Table

class astropy.table.Table(data=None, masked=None, names=None, dtype=None, meta=None, copy=True, rows=None)

Bases: object

A class to represent tables of heterogeneous data.

Table provides a class for heterogeneous tabular data, making use of a numpy structured array internally to store the data values. A key enhancement provided by the Table class is the ability to easily modify the structure of the table by adding or removing columns, or adding new rows of data. In addition table and column metadata are fully supported.

Table differs from NDData by the assumption that the input data consists of columns of homogeneous data, where each column has a unique identifier and may contain additional metadata such as the data unit, format, and description.

Parameters:

data : numpy ndarray, dict, list, or Table, optional

Data to initialize table.

masked : bool, optional

Specify whether the table is masked.

names : list, optional

Specify column names

dtype : list, optional

Specify column data types

meta : dict, optional

Metadata associated with the table.

copy : bool, optional

Copy the input data (default=True).

rows : numpy ndarray, list of lists, optional

Row-oriented data for table instead of data argument

Attributes Summary

ColumnClass
colnames
dtype
groups
mask
masked

Methods Summary

add_column(col[, index])	Add a new Column object col to the table.
add_columns(cols[, indexes])	Add a list of new Column objects cols to the table.
add_row([vals, mask])	Add a new row to the end of the table.
argsort([keys, kind])	Return the indices which would sort the table according to one or more key columns.
convert_bytestring_to_unicode([python3_only])	Convert bytestring columns (dtype.kind=’S’) to unicode (dtype.kind=’U’) assuming ASCII encoding.
convert_unicode_to_bytestring([python3_only])	Convert ASCII-only unicode columns (dtype.kind=’U’) to bytestring (dtype.kind=’S’).
copy([copy_data])	Return a copy of the table.
create_mask()
field(item)	Return column[item] for recarray compatibility.
filled([fill_value])	Return a copy of self, with masked values filled.
group_by(keys)	Group this table by the specified keys This effectively splits the table into groups which correspond to unique values of the keys grouping object.
index_column(name)	Return the positional index of column name.
keep_columns(names)	Keep only the columns specified (remove the others).
keys()
more([max_lines, max_width, show_name, ...])	Interactively browse table with a paging interface.
next()	Python 3 iterator
pformat([max_lines, max_width, show_name, ...])	Return a list of lines for the formatted string representation of the table.
pprint([max_lines, max_width, show_name, ...])	Print a formatted string representation of the table.
read(*args, **kwargs)	Read and parse a data table and return as a Table.
remove_column(name)	Remove a column from the table.
remove_columns(names)	Remove several columns from the table.
remove_row(index)	Remove a row from the table.
remove_rows(row_specifier)	Remove rows from the table.
rename_column(name, new_name)	Rename a column.
reverse()	Reverse the row order of table rows.
show_in_browser([css, max_lines, jsviewer, ...])	Render the table in HTML and show it in a web browser.
sort(keys)	Sort the table according to one or more keys.
write(*args, **kwargs)	Write this Table object out in the specified format.

Attributes Documentation

ColumnClass

colnames

dtype

groups

mask

masked

Methods Documentation

add_column(col, index=None)

Add a new Column object col to the table. If index is supplied then insert column before index position in the list of columns, otherwise append column to the end of the list.

Parameters:

col : Column

Column object to add.

index : int or None

Insert column before this position or at end (default)

Examples

Create a table with two columns ‘a’ and ‘b’:

>>> t = Table([[1, 2, 3], [0.1, 0.2, 0.3]], names=('a', 'b'))
>>> print(t)
 a   b
--- ---
  1 0.1
  2 0.2
  3 0.3

Create a third column ‘c’ and append it to the end of the table:

>>> col_c = Column(name='c', data=['x', 'y', 'z'])
>>> t.add_column(col_c)
>>> print(t)
 a   b   c
--- --- ---
  1 0.1   x
  2 0.2   y
  3 0.3   z

Add column ‘d’ at position 1. Note that the column is inserted before the given index:

>>> col_d = Column(name='d', data=['a', 'b', 'c'])
>>> t.add_column(col_d, 1)
>>> print(t)
 a   d   b   c
--- --- --- ---
  1   a 0.1   x
  2   b 0.2   y
  3   c 0.3   z

To add several columns use add_columns.

add_columns(cols, indexes=None)

Add a list of new Column objects cols to the table. If a corresponding list of indexes is supplied then insert column before each index position in the original list of columns, otherwise append columns to the end of the list.

Parameters:

cols : list of Columns

Column objects to add.

indexes : list of ints or None

Insert column before this position or at end (default)

Examples

Create a table with two columns ‘a’ and ‘b’:

>>> t = Table([[1, 2, 3], [0.1, 0.2, 0.3]], names=('a', 'b'))
>>> print(t)
 a   b
--- ---
  1 0.1
  2 0.2
  3 0.3

Create column ‘c’ and ‘d’ and append them to the end of the table:

>>> col_c = Column(name='c', data=['x', 'y', 'z'])
>>> col_d = Column(name='d', data=['u', 'v', 'w'])
>>> t.add_columns([col_c, col_d])
>>> print(t)
 a   b   c   d
--- --- --- ---
  1 0.1   x   u
  2 0.2   y   v
  3 0.3   z   w

Add column ‘c’ at position 0 and column ‘d’ at position 1. Note that the columns are inserted before the given position:

>>> t = Table([[1, 2, 3], [0.1, 0.2, 0.3]], names=('a', 'b'))
>>> col_c = Column(name='c', data=['x', 'y', 'z'])
>>> col_d = Column(name='d', data=['u', 'v', 'w'])
>>> t.add_columns([col_c, col_d], [0, 1])
>>> print(t)
 c   a   d   b
--- --- --- ---
  x   1   u 0.1
  y   2   v 0.2
  z   3   w 0.3

add_row(vals=None, mask=None)

Add a new row to the end of the table.

The vals argument can be:

sequence (e.g. tuple or list)

Column values in the same order as table columns.

mapping (e.g. dict)

Keys corresponding to column names. Missing values will be filled with np.zeros for the column dtype.

None

All values filled with np.zeros for the column dtype.

This method requires that the Table object “owns” the underlying array data. In particular one cannot add a row to a Table that was initialized with copy=False from an existing array.

The mask attribute should give (if desired) the mask for the values. The type of the mask should match that of the values, i.e. if vals is an iterable, then mask should also be an iterable with the same length, and if vals is a mapping, then mask should be a dictionary.

Parameters:

vals : tuple, list, dict or None

Use the specified values in the new row

mask : tuple, list, dict or None

Use the specified mask values in the new row

Examples

Create a table with three columns ‘a’, ‘b’ and ‘c’:

>>> t = Table([[1,2],[4,5],[7,8]], names=('a','b','c'))
>>> print(t)
 a   b   c
--- --- ---
  1   4   7
  2   5   8

Adding a new row with entries ‘3’ in ‘a’, ‘6’ in ‘b’ and ‘9’ in ‘c’:

>>> t.add_row([3,6,9])
>>> print(t)
  a   b   c
  --- --- ---
  1   4   7
  2   5   8
  3   6   9

argsort(keys=None, kind=None)

Return the indices which would sort the table according to one or more key columns. This simply calls the numpy.argsort function on the table with the order parameter set to keys.

Parameters:

keys : str or list of str

The column name(s) to order the table by

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm.

Returns:

index_array : ndarray, int

Array of indices that sorts the table by the specified key column(s).

convert_bytestring_to_unicode(python3_only=False)

Convert bytestring columns (dtype.kind=’S’) to unicode (dtype.kind=’U’) assuming ASCII encoding.

Internally this changes string columns to represent each character in the string with a 4-byte UCS-4 equivalent, so it is inefficient for memory but allows Python 3 scripts to manipulate string arrays with natural syntax.

The python3_only parameter is provided as a convenience so that code can be written in a Python 2 / 3 compatible way:

>>> t = Table.read('my_data.fits')
>>> t.convert_bytestring_to_unicode(python3_only=True)

Parameters:

python3_only : bool

Only do this operation for Python 3

convert_unicode_to_bytestring(python3_only=False)

Convert ASCII-only unicode columns (dtype.kind=’U’) to bytestring (dtype.kind=’S’).

When exporting a unicode string array to a file in Python 3, it may be desirable to encode unicode columns as bytestrings. This routine takes advantage of numpy automated conversion which works for strings that are pure ASCII.

The python3_only parameter is provided as a convenience so that code can be written in a Python 2 / 3 compatible way:

>>> t.convert_unicode_to_bytestring(python3_only=True)
>>> t.write('my_data.fits')

Parameters:

python3_only : bool

Only do this operation for Python 3

copy(copy_data=True)

Return a copy of the table.

Parameters:

copy_data : bool

If True (the default), copy the underlying data array. Otherwise, use the same data array

create_mask()

field(item)

Return column[item] for recarray compatibility.

filled(fill_value=None)

Return a copy of self, with masked values filled.

If input fill_value supplied then that value is used for all masked entries in the table. Otherwise the individual fill_value defined for each table column is used.

Parameters:

fill_value : str

If supplied, this fill_value is used for all masked entries in the entire table.

Returns:

filled_table : Table

New table with masked values filled

group_by(keys)

Group this table by the specified keys

This effectively splits the table into groups which correspond to unique values of the keys grouping object. The output is a new TableGroups which contains a copy of this table but sorted by row according to keys.

The keys input to group_by can be specified in different ways:

• String or list of strings corresponding to table column name(s)
• Numpy array (homogeneous or structured) with same length as this table
• Table with same length as this table

Parameters:

keys : str, list of str, numpy array, or Table

Key grouping object

Returns:

out : Table

New table with groups set

index_column(name)

Return the positional index of column name.

Parameters:

name : str

column name

Returns:

index : int

Positional index of column name.

Examples

Create a table with three columns ‘a’, ‘b’ and ‘c’:

>>> t = Table([[1, 2, 3], [0.1, 0.2, 0.3], ['x', 'y', 'z']],
...           names=('a', 'b', 'c'))
>>> print(t)
 a   b   c
--- --- ---
  1 0.1   x
  2 0.2   y
  3 0.3   z

Get index of column ‘b’ of the table:

>>> t.index_column('b')
1

keep_columns(names)

Keep only the columns specified (remove the others).

Parameters:

names : list

A list containing the names of the columns to keep. All other columns will be removed.

Examples

Create a table with three columns ‘a’, ‘b’ and ‘c’:

>>> t = Table([[1, 2, 3],[0.1, 0.2, 0.3],['x', 'y', 'z']],
...           names=('a', 'b', 'c'))
>>> print(t)
 a   b   c
--- --- ---
  1 0.1   x
  2 0.2   y
  3 0.3   z

Specifying only a single column name keeps only this column. Keep only column ‘a’ of the table:

>>> t.keep_columns('a')
>>> print(t)
 a
---
  1
  2
  3

Specifying a list of column names is keeps is also possible. Keep columns ‘a’ and ‘c’ of the table:

>>> t = Table([[1, 2, 3],[0.1, 0.2, 0.3],['x', 'y', 'z']],
...           names=('a', 'b', 'c'))
>>> t.keep_columns(['a', 'c'])
>>> print(t)
 a   c
--- ---
  1   x
  2   y
  3   z

keys()

more(max_lines=None, max_width=None, show_name=True, show_unit=None)

Interactively browse table with a paging interface.

Supported keys:

f, <space> : forward one page
b : back one page
r : refresh same page
n : next row
p : previous row
< : go to beginning
> : go to end
q : quit browsing
h : print this help

Parameters:

max_lines : int

Maximum number of lines in table output

max_width : int or None

Maximum character width of output

show_name : bool

Include a header row for column names (default=True)

show_unit : bool

Include a header row for unit. Default is to show a row for units only if one or more columns has a defined value for the unit.

next()

Python 3 iterator

pformat(max_lines=None, max_width=None, show_name=True, show_unit=None, html=False, tableid=None)

Return a list of lines for the formatted string representation of the table.

If no value of max_lines is supplied then the height of the screen terminal is used to set max_lines. If the terminal height cannot be determined then the default is taken from the configuration item astropy.conf.max_lines. If a negative value of max_lines is supplied then there is no line limit applied.

The same applies for max_width except the configuration item is astropy.conf.max_width.

Parameters:

max_lines : int or None

Maximum number of rows to output

max_width : int or None

Maximum character width of output

show_name : bool

Include a header row for column names (default=True)

show_unit : bool

Include a header row for unit. Default is to show a row for units only if one or more columns has a defined value for the unit.

html : bool

Format the output as an HTML table (default=False)

tableid : str or None

An ID tag for the table; only used if html is set. Default is “table{id}”, where id is the unique integer id of the table object, id(self)

Returns:

lines : list

Formatted table as a list of strings

pprint(max_lines=None, max_width=None, show_name=True, show_unit=None)

Print a formatted string representation of the table.

If no value of max_lines is supplied then the height of the screen terminal is used to set max_lines. If the terminal height cannot be determined then the default is taken from the configuration item astropy.conf.max_lines. If a negative value of max_lines is supplied then there is no line limit applied.

The same applies for max_width except the configuration item is astropy.conf.max_width.

Parameters:

max_lines : int

Maximum number of lines in table output

max_width : int or None

Maximum character width of output

show_name : bool

Include a header row for column names (default=True)

show_unit : bool

Include a header row for unit. Default is to show a row for units only if one or more columns has a defined value for the unit.

classmethod read(*args, **kwargs)

Read and parse a data table and return as a Table.

This function provides the Table interface to the astropy unified I/O layer. This allows easily reading a file in many supported data formats using syntax such as:

>>> from astropy.table import Table
>>> dat = Table.read('table.dat', format='ascii')
>>> events = Table.read('events.fits', format='fits')

The arguments and keywords (other than format) provided to this function are passed through to the underlying data reader (e.g. read).

The available built-in formats are:

Format	Read	Write	Auto-identify	Deprecated
ascii	Yes	Yes	No
ascii.aastex	Yes	Yes	No
ascii.basic	Yes	Yes	No
ascii.cds	Yes	No	No
ascii.commented_header	Yes	Yes	No
ascii.csv	Yes	Yes	Yes
ascii.daophot	Yes	No	No
ascii.fixed_width	Yes	Yes	No
ascii.fixed_width_no_header	Yes	Yes	No
ascii.fixed_width_two_line	Yes	Yes	No
ascii.html	Yes	Yes	Yes
ascii.ipac	Yes	Yes	No
ascii.latex	Yes	Yes	Yes
ascii.no_header	Yes	Yes	No
ascii.rdb	Yes	Yes	Yes
ascii.sextractor	Yes	No	No
ascii.tab	Yes	Yes	No
fits	Yes	Yes	Yes
hdf5	Yes	Yes	Yes
votable	Yes	No	No
aastex	Yes	Yes	No	Yes
cds	Yes	No	No	Yes
daophot	Yes	No	No	Yes
html	Yes	Yes	No	Yes
ipac	Yes	Yes	No	Yes
latex	Yes	Yes	No	Yes
rdb	Yes	Yes	No	Yes

Deprecated format names like aastex will be removed in a future version. Use the full name (e.g. ascii.aastex) instead.

remove_column(name)

Remove a column from the table.

This can also be done with:

del table[name]

Parameters:

name : str

Name of column to remove

Examples

Create a table with three columns ‘a’, ‘b’ and ‘c’:

>>> t = Table([[1, 2, 3], [0.1, 0.2, 0.3], ['x', 'y', 'z']],
...           names=('a', 'b', 'c'))
>>> print(t)
 a   b   c
--- --- ---
  1 0.1   x
  2 0.2   y
  3 0.3   z

Remove column ‘b’ from the table:

>>> t.remove_column('b')
>>> print(t)
 a   c
--- ---
  1   x
  2   y
  3   z

To remove several columns at the same time use remove_columns.

remove_columns(names)

Remove several columns from the table.

Parameters:

names : list

A list containing the names of the columns to remove

Examples

Create a table with three columns ‘a’, ‘b’ and ‘c’:

>>> t = Table([[1, 2, 3], [0.1, 0.2, 0.3], ['x', 'y', 'z']],
...     names=('a', 'b', 'c'))
>>> print(t)
 a   b   c
--- --- ---
  1 0.1   x
  2 0.2   y
  3 0.3   z

Remove columns ‘b’ and ‘c’ from the table:

>>> t.remove_columns(['b', 'c'])
>>> print(t)
 a
---
  1
  2
  3

Specifying only a single column also works. Remove column ‘b’ from the table:

>>> t = Table([[1, 2, 3], [0.1, 0.2, 0.3], ['x', 'y', 'z']],
...     names=('a', 'b', 'c'))
>>> t.remove_columns('b')
>>> print(t)
 a   c
--- ---
  1   x
  2   y
  3   z

This gives the same as using remove_column.

remove_row(index)

Remove a row from the table.

Parameters:

index : int

Index of row to remove

Examples

Create a table with three columns ‘a’, ‘b’ and ‘c’:

>>> t = Table([[1, 2, 3], [0.1, 0.2, 0.3], ['x', 'y', 'z']],
...           names=('a', 'b', 'c'))
>>> print(t)
 a   b   c
--- --- ---
  1 0.1   x
  2 0.2   y
  3 0.3   z

Remove row 1 from the table:

>>> t.remove_row(1)
>>> print(t)
 a   b   c
--- --- ---
  1 0.1   x
  3 0.3   z

To remove several rows at the same time use remove_rows.

remove_rows(row_specifier)

Remove rows from the table.

Parameters:

row_specifier : slice, int, or array of ints

Specification for rows to remove

Examples

Create a table with three columns ‘a’, ‘b’ and ‘c’:

>>> t = Table([[1, 2, 3], [0.1, 0.2, 0.3], ['x', 'y', 'z']],
...           names=('a', 'b', 'c'))
>>> print(t)
 a   b   c
--- --- ---
  1 0.1   x
  2 0.2   y
  3 0.3   z

Remove rows 0 and 2 from the table:

>>> t.remove_rows([0, 2])
>>> print(t)
 a   b   c
--- --- ---
  2 0.2   y

Note that there are no warnings if the slice operator extends outside the data:

>>> t = Table([[1, 2, 3], [0.1, 0.2, 0.3], ['x', 'y', 'z']],
...           names=('a', 'b', 'c'))
>>> t.remove_rows(slice(10, 20, 1))
>>> print(t)
 a   b   c
--- --- ---
  1 0.1   x
  2 0.2   y
  3 0.3   z

rename_column(name, new_name)

Rename a column.

This can also be done directly with by setting the name attribute for a column:

table[name].name = new_name

Parameters:

name : str

The current name of the column.

new_name : str

The new name for the column

Examples

Create a table with three columns ‘a’, ‘b’ and ‘c’:

>>> t = Table([[1,2],[3,4],[5,6]], names=('a','b','c'))
>>> print(t)
 a   b   c
--- --- ---
  1   3   5
  2   4   6

Renaming column ‘a’ to ‘aa’:

>>> t.rename_column('a' , 'aa')
>>> print(t)
 aa  b   c
--- --- ---
  1   3   5
  2   4   6

reverse()

Reverse the row order of table rows. The table is reversed in place and there are no function arguments.

Examples

Create a table with three columns:

>>> t = Table([['Max', 'Jo', 'John'], ['Miller','Miller','Jackson'],
...         [12,15,18]], names=('firstname','name','tel'))
>>> print(t)
firstname   name  tel
--------- ------- ---
      Max  Miller  12
       Jo  Miller  15
     John Jackson  18

Reversing order:

>>> t.reverse()
>>> print(t)
firstname   name  tel
--------- ------- ---
     John Jackson  18
       Jo  Miller  15
      Max  Miller  12

show_in_browser(css=u'table, th, td, tr, tbody {border: 1px solid black; border-collapse: collapse;}', max_lines=5000, jsviewer=False, jskwargs={}, tableid=None, browser=u'default')

Render the table in HTML and show it in a web browser. In order to make a persistent html file, i.e. one that survives refresh, the returned file object must be kept in memory.

Parameters:

css : string

A valid CSS string declaring the formatting for the table

max_lines : int

Maximum number of rows to export to the table (set low by default to avoid memory issues, since the browser view requires duplicating the table in memory). A negative value of max_lines indicates no row limit

jsviewer : bool

If True, prepends some javascript headers so that the table is rendered as a https://datatables.net data table. This allows in-browser searching & sorting. See JSViewer

jskwargs : dict

Passed to the JSViewer init.

tableid : str or None

An html ID tag for the table. Default is “table{id}”, where id is the unique integer id of the table object, id(self).

browser : str

Any legal browser name, e.g. 'firefox', 'chrome', 'safari' (for mac, you may need to use 'open -a "/Applications/Google Chrome.app" %s' for Chrome). If 'default', will use the system default browser.

Returns:

file :

A NamedTemporaryFile object pointing to the html file on disk.

sort(keys)

Sort the table according to one or more keys. This operates on the existing table and does not return a new table.

Parameters:

keys : str or list of str

The key(s) to order the table by

Examples

Create a table with 3 columns:

>>> t = Table([['Max', 'Jo', 'John'], ['Miller','Miller','Jackson'],
...         [12,15,18]], names=('firstname','name','tel'))
>>> print(t)
firstname   name  tel
--------- ------- ---
      Max  Miller  12
       Jo  Miller  15
     John Jackson  18

Sorting according to standard sorting rules, first ‘name’ then ‘firstname’:

>>> t.sort(['name','firstname'])
>>> print(t)
firstname   name  tel
--------- ------- ---
     John Jackson  18
       Jo  Miller  15
      Max  Miller  12

write(*args, **kwargs)

Write this Table object out in the specified format.

This function provides the Table interface to the astropy unified I/O layer. This allows easily writing a file in many supported data formats using syntax such as:

>>> from astropy.table import Table
>>> dat = Table([[1, 2], [3, 4]], names=('a', 'b'))
>>> dat.write('table.dat', format='ascii')

The arguments and keywords (other than format) provided to this function are passed through to the underlying data reader (e.g. write).

The available built-in formats are:

Format	Read	Write	Auto-identify	Deprecated
ascii	Yes	Yes	No
ascii.aastex	Yes	Yes	No
ascii.basic	Yes	Yes	No
ascii.commented_header	Yes	Yes	No
ascii.csv	Yes	Yes	Yes
ascii.fixed_width	Yes	Yes	No
ascii.fixed_width_no_header	Yes	Yes	No
ascii.fixed_width_two_line	Yes	Yes	No
ascii.html	Yes	Yes	Yes
ascii.ipac	Yes	Yes	No
ascii.latex	Yes	Yes	Yes
ascii.no_header	Yes	Yes	No
ascii.rdb	Yes	Yes	Yes
ascii.tab	Yes	Yes	No
fits	Yes	Yes	Yes
hdf5	Yes	Yes	Yes
votable	Yes	Yes	No
aastex	Yes	Yes	No	Yes
html	Yes	Yes	No	Yes
ipac	Yes	Yes	No	Yes
latex	Yes	Yes	No	Yes
rdb	Yes	Yes	No	Yes

Deprecated format names like aastex will be removed in a future version. Use the full name (e.g. ascii.aastex) instead.