Table¶
-
class
astropy.table.
Table
(data=None, masked=None, names=None, dtype=None, meta=None, copy=True, rows=None)[source] [edit on github]¶ Bases:
object
A class to represent tables of heterogeneous data.
Table
provides a class for heterogeneous tabular data, making use of anumpy
structured array internally to store the data values. A key enhancement provided by theTable
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 fromNDData
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
argumentAttributes Summary
ColumnClass
colnames
dtype
groups
has_mixin_columns
True if table has any mixin columns (defined as columns that are not Column mask
masked
Methods Summary
Attributes Documentation
-
ColumnClass
¶
-
colnames
¶
-
dtype
¶
-
groups
¶
-
has_mixin_columns
¶ True if table has any mixin columns (defined as columns that are not Column subclasses)
-
mask
¶
-
masked
¶
Methods Documentation
-
add_column
(col, index=None)[source] [edit on github]¶ Add a new Column object
col
to the table. Ifindex
is supplied then insert column beforeindex
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, copy=True)[source] [edit on github]¶ Add a list of new Column objects
cols
to the table. If a corresponding list ofindexes
is supplied then insert column before eachindex
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)
copy : bool
Make a copy of the new columns (default=True)
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)[source] [edit on github]¶ 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. ifvals
is an iterable, thenmask
should also be an iterable with the same length, and ifvals
is a mapping, thenmask
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)[source] [edit on github]¶ 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 theorder
parameter set tokeys
.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).
-
as_array
()[source] [edit on github]¶ Return a new copy of the table in the form of a structured np.ndarray or np.ma.MaskedArray object (as appropriate).
Returns: table_array : np.ndarray (unmasked) or np.ma.MaskedArray (masked)
Copy of table as a numpy structured array
-
convert_bytestring_to_unicode
(python3_only=False)[source] [edit on github]¶ 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)[source] [edit on github]¶ 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)[source] [edit on github]¶ 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
-
field
(item)[source] [edit on github]¶ Return column[item] for recarray compatibility.
-
filled
(fill_value=None)[source] [edit on github]¶ 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 individualfill_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)[source] [edit on github]¶ 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 newTableGroups
which contains a copy of this table but sorted by row according tokeys
.The
keys
input togroup_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)[source] [edit on github]¶ 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
-
insert_row
(index, vals=None, mask=None)[source] [edit on github]¶ Add a new row before the given
index
position in 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.
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. ifvals
is an iterable, thenmask
should also be an iterable with the same length, and ifvals
is a mapping, thenmask
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
-
keep_columns
(names)[source] [edit on github]¶ 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
()[source] [edit on github]¶
-
more
(max_lines=None, max_width=None, show_name=True, show_unit=None, show_dtype=False)[source] [edit on github]¶ 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.
show_dtype : bool
Include a header row for column dtypes (default=True)
-
pformat
(max_lines=None, max_width=None, show_name=True, show_unit=None, show_dtype=False, html=False, tableid=None)[source] [edit on github]¶ 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 setmax_lines
. If the terminal height cannot be determined then the default is taken from the configuration itemastropy.conf.max_lines
. If a negative value ofmax_lines
is supplied then there is no line limit applied.The same applies for
max_width
except the configuration item isastropy.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.
show_dtype : bool
Include a header row for column dtypes (default=True)
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, show_dtype=False)[source] [edit on github]¶ 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 setmax_lines
. If the terminal height cannot be determined then the default is taken from the configuration itemastropy.conf.max_lines
. If a negative value ofmax_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.
show_dtype : bool
Include a header row for column dtypes (default=True)
-
classmethod
read
(*args, **kwargs)[source] [edit on github]¶ 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 No ascii.daophot Yes No No ascii.ecsv Yes Yes No ascii.fast_basic Yes Yes No ascii.fast_commented_header Yes Yes No ascii.fast_csv Yes Yes No ascii.fast_no_header Yes Yes No ascii.fast_rdb Yes Yes No ascii.fast_tab Yes Yes 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 csv Yes Yes Yes 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)[source] [edit on github]¶ 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)[source] [edit on github]¶ 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)[source] [edit on github]¶ 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)[source] [edit on github]¶ 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)[source] [edit on github]¶ Rename a column.
This can also be done directly with by setting the
name
attribute for a column:table[name].name = new_name
TODO: this won’t work for mixins
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
()[source] [edit on github]¶ 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={u'use_local_files': True}, tableid=None, browser=u'default')[source] [edit on github]¶ Render the table in HTML and show it in a web browser.
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 DataTables data table. This allows in-browser searching & sorting.jskwargs : dict
Passed to the
astropy.table.JSViewer
init. Default to{'use_local_files': True}
which means that the JavaScipt librairies will be served from local copies.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.
-
sort
(keys)[source] [edit on github]¶ 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)[source] [edit on github]¶ 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 No ascii.ecsv Yes Yes No ascii.fast_basic Yes Yes No ascii.fast_commented_header Yes Yes No ascii.fast_csv Yes Yes No ascii.fast_no_header Yes Yes No ascii.fast_rdb Yes Yes No ascii.fast_tab Yes Yes 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.tab Yes Yes No fits Yes Yes Yes hdf5 Yes Yes Yes jsviewer No Yes No votable Yes Yes No aastex Yes Yes No Yes csv Yes Yes Yes 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.
-