BinnedTimeSeries#

class astropy.timeseries.BinnedTimeSeries(data=None, *, time_bin_start=None, time_bin_end=None, time_bin_size=None, n_bins=None, **kwargs)[source]#

Bases: BaseTimeSeries

A class to represent binned time series data in tabular form.

BinnedTimeSeries provides a class for representing time series as a collection of values of different quantities measured in time bins (for time series with values sampled at specific times, see the TimeSeries class). BinnedTimeSeries is a sub-class of QTable and thus provides all the standard table maniplation methods available to tables, but it also provides additional conveniences for dealing with time series, such as a flexible initializer for setting up the times, and attributes to access the start/center/end time of bins.

See also: https://docs.astropy.org/en/stable/timeseries/

Parameters:
datanumpy ndarray, python:dict, python:list, astropy:table-like object, optional

Data to initialize time series. This does not need to contain the times, which can be provided separately, but if it does contain the times they should be in columns called 'time_bin_start' and 'time_bin_size' to be automatically recognized.

time_bin_startTime or python:iterable

The times of the start of each bin - this can be either given directly as a Time array or as any iterable that initializes the Time class. If this is given, then the remaining time-related arguments should not be used. This can also be a scalar value if time_bin_size is provided.

time_bin_endTime or python:iterable

The times of the end of each bin - this can be either given directly as a Time array or as any value or iterable that initializes the Time class. If this is given, then the remaining time-related arguments should not be used. This can only be given if time_bin_start is an array of values. If time_bin_end is a scalar, time bins are assumed to be contiguous, such that the end of each bin is the start of the next one, and time_bin_end gives the end time for the last bin. If time_bin_end is an array, the time bins do not need to be contiguous. If this argument is provided, time_bin_size should not be provided.

time_bin_sizeTimeDelta or Quantity

The size of the time bins, either as a scalar value (in which case all time bins will be assumed to have the same duration) or as an array of values (in which case each time bin can have a different duration). If this argument is provided, time_bin_end should not be provided.

n_binspython:int

The number of time bins for the series. This is only used if both time_bin_start and time_bin_size are provided and are scalar values.

**kwargspython:dict, optional

Additional keyword arguments are passed to QTable.

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.

time_bin_center

The center times of all the time bins.

time_bin_end

The end times of all the time bins.

time_bin_size

The sizes of all the time bins.

time_bin_start

The start times of all the time bins.

write

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

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 a pandas.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 the table.

pformat_all([max_lines, max_width, ...])

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(filename[, time_bin_start_column, ...])

Read and parse a file and returns a astropy.timeseries.BinnedTimeSeries.

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.

setdefault(name, default)

Ensure a column named name exists.

show_in_browser([max_lines, jsviewer, ...])

show_in_notebook(*[, backend])

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

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

time_bin_center#

The center times of all the time bins.

time_bin_end#

The end times of all the time bins.

time_bin_size#

The sizes of all the time bins.

time_bin_start#

The start times of all the time bins.

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:
*argspython:tuple, optional

Positional arguments passed through to data writer. If supplied the first argument is the output filename.

formatpython:str

File format specifier.

serialize_methodpython:str, python:dict, optional

Serialization method specifier for columns.

**kwargspython:dict, optional

Keyword arguments passed through to data writer.

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

indexpython:int or python:None

Insert column before this position or at end (default).

namepython: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_namepython:str or python: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:
colspython:list of object

List of data objects for the new columns

indexespython:list of python:int or python:None

Insert column before this position or at end (default).

namespython:list of python: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:
colnamespython:str or python:list

List of column names (or a single column name) to index

enginetype or python:None

Indexing engine class to use, either SortedArray, BST, or SCEngine. If the supplied argument is None (by default), use SortedArray.

uniquebool (default: python:False)

If set to True, an exception will be raised if duplicate rows exist.

Raises:
ValueError

If any selected column does not support indexing, or has more than one dimension.

ValueError

If unique=True and duplicate rows are found.

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:
valspython:tuple, python:list, python:dict or python:None

Use the specified values in the new row

maskpython:tuple, python:list, python:dict or python: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:
keyspython:str or python:list of python: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, python: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).

namespython:list, 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.

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 and make a deep copy of the meta attribute. Otherwise, use the same data array and make a shallow (key-only) copy of meta.

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_valuepython:str

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

Returns:
filled_tableTable

New table with masked values filled

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 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
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:
keyspython:str, python:list of python:str, numpy array, or Table

Key grouping object

Returns:
outTable

New table with groups set

index_column(name)#

Return the positional index of column name.

Parameters:
namepython:str

column name

Returns:
indexpython:int

Positional index of column name.

Examples

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

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

Get index of column ‘b’ of the table:

>>> t.index_column('b')
1
index_mode(mode)#

Return a context manager for an indexing mode.

Parameters:
modepython: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.

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:
valspython:tuple, python:list, python:dict or python:None

Use the specified values in the new row

maskpython:tuple, python:list, python:dict or python: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:
namespython:list

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

Returns:
rowspython:iterable

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:
namespython:str or python:iterable of python: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_linespython:int

Maximum number of lines in table output

max_widthpython:int or python: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=-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 table.

If max_lines=None 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 will be determined using the astropy.conf.max_lines configuration item. If a negative value of max_lines is supplied then there is no line limit applied (default).

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

Parameters:
max_linespython:int or python:None

Maximum number of rows to output

max_widthpython:int or python: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.

tableidpython:str or python: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)

alignpython:str or python:list or python:tuple or python: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.

tableclasspython:str or python:list of python:str or python:None

CSS classes for the table; only used if html is set. Default is None.

Returns:
linespython:list

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

Deprecated since version 7.0: The pformat_all function is deprecated and may be removed in a future version. Use Table.pformat instead.

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

If max_lines=None 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 will be determined using the astropy.conf.max_lines configuration item. If a negative value of max_lines is supplied then there is no line limit applied (default).

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

Parameters:
max_linespython:int or python:None

Maximum number of rows to output

max_widthpython:int or python: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.

tableidpython:str or python: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)

alignpython:str or python:list or python:tuple or python: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.

tableclasspython:str or python:list of python:str or python:None

CSS classes for the table; only used if html is set. Default is None.

Returns:
linespython:list

Formatted table as a list of strings.

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_linespython:int or python:None

Maximum number of lines in table output.

max_widthpython:int or python: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.

alignpython:str or python:list or python:tuple or python: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_linespython:int or python:None

Maximum number of lines in table output.

max_widthpython:int or python: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.

alignpython:str or python:list or python:tuple or python: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(filename, time_bin_start_column=None, time_bin_end_column=None, time_bin_size_column=None, time_bin_size_unit=None, time_format=None, time_scale=None, format=None, *args, **kwargs)[source]#

Read and parse a file and returns a astropy.timeseries.BinnedTimeSeries.

This method uses the unified I/O infrastructure in Astropy which makes it easy to define readers/writers for various classes (https://docs.astropy.org/en/stable/io/unified.html). By default, this method will try and use readers defined specifically for the astropy.timeseries.BinnedTimeSeries class - however, it is also possible to use the format keyword to specify formats defined for the astropy.table.Table class - in this case, you will need to also provide the column names for column containing the start times for the bins, as well as other column names (see the Parameters section below for details):

>>> from astropy.timeseries.binned import BinnedTimeSeries
>>> ts = BinnedTimeSeries.read('binned.dat', format='ascii.ecsv',
...                            time_bin_start_column='date_start',
...                            time_bin_end_column='date_end')
Parameters:
filenamepython:str

File to parse.

formatpython:str

File format specifier.

time_bin_start_columnpython:str

The name of the column with the start time for each bin.

time_bin_end_columnpython:str, optional

The name of the column with the end time for each bin. Either this option or time_bin_size_column should be specified.

time_bin_size_columnpython:str, optional

The name of the column with the size for each bin. Either this option or time_bin_end_column should be specified.

time_bin_size_unitastropy.units.Unit, optional

If time_bin_size_column is specified but does not have a unit set in the table, you can specify the unit manually.

time_formatpython:str, optional

The time format for the start and end columns.

time_scalepython:str, optional

The time scale for the start and end columns.

*argspython:tuple, optional

Positional arguments passed through to the data reader.

**kwargspython:dict, optional

Keyword arguments passed through to the data reader.

Returns:
outastropy.timeseries.binned.BinnedTimeSeries

BinnedTimeSeries corresponding to the file.

remove_column(name)#

Remove a column from the table.

This can also be done with:

del table[name]
Parameters:
namepython:str

Name of column to remove

Examples

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

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

Remove column ‘b’ from the table:

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

To remove several columns at the same time use remove_columns.

remove_columns(names)#

Remove several columns from the table.

Parameters:
namespython:str or python:iterable of python: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:
colnamepython:str

Name of column

remove_row(index)#

Remove a row from the table.

Parameters:
indexpython:int

Index of row to remove

Examples

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

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

Remove row 1 from the table:

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

To remove several rows at the same time use remove_rows.

remove_rows(row_specifier)#

Remove rows from the table.

Parameters:
row_specifierslice or python:int or array of python: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 by setting the name attribute of the info property of the column:

table[name].info.name = new_name
Parameters:
namepython:str

The current name of the column.

new_namepython:str

The new name for the column

Examples

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

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

Renaming column ‘a’ to ‘aa’:

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

Rename multiple columns.

Parameters:
namespython:list, python:tuple

A list or tuple of existing column names.

new_namespython:list, python: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:
namepython:str

Name of column to replace

colColumn or ndarray or python: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
setdefault(name, default)#

Ensure a column named name exists.

If name is already present then default is ignored. Otherwise default 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.

Parameters:
namepython:str

Name of the column.

defaultobject

Data object for the new column.

Returns:
Column, MaskedColumn or mixin-column type

The column named name if it is present already, or the validated default 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')#

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

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

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

tableidpython:str or python: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_classpython:str or python: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

csspython:str

A valid CSS string declaring the formatting for the table. Defaults to astropy.table.jsviewer.DEFAULT_CSS.

show_row_indexpython:str or python: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(*, backend='ipydatagrid', **kwargs)#

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

Note

The method API was modified in v7.0 to include a backend argument and require only keyword arguments.

Parameters:
backend{“ipydatagrid”, “classic”}

Backend to use for rendering (default=”ipydatagrid”). The “classic” backend is deprecated since v6.1.

**kwargspython:dict, optional

Keyword arguments as accepted by desired backend. See astropy.table.notebook_backends for the available backends and their respective keyword arguments.

Raises:
NotImplementedError

Requested backend is not supported.

See also

astropy.table.notebook_backends
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:
keyspython:str or python:list of python: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
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:
indexpython:None, bool, python:str

Specify DataFrame index mode

use_nullable_intbool, default=True

Convert integer MaskedColumn to pandas nullable integer type. If use_nullable_int=False then the column is converted to float with NaN.

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. If other is a |Table| 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

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:
otherastropy:table-like object or python: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