Table#
- class astropy.table.Table(data=None, masked=False, names=None, dtype=None, meta=None, copy=True, rows=None, copy_indices=True, units=None, descriptions=None, **kwargs)[source]#
Bases:
object
A class to represent tables of heterogeneous data.
Table
provides a class for heterogeneous tabular data. A key enhancement provided by theTable
class over e.g. anumpy
structured array 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.See also: https://docs.astropy.org/en/stable/table/
- Parameters:
- data
numpy
ndarray
,dict
,list
, astropy:table-likeobject
, optional Data to initialize table.
- maskedbool, 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.
- copybool, optional
Copy the input column data and make a deep copy of the input meta. Default is True.
- rows
numpy
ndarray
,list
oflist
, optional Row-oriented data for table instead of
data
argument.- copy_indicesbool, optional
Copy any indices in the input data. Default is True.
- units
list
,dict
, optional List or dict of units to apply to columns.
- descriptions
list
,dict
, optional List or dict of descriptions to apply to columns.
- **kwargs
dict
, optional Additional keyword args when converting table-like object.
- data
Attributes Summary
True if table has any
MaskedColumn
columns.True if column in the table has values which are masked.
True if table has any mixin columns (defined as columns that are not Column subclasses).
Return a TableILoc object that can be used for retrieving indexed rows in the order they appear in the index.
Return the indices associated with columns of the table as a TableIndices object.
Return a TableLoc object that can be used for retrieving rows by index in a given data range.
Return a TableLocIndices object that can be used for retrieving the row indices corresponding to given table index key value or values.
Maintain tuple that controls table column visibility for print output.
Maintain tuple that controls table column visibility for print output.
Read and parse a data table and return as a Table.
Write this Table object out in the specified format.
Methods Summary
add_column
(col[, index, name, ...])Add a new column to the table using
col
as input.add_columns
(cols[, indexes, names, copy, ...])Add a list of new columns the table using
cols
data objects.add_index
(colnames[, engine, unique])Insert a new index among one or more columns.
add_row
([vals, mask])Add a new row to the end of the table.
argsort
([keys, kind, reverse])Return the indices which would sort the table according to one or more key columns.
as_array
([keep_byteorder, names])Return a new copy of the table in the form of a structured np.ndarray or np.ma.MaskedArray object (as appropriate).
Convert bytestring columns (dtype.kind='S') to unicode (dtype.kind='U') using UTF-8 encoding.
Convert unicode columns (dtype.kind='U') to bytestring (dtype.kind='S') using UTF-8 encoding.
copy
([copy_data])Return a copy of the table.
field
(item)Return column[item] for recarray compatibility.
filled
([fill_value])Return copy of self, with masked values filled.
from_pandas
(dataframe[, index, units])Create a
Table
from apandas.DataFrame
instance.group_by
(keys)Group this table by the specified
keys
.index_column
(name)Return the positional index of column
name
.index_mode
(mode)Return a context manager for an indexing mode.
insert_row
(index[, vals, mask])Add a new row before the given
index
position in the table.items
()itercols
()Iterate over the columns of this table.
iterrows
(*names)Iterate over rows of table returning a tuple of values for each row.
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.
pformat
([max_lines, max_width, show_name, ...])Return a list of lines for the formatted string representation of
pformat_all
([max_lines, max_width, ...])Return a list of lines for the formatted string representation of
pprint
([max_lines, max_width, show_name, ...])Print a formatted string representation of the table.
pprint_all
([max_lines, max_width, ...])Print a formatted string representation of the entire table.
remove_column
(name)Remove a column from the table.
remove_columns
(names)Remove several columns from the table.
remove_indices
(colname)Remove all indices involving the given column.
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.
rename_columns
(names, new_names)Rename multiple columns.
replace_column
(name, col[, copy])Replace column
name
with the newcol
object.reverse
()Reverse the row order of table rows.
round
([decimals])Round numeric columns in-place to the specified number of decimals.
setdefault
(name, default)Ensure a column named
name
exists.show_in_browser
([max_lines, jsviewer, ...])show_in_notebook
([tableid, css, ...])sort
([keys, kind, reverse])Sort the table according to one or more keys.
to_pandas
([index, use_nullable_int])Return a
pandas.DataFrame
instance.update
(other[, copy])Perform a dictionary-style update and merge metadata.
values
()values_equal
(other)Element-wise comparison of table with another table, list, or scalar.
Attributes Documentation
- ColumnClass#
- colnames#
- dtype#
- groups#
- has_masked_columns#
True if table has any
MaskedColumn
columns.This does not check for mixin columns that may have masked values, use the
has_masked_values
property in that case.
- has_masked_values#
True if column in the table has values which are masked.
This may be relatively slow for large tables as it requires checking the mask values of each column.
- has_mixin_columns#
True if table has any mixin columns (defined as columns that are not Column subclasses).
- iloc#
Return a TableILoc object that can be used for retrieving indexed rows in the order they appear in the index.
- indices#
Return the indices associated with columns of the table as a TableIndices object.
- info#
- loc#
Return a TableLoc object that can be used for retrieving rows by index in a given data range. Note that both loc and iloc work only with single-column indices.
- loc_indices#
Return a TableLocIndices object that can be used for retrieving the row indices corresponding to given table index key value or values.
- mask#
- masked#
- meta = None#
- pprint_exclude_names#
Maintain tuple that controls table column visibility for print output.
This is a descriptor that inherits from MetaAttribute so that the attribute value is stored in the table meta[‘__attributes__’].
This gets used for the
pprint_include_names
andpprint_exclude_names
Table attributes.
- pprint_include_names#
Maintain tuple that controls table column visibility for print output.
This is a descriptor that inherits from MetaAttribute so that the attribute value is stored in the table meta[‘__attributes__’].
This gets used for the
pprint_include_names
andpprint_exclude_names
Table attributes.
- read#
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')
Get help on the available readers for
Table
using the``help()`` method:>>> Table.read.help() # Get help reading Table and list supported formats >>> Table.read.help('fits') # Get detailed help on Table FITS reader >>> Table.read.list_formats() # Print list of available formats
See also: https://docs.astropy.org/en/stable/io/unified.html
- Parameters:
- *args
tuple
, optional Positional arguments passed through to data reader. If supplied the first argument is typically the input filename.
- format
str
File format specifier.
- units
list
,dict
, optional List or dict of units to apply to columns
- descriptions
list
,dict
, optional List or dict of descriptions to apply to columns
- **kwargs
dict
, optional Keyword arguments passed through to data reader.
- *args
- Returns:
- out
Table
Table corresponding to file contents
- out
- write#
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')
Get help on the available writers for
Table
using the``help()`` method:>>> Table.write.help() # Get help writing Table and list supported formats >>> Table.write.help('fits') # Get detailed help on Table FITS writer >>> Table.write.list_formats() # Print list of available formats
The
serialize_method
argument is explained in the section on Table serialization methods.See also: https://docs.astropy.org/en/stable/io/unified.html
- Parameters:
- *args
tuple
, optional Positional arguments passed through to data writer. If supplied the first argument is the output filename.
- format
str
File format specifier.
- serialize_method
str
,dict
, optional Serialization method specifier for columns.
- **kwargs
dict
, optional Keyword arguments passed through to data writer.
- *args
Methods Documentation
- add_column(col, index=None, name=None, rename_duplicate=False, copy=True, default_name=None)[source]#
Add a new column to the table using
col
as input. Ifindex
is supplied then insert column beforeindex
position in the list of columns, otherwise append column to the end of the list.The
col
input can be any data object which is acceptable as aTable
column object or can be converted. This includes mixin columns and scalar or length=1 objects which get broadcast to match the table length.To add several columns at once use
add_columns()
or simply calladd_column()
for each one. There is very little performance difference in the two approaches.- Parameters:
- col
object
Data object for the new column
- index
int
orNone
Insert column before this position or at end (default).
- name
str
Column name
- rename_duplicatebool
Uniquify column name if it already exist. Default is False.
- copybool
Make a copy of the new column. Default is True.
- default_name
str
orNone
Name to use if both
name
andcol.info.name
are not available. Defaults tocol{number_of_columns}
.
- col
Examples
Create a table with two columns ‘a’ and ‘b’, then create a third column ‘c’ and append it to the end of the table:
>>> t = Table([[1, 2], [0.1, 0.2]], names=('a', 'b')) >>> col_c = Column(name='c', data=['x', 'y']) >>> t.add_column(col_c) >>> print(t) a b c --- --- --- 1 0.1 x 2 0.2 y
Add column ‘d’ at position 1. Note that the column is inserted before the given index:
>>> t.add_column(['a', 'b'], name='d', index=1) >>> print(t) a d b c --- --- --- --- 1 a 0.1 x 2 b 0.2 y
Add second column named ‘b’ with rename_duplicate:
>>> t = Table([[1, 2], [0.1, 0.2]], names=('a', 'b')) >>> t.add_column(1.1, name='b', rename_duplicate=True) >>> print(t) a b b_1 --- --- --- 1 0.1 1.1 2 0.2 1.1
Add an unnamed column or mixin object in the table using a default name or by specifying an explicit name with
name
. Name can also be overridden:>>> t = Table([[1, 2], [0.1, 0.2]], names=('a', 'b')) >>> t.add_column(['a', 'b']) >>> t.add_column(col_c, name='d') >>> print(t) a b col2 d --- --- ---- --- 1 0.1 a x 2 0.2 b y
- add_columns(cols, indexes=None, names=None, copy=True, rename_duplicate=False)[source]#
Add a list of new columns the table using
cols
data objects. 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.The
cols
input can include any data objects which are acceptable asTable
column objects or can be converted. This includes mixin columns and scalar or length=1 objects which get broadcast to match the table length.From a performance perspective there is little difference between calling this method once or looping over the new columns and calling
add_column()
for each column.- Parameters:
- cols
list
ofobject
List of data objects for the new columns
- indexes
list
ofint
orNone
Insert column before this position or at end (default).
- names
list
ofstr
Column names
- copybool
Make a copy of the new columns. Default is True.
- rename_duplicatebool
Uniquify new column names if they duplicate the existing ones. Default is False.
- cols
See also
Examples
Create a table with two columns ‘a’ and ‘b’, then create columns ‘c’ and ‘d’ and append them to the end of the table:
>>> t = Table([[1, 2], [0.1, 0.2]], names=('a', 'b')) >>> col_c = Column(name='c', data=['x', 'y']) >>> col_d = Column(name='d', data=['u', 'v']) >>> t.add_columns([col_c, col_d]) >>> print(t) a b c d --- --- --- --- 1 0.1 x u 2 0.2 y v
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], [0.1, 0.2]], names=('a', 'b')) >>> t.add_columns([['x', 'y'], ['u', 'v']], names=['c', 'd'], ... indexes=[0, 1]) >>> print(t) c a d b --- --- --- --- x 1 u 0.1 y 2 v 0.2
Add second column ‘b’ and column ‘c’ with
rename_duplicate
:>>> t = Table([[1, 2], [0.1, 0.2]], names=('a', 'b')) >>> t.add_columns([[1.1, 1.2], ['x', 'y']], names=('b', 'c'), ... rename_duplicate=True) >>> print(t) a b b_1 c --- --- --- --- 1 0.1 1.1 x 2 0.2 1.2 y
Add unnamed columns or mixin objects in the table using default names or by specifying explicit names with
names
. Names can also be overridden:>>> t = Table() >>> col_b = Column(name='b', data=['u', 'v']) >>> t.add_columns([[1, 2], col_b]) >>> t.add_columns([[3, 4], col_b], names=['c', 'd']) >>> print(t) col0 b c d ---- --- --- --- 1 u 3 u 2 v 4 v
- add_index(colnames, engine=None, unique=False)[source]#
Insert a new index among one or more columns. If there are no indices, make this index the primary table index.
- Parameters:
- colnames
str
orlist
List of column names (or a single column name) to index
- enginetype or
None
Indexing engine class to use, either
SortedArray
,BST
, orSCEngine
. If the supplied argument is None (by default), useSortedArray
.- uniquebool
Whether the values of the index must be unique. Default is False.
- colnames
- add_row(vals=None, mask=None)[source]#
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:
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, reverse=False)[source]#
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:
- Returns:
- as_array(keep_byteorder=False, names=None)[source]#
Return a new copy of the table in the form of a structured np.ndarray or np.ma.MaskedArray object (as appropriate).
- Parameters:
- keep_byteorderbool, optional
By default the returned array has all columns in native byte order. However, if this option is
True
this preserves the byte order of all columns (if any are non-native).- names
list
, optional: List of column names to include for returned structured array. Default is to include all table columns.
- Returns:
- table_array
array
orMaskedArray
Copy of table as a numpy structured array. ndarray for unmasked or
MaskedArray
for masked.
- table_array
- convert_bytestring_to_unicode()[source]#
Convert bytestring columns (dtype.kind=’S’) to unicode (dtype.kind=’U’) using UTF-8 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 scripts to manipulate string arrays with natural syntax.
- convert_unicode_to_bytestring()[source]#
Convert unicode columns (dtype.kind=’U’) to bytestring (dtype.kind=’S’) using UTF-8 encoding.
When exporting a unicode string array to a file, it may be desirable to encode unicode columns as bytestrings.
- filled(fill_value=None)[source]#
Return 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.
- classmethod from_pandas(dataframe, index=False, units=None)[source]#
Create a
Table
from apandas.DataFrame
instance.In addition to converting generic numeric or string columns, this supports conversion of pandas Date and Time delta columns to
Time
andTimeDelta
columns, respectively.- Parameters:
- dataframe
pandas.DataFrame
A pandas
pandas.DataFrame
instance- indexbool
Include the index column in the returned table (default=False)
- units: dict
A dict mapping column names to a
Unit
. The columns will have the specified unit in the Table.
- dataframe
- Returns:
- Raises:
ImportError
If pandas is not installed
Examples
Here we convert a
pandas.DataFrame
instance to aQTable
.>>> import numpy as np >>> import pandas as pd >>> from astropy.table import QTable
>>> time = pd.Series(['1998-01-01', '2002-01-01'], dtype='datetime64[ns]') >>> dt = pd.Series(np.array([1, 300], dtype='timedelta64[s]')) >>> df = pd.DataFrame({'time': time}) >>> df['dt'] = dt >>> df['x'] = [3., 4.] >>> with pd.option_context('display.max_columns', 20): ... print(df) time dt x 0 1998-01-01 0 days 00:00:01 3.0 1 2002-01-01 0 days 00:05:00 4.0
>>> QTable.from_pandas(df) <QTable length=2> time dt x Time TimeDelta float64 ----------------------- --------- ------- 1998-01-01T00:00:00.000 1.0 3.0 2002-01-01T00:00:00.000 300.0 4.0
- group_by(keys)[source]#
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
- index_column(name)[source]#
Return the 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
- index_mode(mode)[source]#
Return a context manager for an indexing mode.
- Parameters:
- mode
str
Either ‘freeze’, ‘copy_on_getitem’, or ‘discard_on_copy’. In ‘discard_on_copy’ mode, indices are not copied whenever columns or tables are copied. In ‘freeze’ mode, indices are not modified whenever columns are modified; at the exit of the context, indices refresh themselves based on column values. This mode is intended for scenarios in which one intends to make many additions or modifications in an indexed column. In ‘copy_on_getitem’ mode, indices are copied when taking column slices as well as table slices, so col[i0:i1] will preserve indices.
- mode
- insert_row(index, vals=None, mask=None)[source]#
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.
- itercols()[source]#
Iterate over the columns of this table.
Examples
To iterate over the columns of a table:
>>> t = Table([[1], [2]]) >>> for col in t.itercols(): ... print(col) col0 ---- 1 col1 ---- 2
Using
itercols()
is similar tofor col in t.columns.values()
but is syntactically preferred.
- iterrows(*names)[source]#
Iterate over rows of table returning a tuple of values for each row.
This method is especially useful when only a subset of columns are needed.
The
iterrows
method can be substantially faster than using the standard Table row iteration (e.g.for row in tbl:
), since that returns a new~astropy.table.Row
object for each row and accessing a column in that row (e.g.row['col0']
) is slower than tuple access.- Parameters:
- names
list
List of column names (default to all columns if no names provided)
- names
- Returns:
- rowsiterable
Iterator returns tuples of row values
Examples
Create a table with three columns ‘a’, ‘b’ and ‘c’:
>>> t = Table({'a': [1, 2, 3], ... 'b': [1.0, 2.5, 3.0], ... 'c': ['x', 'y', 'z']})
To iterate row-wise using column names:
>>> for a, c in t.iterrows('a', 'c'): ... print(a, c) 1 x 2 y 3 z
- keep_columns(names)[source]#
Keep only the columns specified (remove the others).
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
Keep only column ‘a’ of the table:
>>> t.keep_columns('a') >>> print(t) a --- 1 2 3
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
- more(max_lines=None, max_width=None, show_name=True, show_unit=None, show_dtype=False)[source]#
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
orNone
Maximum character width of output
- show_namebool
Include a header row for column names. Default is True.
- show_unitbool
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_dtypebool
Include a header row for column dtypes. Default is False.
- max_lines
- pformat(max_lines=None, max_width=None, show_name=True, show_unit=None, show_dtype=False, html=False, tableid=None, align=None, tableclass=None)[source]#
- 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
orNone
Maximum number of rows to output
- max_width
int
orNone
Maximum character width of output
- show_namebool
Include a header row for column names. Default is True.
- show_unitbool
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_dtypebool
Include a header row for column dtypes. Default is True.
- htmlbool
Format the output as an HTML table. Default is False.
- tableid
str
orNone
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)
- align
str
orlist
ortuple
orNone
Left/right alignment of columns. Default is right (None) for all columns. Other allowed values are ‘>’, ‘<’, ‘^’, and ‘0=’ for right, left, centered, and 0-padded, respectively. A list of strings can be provided for alignment of tables with multiple columns.
- tableclass
str
orlist
ofstr
orNone
CSS classes for the table; only used if html is set. Default is None.
- max_lines
- Returns:
- lines
list
Formatted table as a list of strings.
- lines
- pformat_all(max_lines=-1, max_width=-1, show_name=True, show_unit=None, show_dtype=False, html=False, tableid=None, align=None, tableclass=None)[source]#
- Return a list of lines for the formatted string representation of
the entire 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
orNone
Maximum number of rows to output
- max_width
int
orNone
Maximum character width of output
- show_namebool
Include a header row for column names. Default is True.
- show_unitbool
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_dtypebool
Include a header row for column dtypes. Default is True.
- htmlbool
Format the output as an HTML table. Default is False.
- tableid
str
orNone
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)
- align
str
orlist
ortuple
orNone
Left/right alignment of columns. Default is right (None) for all columns. Other allowed values are ‘>’, ‘<’, ‘^’, and ‘0=’ for right, left, centered, and 0-padded, respectively. A list of strings can be provided for alignment of tables with multiple columns.
- tableclass
str
orlist
ofstr
orNone
CSS classes for the table; only used if html is set. Default is None.
- max_lines
- Returns:
- lines
list
Formatted table as a list of strings.
- lines
- pprint(max_lines=None, max_width=None, show_name=True, show_unit=None, show_dtype=False, align=None)[source]#
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
orNone
Maximum number of lines in table output.
- max_width
int
orNone
Maximum character width of output.
- show_namebool
Include a header row for column names. Default is True.
- show_unitbool
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_dtypebool
Include a header row for column dtypes. Default is False.
- align
str
orlist
ortuple
orNone
Left/right alignment of columns. Default is right (None) for all columns. Other allowed values are ‘>’, ‘<’, ‘^’, and ‘0=’ for right, left, centered, and 0-padded, respectively. A list of strings can be provided for alignment of tables with multiple columns.
- max_lines
- pprint_all(max_lines=-1, max_width=-1, show_name=True, show_unit=None, show_dtype=False, align=None)[source]#
Print a formatted string representation of the entire table.
This method is the same as
astropy.table.Table.pprint
except that the defaultmax_lines
andmax_width
are both -1 so that by default the entire table is printed instead of restricting to the size of the screen terminal.- Parameters:
- max_lines
int
orNone
Maximum number of lines in table output.
- max_width
int
orNone
Maximum character width of output.
- show_namebool
Include a header row for column names. Default is True.
- show_unitbool
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_dtypebool
Include a header row for column dtypes. Default is False.
- align
str
orlist
ortuple
orNone
Left/right alignment of columns. Default is right (None) for all columns. Other allowed values are ‘>’, ‘<’, ‘^’, and ‘0=’ for right, left, centered, and 0-padded, respectively. A list of strings can be provided for alignment of tables with multiple columns.
- max_lines
- remove_column(name)[source]#
Remove a column from the table.
This can also be done with:
del table[name]
- Parameters:
- name
str
Name of column to remove
- 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
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]#
Remove several columns from the table.
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_indices(colname)[source]#
Remove all indices involving the given column. If the primary index is removed, the new primary index will be the most recently added remaining index.
- Parameters:
- colname
str
Name of column
- colname
- remove_row(index)[source]#
Remove a row from the table.
- Parameters:
- index
int
Index of row to remove
- index
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]#
Remove rows from the table.
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]#
Rename a column.
This can also be done directly by setting the
name
attribute of theinfo
property of the column:table[name].info.name = new_name
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
- rename_columns(names, new_names)[source]#
Rename multiple columns.
- Parameters:
Examples
Create a table with three columns ‘a’, ‘b’, ‘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 columns ‘a’ to ‘aa’ and ‘b’ to ‘bb’:
>>> names = ('a','b') >>> new_names = ('aa','bb') >>> t.rename_columns(names, new_names) >>> print(t) aa bb c --- --- --- 1 3 5 2 4 6
- replace_column(name, col, copy=True)[source]#
Replace column
name
with the newcol
object.The behavior of
copy
for Column objects is: - copy=True: new class instance with a copy of data and deep copy of meta - copy=False: new class instance with same data and a key-only copy of metaFor mixin columns: - copy=True: new class instance with copy of data and deep copy of meta - copy=False: original instance (no copy at all)
- Parameters:
See also
Examples
Replace column ‘a’ with a float version of itself:
>>> t = Table([[1, 2, 3], [0.1, 0.2, 0.3]], names=('a', 'b')) >>> float_a = t['a'].astype(float) >>> t.replace_column('a', float_a)
- reverse()[source]#
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
- round(decimals=0)[source]#
Round numeric columns in-place to the specified number of decimals. Non-numeric columns will be ignored.
- Parameters:
- decimals: int, dict
Number of decimals to round the columns to. If a dict is given, the columns will be rounded to the number specified as the value. If a certain column is not in the dict given, it will remain the same.
Examples
Create three columns with different types:
>>> t = Table([[1, 4, 5], [-25.55, 12.123, 85], ... ['a', 'b', 'c']], names=('a', 'b', 'c')) >>> print(t) a b c --- ------ --- 1 -25.55 a 4 12.123 b 5 85.0 c
Round them all to 0:
>>> t.round(0) >>> print(t) a b c --- ----- --- 1 -26.0 a 4 12.0 b 5 85.0 c
Round column ‘a’ to -1 decimal:
>>> t.round({'a':-1}) >>> print(t) a b c --- ----- --- 0 -26.0 a 0 12.0 b 0 85.0 c
- setdefault(name, default)[source]#
Ensure a column named
name
exists.If
name
is already present thendefault
is ignored. Otherwisedefault
can be any data object which is acceptable as aTable
column object or can be converted. This includes mixin columns and scalar or length=1 objects which get broadcast to match the table length.- Parameters:
- Returns:
Column
,MaskedColumn
or mixin-column typeThe column named
name
if it is present already, or the validateddefault
converted to a column otherwise.
- Raises:
TypeError
If the table is empty and
default
is a scalar object.
Examples
Start with a simple table:
>>> t0 = Table({"a": ["Ham", "Spam"]}) >>> t0 <Table length=2> a str4 ---- Ham Spam
Trying to add a column that already exists does not modify it:
>>> t0.setdefault("a", ["Breakfast"]) <Column name='a' dtype='str4' length=2> Ham Spam >>> t0 <Table length=2> a str4 ---- Ham Spam
But if the column does not exist it will be created with the default value:
>>> t0.setdefault("approved", False) <Column name='approved' dtype='bool' length=2> False False >>> t0 <Table length=2> a approved str4 bool ---- -------- Ham False Spam False
- show_in_browser(max_lines=5000, jsviewer=False, browser='default', jskwargs={'use_local_files': True}, tableid=None, table_class='display compact', css=None, show_row_index='idx')[source]#
Deprecated since version 6.1: We are planning on deprecating show_in_browser in the future. If you are actively using this method, please let us know at astropy/astropy#16067
Render the table in HTML and show it in a web browser.
- Parameters:
- 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.- jsviewerbool
If
True
, prepends some javascript headers so that the table is rendered as a DataTables data table. This allows in-browser searching & sorting.- browser
str
Any legal browser name, e.g.
'firefox'
,'chrome'
,'safari'
(for mac, you may need to use'open -a "/Applications/Google Chrome.app" {}'
for Chrome). If'default'
, will use the system default browser.- jskwargs
dict
Passed to the
astropy.table.JSViewer
init. Defaults to{'use_local_files': True}
which means that the JavaScript libraries will be served from local copies.- tableid
str
orNone
An html ID tag for the table. Default is
table{id}
, where id is the unique integer id of the table object, id(self).- table_class
str
orNone
A string with a list of HTML classes used to style the table. Default is “display compact”, and other possible values can be found in https://www.datatables.net/manual/styling/classes
- css
str
A valid CSS string declaring the formatting for the table. Defaults to
astropy.table.jsviewer.DEFAULT_CSS
.- show_row_index
str
orFalse
If this does not evaluate to False, a column with the given name will be added to the version of the table that gets displayed. This new column shows the index of the row in the table itself, even when the displayed table is re-sorted by another column. Note that if a column with this name already exists, this option will be ignored. Defaults to “idx”.
- max_lines
- show_in_notebook(tableid=None, css=None, display_length=50, table_class='astropy-default', show_row_index='idx')[source]#
Deprecated since version 6.1: show_in_notebook() is deprecated as of 6.1 and to create interactive tables it is recommended to use dedicated tools like: - bloomberg/ipydatagrid - https://docs.bokeh.org/en/latest/docs/user_guide/interaction/widgets.html#datatable - https://dash.plotly.com/datatable
Render the table in HTML and show it in the IPython notebook.
- Parameters:
- tableid
str
orNone
An html ID tag for the table. Default is
table{id}-XXX
, where id is the unique integer id of the table object, id(self), and XXX is a random number to avoid conflicts when printing the same table multiple times.- table_class
str
orNone
A string with a list of HTML classes used to style the table. The special default string (‘astropy-default’) means that the string will be retrieved from the configuration item
astropy.table.default_notebook_table_class
. Note that these table classes may make use of bootstrap, as this is loaded with the notebook. See this page for the list of classes.- css
str
A valid CSS string declaring the formatting for the table. Defaults to
astropy.table.jsviewer.DEFAULT_CSS_NB
.- display_length
int
, optional Number or rows to show. Defaults to 50.
- show_row_index
str
orFalse
If this does not evaluate to False, a column with the given name will be added to the version of the table that gets displayed. This new column shows the index of the row in the table itself, even when the displayed table is re-sorted by another column. Note that if a column with this name already exists, this option will be ignored. Defaults to “idx”.
- tableid
Notes
Currently, unlike
show_in_browser
(withjsviewer=True
), this method needs to access online javascript code repositories. This is due to modern browsers’ limitations on accessing local files. Hence, if you call this method while offline (and don’t have a cached version of jquery and jquery.dataTables), you will not get the jsviewer features.
- sort(keys=None, *, kind=None, reverse=False)[source]#
Sort the table according to one or more keys. This operates on the existing table and does not return a new table.
- Parameters:
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
Sorting according to standard sorting rules, first ‘firstname’ then ‘tel’, in reverse order:
>>> t.sort(['firstname', 'tel'], reverse=True) >>> print(t) firstname name tel --------- ------- --- Max Miller 12 John Jackson 18 Jo Miller 15
- to_pandas(index=None, use_nullable_int=True)[source]#
Return a
pandas.DataFrame
instance.The index of the created DataFrame is controlled by the
index
argument. Forindex=True
or the defaultNone
, an index will be specified for the DataFrame if there is a primary key index on the Table and if it corresponds to a single column. Ifindex=False
then no DataFrame index will be specified. Ifindex
is the name of a column in the table then that will be the DataFrame index.In addition to vanilla columns or masked columns, this supports Table mixin columns like Quantity, Time, or SkyCoord. In many cases these objects have no analog in pandas and will be converted to a “encoded” representation using only Column or MaskedColumn. The exception is Time or TimeDelta columns, which will be converted to the corresponding representation in pandas using
np.datetime64
ornp.timedelta64
. See the example below.- Parameters:
- index
None
, bool,str
Specify DataFrame index mode
- use_nullable_intbool, default=True
Convert integer MaskedColumn to pandas nullable integer type. If
use_nullable_int=False
or the pandas version does not support nullable integer types (version < 0.24), then the column is converted to float with NaN for missing elements and a warning is issued.
- index
- Returns:
- dataframe
pandas.DataFrame
A pandas
pandas.DataFrame
instance
- dataframe
- Raises:
ImportError
If pandas is not installed
ValueError
If the Table has multi-dimensional columns
Examples
Here we convert a table with a few mixins to a
pandas.DataFrame
instance.>>> import pandas as pd >>> from astropy.table import QTable >>> import astropy.units as u >>> from astropy.time import Time, TimeDelta >>> from astropy.coordinates import SkyCoord
>>> q = [1, 2] * u.m >>> tm = Time([1998, 2002], format='jyear') >>> sc = SkyCoord([5, 6], [7, 8], unit='deg') >>> dt = TimeDelta([3, 200] * u.s)
>>> t = QTable([q, tm, sc, dt], names=['q', 'tm', 'sc', 'dt'])
>>> df = t.to_pandas(index='tm') >>> with pd.option_context('display.max_columns', 20): ... print(df) q sc.ra sc.dec dt tm 1998-01-01 1.0 5.0 7.0 0 days 00:00:03 2002-01-01 2.0 6.0 8.0 0 days 00:03:20
- update(other, copy=True)[source]#
Perform a dictionary-style update and merge metadata.
The argument
other
must be aTable
, or something that can be used to initialize a table. Columns from (possibly converted)other
are added to this table. In case of matching column names the column from this table is replaced with the one fromother
. Ifother
is aTable
instance then|=
is available as alternate syntax for in-place update and|
can be used merge data to a new table.- Parameters:
- otherastropy:table-like
Data to update this table with.
- copybool
Whether the updated columns should be copies of or references to the originals.
See also
Examples
Update a table with another table:
>>> t1 = Table({'a': ['foo', 'bar'], 'b': [0., 0.]}, meta={'i': 0}) >>> t2 = Table({'b': [1., 2.], 'c': [7., 11.]}, meta={'n': 2}) >>> t1.update(t2) >>> t1 <Table length=2> a b c str3 float64 float64 ---- ------- ------- foo 1.0 7.0 bar 2.0 11.0 >>> t1.meta {'i': 0, 'n': 2}
Update a table with a dictionary:
>>> t = Table({'a': ['foo', 'bar'], 'b': [0., 0.]}) >>> t.update({'b': [1., 2.]}) >>> t <Table length=2> a b str3 float64 ---- ------- foo 1.0 bar 2.0
- values_equal(other)[source]#
Element-wise comparison of table with another table, list, or scalar.
Returns a
Table
with the same columns containing boolean values showing result of comparison.- Parameters:
- otherastropy:table-like
object
orlist
or scalar Object to compare with table
- otherastropy:table-like
Examples
Compare one Table with other:
>>> t1 = Table([[1, 2], [4, 5], [-7, 8]], names=('a', 'b', 'c')) >>> t2 = Table([[1, 2], [-4, 5], [7, 8]], names=('a', 'b', 'c')) >>> t1.values_equal(t2) <Table length=2> a b c bool bool bool ---- ----- ----- True False False True True True