EventTable¶

class gwpy.table.EventTable(data=None, masked=False, names=None, dtype=None, meta=None, copy=True, rows=None, copy_indices=True, units=None, descriptions=None, **kwargs)[source]¶

A container for a table of events.

This object expands the default Table with extra read/write formats, and methods to perform filtering, rate calculations, and visualisation.

See also

astropy.table.Table: for details on parameters for creating an EventTable

Attributes Summary

`ColumnClass`
`colnames`
`dtype`
`groups`
`has_masked_columns`	True if table has any `MaskedColumn` columns.
`has_masked_values`	True if column in the table has values which are masked.
`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.
`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`
`pprint_exclude_names`	Maintain tuple that controls table column visibility for print output.
`pprint_include_names`	Maintain tuple that controls table column visibility for print output.

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).
`binned_event_rates`(stride, column, bins[, ...])	Calculate an event rate `TimeSeriesDict` over a number of bins.
`cluster`(index, rank, window)	Cluster this `EventTable` over a given column, `index`, maximizing over a specified column in the table, `rank`.
`convert_bytestring_to_unicode`()	Convert bytestring columns (dtype.kind='S') to unicode (dtype.kind='U') using UTF-8 encoding.
`convert_unicode_to_bytestring`()	Convert unicode columns (dtype.kind='U') to bytestring (dtype.kind='S') using UTF-8 encoding.
`copy`([copy_data])	Return a copy of the table.
`event_rate`(stride[, start, end, timecolumn])	Calculate the rate `TimeSeries` for this `Table`.
`fetch`(format_, args, *kwargs)	Fetch a table of events from a database
`fetch_open_data`(catalog[, columns, ...])	Fetch events from an open-data catalogue hosted by GWOSC.
`field`(item)	Return column[item] for recarray compatibility.
`filled`([fill_value])	Return copy of self, with masked values filled.
`filter`(*column_filters)	Apply one or more column slice filters to this `EventTable`
`from_pandas`(dataframe[, index, units])	Create a `Table` from a `pandas.DataFrame` instance
`get_column`(name)	Return the `Column` with the given name
`group_by`(keys)	Group this table by the specified `keys`
`hist`(column, **kwargs)	Generate a `HistogramPlot` of this `Table`.
`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
`plot`(args, *kwargs)	DEPRECATED, use `EventTable.scatter`
`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.
`read`(source, args, *kwargs)	Read data into an `EventTable`
`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 new `col` object.
`reverse`()	Reverse the row order of table rows.
`round`([decimals])	Round numeric columns in-place to the specified number of decimals.
`scatter`(x, y, **kwargs)	Make a scatter plot of column `x` vs column `y`.
`show_in_browser`([max_lines, jsviewer, ...])	Render the table in HTML and show it in a web browser.
`show_in_notebook`([tableid, css, ...])	Render the table in HTML and show it in the IPython notebook.
`sort`([keys, kind, reverse])	Sort the table according to one or more keys.
`tile`(x, y, w, h, **kwargs)	Make a tile plot of this table.
`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.
`write`(target, args, *kwargs)	Write this table to a file

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¶

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 and pprint_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 and pprint_exclude_names Table attributes.

Methods Documentation

add_column(col, index=None, name=None, rename_duplicate=False, copy=True, default_name=None)¶

Add a new column to the table using col as input. If index is supplied then insert column before index 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 a Table 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 call add_column() for each one. There is very little performance difference in the two approaches.

Parameters¶

colobject: Data object for the new column
indexint or None: Insert column before this position or at end (default).
namestr: 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_namestr or None: Name to use if both name and col.info.name are not available. Defaults to col{number_of_columns}.

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)¶

Add a list of new columns the table using cols data objects. 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.

The cols input can include any data objects which are acceptable as Table 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¶

colslist of object: List of data objects for the new columns
indexeslist of int or None: Insert column before this position or at end (default).
nameslist of str: 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.

See also

astropy.table.hstack, update, replace_column

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)¶

Insert a new index among one or more columns. If there are no indices, make this index the primary table index.

Parameters¶

colnamesstr or list: List of column names (or a single column name) to index
enginetype or None: Indexing engine class to use, from among SortedArray, BST, and SCEngine. If the supplied argument is None (by default), use SortedArray.
uniquebool: Whether the values of the index must be unique. Default is False.

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¶

valstuple, list, dict or None: Use the specified values in the new row
masktuple, 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, reverse=False)¶

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¶

keysstr or list of str: The column name(s) to order the table by
kind{‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, optional: Sorting algorithm used by numpy.argsort.
reversebool: Sort in reverse order (default=False)

Returns¶

index_arrayndarray, int: Array of indices that sorts the table by the specified key column(s).

as_array(keep_byteorder=False, names=None)¶

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).
nameslist, optional:: List of column names to include for returned structured array. Default is to include all table columns.

Returns¶

table_arrayarray or MaskedArray: Copy of table as a numpy structured array. ndarray for unmasked or MaskedArray for masked.

binned_event_rates(stride, column, bins, operator='>=', start=None, end=None, timecolumn=None)[source]¶

Calculate an event rate TimeSeriesDict over a number of bins.

Parameters¶

stridefloat

size (seconds) of each time bin

columnstr

name of column by which to bin.

binslist

a list of tuples marking containing bins, or a list of floats defining bin edges against which an math operation is performed for each event.

operatorstr, callable

one of:

'<', '<=', '>', '>=', '==', '!=', for a standard mathematical operation,
'in' to use the list of bins as containing bin edges, or
a callable function that takes compares an event value against the bin value and returns a boolean.

Note

If bins is given as a list of tuples, this argument is ignored.

startfloat, LIGOTimeGPS, optional

GPS start epoch of rate TimeSeries.

endfloat, LIGOTimeGPS, optional

GPS end time of rate TimeSeries. This value will be rounded up to the nearest sample if needed.

timecolumnstr, optional, default: time

name of time-column to use when binning events

Returns¶

rates~gwpy.timeseries.TimeSeriesDict`: a dict of (bin, TimeSeries) pairs describing a rate of events per second (Hz) for each of the bins.

cluster(index, rank, window)[source]¶

Cluster this EventTable over a given column, index, maximizing over a specified column in the table, rank.

The clustering algorithm uses a pooling method to identify groups of points that are all separated in index by less than window.

Each cluster of nearby points is replaced by the point in that cluster with the maximum value of rank.

Parameters¶

indexstr: name of the column which is used to search for clusters
rankstr: name of the column to maximize over in each cluster
windowfloat: window to use when clustering data points, will raise ValueError if window > 0 is not satisfied

Returns¶

tableEventTable: a new table that has had the clustering algorithm applied via slicing of the original

Examples

To cluster an EventTable (table) whose index is end_time, window is 0.1, and maximize over snr:

>>> table.cluster('end_time', 'snr', 0.1)

convert_bytestring_to_unicode()¶

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()¶

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.

copy(copy_data=True)¶

Return a copy of the table.

Parameters¶

copy_databool: If True (the default), copy the underlying data array. Otherwise, use the same data array. The meta is always deepcopied regardless of the value for copy_data.

event_rate(stride, start=None, end=None, timecolumn=None)[source]¶

Calculate the rate TimeSeries for this Table.

Parameters¶

stridefloat: size (seconds) of each time bin
startfloat, LIGOTimeGPS, optional: GPS start epoch of rate TimeSeries
endfloat, LIGOTimeGPS, optional: GPS end time of rate TimeSeries. This value will be rounded up to the nearest sample if needed.
timecolumnstr, optional: name of time-column to use when binning events, attempts are made to guess this

Returns¶

rateTimeSeries: a TimeSeries of events per second (Hz)

Raises¶

ValueError: if the timecolumn cannot be guessed from the table contents

classmethod fetch(format_, *args, **kwargs)[source]¶

Fetch a table of events from a database

Parameters¶

formatstr, Engine: the format of the remote data, see _Notes_ for a list of registered formats, OR an SQL database Engine object
*args: all other positional arguments are specific to the data format, see below for basic usage
columnslist of str, optional: the columns to fetch from the database table, defaults to all
selectionstr, or list of str, optional: one or more column filters with which to downselect the returned table rows as they as read, e.g. 'snr > 5'; multiple selections should be connected by ‘ && ‘, or given as a list, e.g. 'snr > 5 && frequency < 1000' or ['snr > 5', 'frequency < 1000']
**kwargs: all other positional arguments are specific to the data format, see the online documentation for more details

Returns¶

tableEventTable: a table of events recovered from the remote database

Notes

The available named formats are:

Format	Basic usage
gravityspy	`fetch('gravityspy', tablename)`
hacr	`fetch('hacr', channel, gpsstart, gpstop)`

Examples

>>> from gwpy.table import EventTable

To download a table of all blip glitches from the Gravity Spy database:

>>> EventTable.fetch(
...     'gravityspy',
...     'glitches',
...     selection=['ml_label=Blip', 'ml_confidence>0.9'],
... )

To download a table from any SQL-type server

>>> from sqlalchemy.engine import create_engine
>>> engine = create_engine(...)
>>> EventTable.fetch(engine, 'mytable')

classmethod fetch_open_data(catalog, columns=None, selection=None, host='https://www.gw-openscience.org', **kwargs)[source]¶

Fetch events from an open-data catalogue hosted by GWOSC.

Parameters¶

catalogstr: the name of the catalog to fetch, e.g. 'GWTC-1-confident'
columnslist of str, optional: the list of column names to read
selectionstr, or list of str, optional: one or more column filters with which to downselect the returned events as they as read, e.g. 'mass1 < 30'; multiple selections should be connected by ‘ && ‘, or given as a list, e.g. 'mchirp < 3 && distance < 500' or ['mchirp < 3', 'distance < 500']
hoststr, optional: the open-data host to use

field(item)¶: Return column[item] for recarray compatibility.

filled(fill_value=None)¶

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 individual fill_value defined for each table column is used.

Parameters¶

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

Returns¶

filled_tableTable: New table with masked values filled

filter(*column_filters)[source]¶

Apply one or more column slice filters to this EventTable

Multiple column filters can be given, and will be applied concurrently

Parameters¶

column_filterstr, tuple: a column slice filter definition, e.g. 'snr > 10, or a filter tuple definition, e.g. ('snr', <my_func>, <arg>)

Returns¶

tableEventTable: a new table with only those rows matching the filters

Notes

See Filtering tables for more details on using filter tuples

Examples

To filter an existing EventTable (table) to include only rows with snr greater than 10, and frequency less than 1000:

>>> table.filter('snr>10', 'frequency<1000')

Custom operations can be defined using filter tuple definitions:

>>> from gwpy.table.filters import in_segmentlist
>>> table.filter(('time', in_segmentlist, segs))

classmethod from_pandas(dataframe, index=False, units=None)¶

Create a Table from a pandas.DataFrame instance

In addition to converting generic numeric or string columns, this supports conversion of pandas Date and Time delta columns to Time and TimeDelta columns, respectively.

Parameters¶

dataframepandas.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 to a Unit. The columns will have the specified unit in the Table.

Returns¶

tableTable: A Table (or subclass) instance

Raises¶

ImportError: If pandas is not installed

Examples

Here we convert a pandas.DataFrame instance to a QTable.

>>> 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

get_column(name)[source]¶

Return the Column with the given name

This method is provided only for compatibility with the ligo.lw.table.Table.

Parameters¶

namestr: the name of the column to return

Returns¶

columnastropy.table.Column

Raises¶

KeyError: if no column is found with the given name

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¶

keysstr, list of str, numpy array, or Table: Key grouping object

Returns¶

outTable: New table with groups set

hist(column, **kwargs)[source]¶

Generate a HistogramPlot of this Table.

Parameters¶

columnstr: Name of the column over which to histogram data
methodstr, optional: Name of Axes method to use to plot the histogram, default: 'hist'.
**kwargs: Any other keyword arguments, see below.

Returns¶

plotPlot: The newly created figure.

See also

matplotlib.pyplot.figure: for documentation of keyword arguments used to create the figure.
matplotlib.figure.Figure.add_subplot: for documentation of keyword arguments used to create the axes.
gwpy.plot.Axes.hist: for documentation of keyword arguments used to display the histogram, if the method keyword is given, this method might not actually be the one used.

index_column(name)¶

Return the positional index of column name.

Parameters¶

namestr: column name

Returns¶

indexint: 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)¶

Return a context manager for an indexing mode.

Parameters¶

modestr: 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.

insert_row(index, vals=None, mask=None)¶

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. 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¶

valstuple, list, dict or None: Use the specified values in the new row
masktuple, list, dict or None: Use the specified mask values in the new row

items()¶

itercols()¶

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 to for col in t.columns.values() but is syntactically preferred.

iterrows(*names)¶

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¶

nameslist: List of column names (default to all columns if no names provided)

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)¶

Keep only the columns specified (remove the others).

Parameters¶

namesstr or iterable of str: 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

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

keys()¶

more(max_lines=None, max_width=None, show_name=True, show_unit=None, show_dtype=False)¶

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_linesint: Maximum number of lines in table output
max_widthint or None: 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.

pformat(max_lines=None, max_width=None, show_name=True, show_unit=None, show_dtype=False, html=False, tableid=None, align=None, tableclass=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_linesint or None: Maximum number of rows to output
max_widthint or None: 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.
tableidstr 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)
alignstr or list or tuple or None: 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.
tableclassstr or list of str or None: CSS classes for the table; only used if html is set. Default is None.

Returns¶

lineslist: Formatted table as a list of strings.

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)¶

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 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_linesint or None: Maximum number of rows to output
max_widthint or None: 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.
tableidstr 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)
alignstr or list or tuple or None: 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.
tableclassstr or list of str or None: CSS classes for the table; only used if html is set. Default is None.

Returns¶

lineslist: Formatted table as a list of strings.

plot(*args, **kwargs)[source]¶: DEPRECATED, use EventTable.scatter

pprint(max_lines=None, max_width=None, show_name=True, show_unit=None, show_dtype=False, align=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_linesint or None: Maximum number of lines in table output.
max_widthint or None: 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.
alignstr or list or tuple or None: 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.

pprint_all(max_lines=- 1, max_width=- 1, show_name=True, show_unit=None, show_dtype=False, align=None)¶

Print a formatted string representation of the entire table.

This method is the same as astropy.table.Table.pprint except that the default max_lines and max_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_linesint or None: Maximum number of lines in table output.
max_widthint or None: 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.
alignstr or list or tuple or None: 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.

classmethod read(source, *args, **kwargs)[source]¶

Read data into an EventTable

Parameters¶

sourcestr, list

Source of data, any of the following:

str path of single data file,
str path of LAL-format cache file,
list of paths.

*args

other positional arguments will be passed directly to the underlying reader method for the given format

formatstr, optional

the format of the given source files; if not given, an attempt will be made to automatically identify the format

columnslist of str, optional

the list of column names to read

selectionstr, or list of str, optional

one or more column filters with which to downselect the returned table rows as they as read, e.g. 'snr > 5'; multiple selections should be connected by ‘ && ‘, or given as a list, e.g. 'snr > 5 && frequency < 1000' or ['snr > 5', 'frequency < 1000']

nprocint, optional, default: 1

number of CPUs to use for parallel reading of multiple files

verbosebool, optional

print a progress bar showing read status, default: False

.. note::

Keyword arguments other than those listed here may be required depending on the format

Returns¶

tableEventTable

Raises¶

astropy.io.registry.IORegistryError: if the format cannot be automatically identified
IndexError: if source is an empty list

Notes

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.cwb	Yes	No	No
ascii.daophot	Yes	No	No
ascii.ecsv	Yes	Yes	Yes
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.mrt	Yes	Yes	No
ascii.no_header	Yes	Yes	No
ascii.omega	Yes	No	No
ascii.qdp	Yes	Yes	Yes
ascii.rdb	Yes	Yes	Yes
ascii.rst	Yes	Yes	No
ascii.sextractor	Yes	No	No
ascii.tab	Yes	Yes	No
asdf	Yes	Yes	Yes
fits	Yes	Yes	Yes
gwf	Yes	Yes	Yes
hdf5	Yes	Yes	Yes
hdf5.pycbc_live	Yes	No	Yes
hdf5.snax	Yes	No	No
ligolw	Yes	Yes	Yes
ligolw.gstlal	Yes	No	Yes
ligolw.gstlal.coinc	Yes	No	No
ligolw.gstlal.sngl	Yes	No	No
pandas.csv	Yes	Yes	No
pandas.fwf	Yes	No	No
pandas.html	Yes	Yes	No
pandas.json	Yes	Yes	No
parquet	Yes	Yes	Yes
root	Yes	Yes	Yes
root.cwb	Yes	No	No
root.omicron	Yes	No	No
votable	Yes	Yes	Yes
aastex	Yes	Yes	No	Yes
cds	Yes	No	No	Yes
csv	Yes	Yes	No	Yes
daophot	Yes	No	No	Yes
html	Yes	Yes	No	Yes
ipac	Yes	Yes	No	Yes
latex	Yes	Yes	No	Yes
mrt	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¶

namestr: 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¶

namesstr or iterable of str: 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_indices(colname)¶

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¶

colnamestr: Name of column

remove_row(index)¶

Remove a row from the table.

Parameters¶

indexint: 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_specifierslice or int or array of int: 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

TODO: this won’t work for mixins

Parameters¶

namestr: The current name of the column.
new_namestr: 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

rename_columns(names, new_names)¶

Rename multiple columns.

Parameters¶

nameslist, tuple: A list or tuple of existing column names.
new_nameslist, tuple: A list or tuple of new column names.

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)¶

Replace column name with the new col 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 meta

For 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¶

namestr: Name of column to replace
colColumn or ndarray or sequence: New column object to replace the existing column.
copybool: Make copy of the input col, default=True

See also

add_columns, astropy.table.hstack, update

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()¶

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)¶

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

scatter(x, y, **kwargs)[source]¶

Make a scatter plot of column x vs column y.

Parameters¶

xstr: name of column defining centre point on the X-axis
ystr: name of column defining centre point on the Y-axis
colorstr, optional, default:None: name of column by which to color markers
**kwargs: any other keyword arguments, see below

Returns¶

plotPlot: the newly created figure

See also

matplotlib.pyplot.figure: for documentation of keyword arguments used to create the figure
matplotlib.figure.Figure.add_subplot: for documentation of keyword arguments used to create the axes
gwpy.plot.Axes.scatter: for documentation of keyword arguments used to display the table

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')¶

Render the table in HTML and show it in a web browser.

Parameters¶

max_linesint: 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.
browserstr: 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.
jskwargsdict: 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.
tableidstr 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).
table_classstr or None: 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
cssstr: A valid CSS string declaring the formatting for the table. Defaults to astropy.table.jsviewer.DEFAULT_CSS.
show_row_indexstr or False: 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”.

show_in_notebook(tableid=None, css=None, display_length=50, table_class='astropy-default', show_row_index='idx')¶

Render the table in HTML and show it in the IPython notebook.

Parameters¶

tableidstr or None: 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_classstr or None: 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.
cssstr: A valid CSS string declaring the formatting for the table. Defaults to astropy.table.jsviewer.DEFAULT_CSS_NB.
display_lengthint, optional: Number or rows to show. Defaults to 50.
show_row_indexstr or False: 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”.

Notes

Currently, unlike show_in_browser (with jsviewer=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)¶

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

Parameters¶

keysstr or list of str: The key(s) to order the table by. If None, use the primary index of the Table.
kind{‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, optional: Sorting algorithm used by numpy.argsort.
reversebool: Sort in reverse order (default=False)

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

tile(x, y, w, h, **kwargs)[source]¶

Make a tile plot of this table.

Parameters¶

xstr: name of column defining anchor point on the X-axis
ystr: name of column defining anchor point on the Y-axis
wstr: name of column defining extent on the X-axis (width)
hstr: name of column defining extent on the Y-axis (height)
colorstr, optional, default:None: name of column by which to color markers
**kwargs: any other keyword arguments, see below

Returns¶

plotPlot: the newly created figure

See also

matplotlib.pyplot.figure: for documentation of keyword arguments used to create the figure
matplotlib.figure.Figure.add_subplot: for documentation of keyword arguments used to create the axes
gwpy.plot.Axes.tile: for documentation of keyword arguments used to display the table

to_pandas(index=None, use_nullable_int=True)¶

Return a pandas.DataFrame instance

The index of the created DataFrame is controlled by the index argument. For index=True or the default None, 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. If index=False then no DataFrame index will be specified. If index 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 or np.timedelta64. See the example below.

Parameters¶

indexNone, 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.

Returns¶

dataframepandas.DataFrame: A pandas pandas.DataFrame instance

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)¶

Perform a dictionary-style update and merge metadata.

The argument other must be a |Table|, 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 from other.

Parameters¶

othertable-like: Data to update this table with.
copybool: Whether the updated columns should be copies of or references to the originals.

See also

add_columns, astropy.table.hstack, replace_column

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()¶

values_equal(other)¶

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¶

othertable-like object or list or scalar: Object to compare with table

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

write(target, *args, **kwargs)[source]¶

Write this table to a file

Parameters¶

target: `str`: filename for output data file
*args: other positional arguments will be passed directly to the underlying writer method for the given format
formatstr, optional: format for output data; if not given, an attempt will be made to automatically identify the format based on the target filename
**kwargs: other keyword arguments will be passed directly to the underlying writer method for the given format

Raises¶

astropy.io.registry.IORegistryError: if the format cannot be automatically identified

Notes

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.ecsv	Yes	Yes	Yes
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.mrt	Yes	Yes	No
ascii.no_header	Yes	Yes	No
ascii.qdp	Yes	Yes	Yes
ascii.rdb	Yes	Yes	Yes
ascii.rst	Yes	Yes	No
ascii.tab	Yes	Yes	No
asdf	Yes	Yes	Yes
fits	Yes	Yes	Yes
gwf	Yes	Yes	No
hdf5	Yes	Yes	Yes
jsviewer	No	Yes	No
ligolw	Yes	Yes	Yes
pandas.csv	Yes	Yes	No
pandas.html	Yes	Yes	No
pandas.json	Yes	Yes	No
parquet	Yes	Yes	Yes
root	Yes	Yes	Yes
votable	Yes	Yes	Yes
aastex	Yes	Yes	No	Yes
csv	Yes	Yes	No	Yes
html	Yes	Yes	No	Yes
ipac	Yes	Yes	No	Yes
latex	Yes	Yes	No	Yes
mrt	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.