Skip to main content
`Ctrl`+`K`

# TimeSeries

class astropy.timeseries.TimeSeries(data=None, *, time=None, time_start=None, time_delta=None, n_samples=None, **kwargs)

  Bases: `BaseTimeSeries`

  A class to represent time series data in tabular form.

  `TimeSeries` provides a class for representing time series as a collection of values of different quantities measured at specific points in time (for time series with finite time bins, see the `BinnedTimeSeries` class). `TimeSeries` 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, a method for folding time series, and a `time` attribute for easy access to the time values.

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

  Parameters:
    data `numpy` `ndarray`, `python:dict`, `python:list`, `Table`, or 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 a column called `'time'` to be automatically recognized.

    time `Time`, `TimeDelta` or python:iterable

      The times at which the values are sampled - this can be either given directly as a `Time` or `TimeDelta` array or as any iterable that initializes the `Time` class. If this is given, then the remaining time-related arguments should not be used.

    time_start `Time` or `python:str`

      The time of the first sample in the time series. This is an alternative to providing `time` and requires that `time_delta` is also provided.

    time_delta `TimeDelta` or `Quantity` [:ref: ‘time’]

      The step size in time for the series. This can either be a scalar if the time series is evenly sampled, or an array of values if it is not.

    n_samples `python:int`

      The number of time samples for the series. This is only used if both `time_start` and `time_delta` are provided and are scalar values.

    **kwargs `python: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` | The time values.
  `write` | Write this Table object out in the specified format.

  Methods Summary

  `add_column`(*args, **kwargs) | See `add_column()`.
  `add_columns`(*args, **kwargs) | See `add_columns()`.
  `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.
  `fold`([period, epoch_time, epoch_phase, ...]) | Return a new `TimeSeries` folded with a period and epoch.
  `from_df`(df, /, *[, index, units]) | Create a `Table` from any `narwhals`-compatible dataframe (e.g., `pandas`, `polars`, `pyarrow`, etc).
  `from_pandas`(df[, time_scale]) | Convert a `DataFrame` to a `astropy.timeseries.TimeSeries`.
  `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_column, time_format, ...]) | Read and parse a file and returns a `astropy.timeseries.TimeSeries`.
  `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_df`(backend, /, *[, index, use_nullable_int]) | Convert the table to an eager DataFrame using the `narwhals` backend.
  `to_pandas`() | Convert this `TimeSeries` to a `DataFrame` with a `DatetimeIndex` index.
  `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

    The time values.

  write

    Write this Table object out in the specified format.

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

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

    Get help on the available writers for `Table` using the``help()`` method:

        >>> Table.write.help()  # Get help writing Table and list supported formats
        >>> Table.write.help('fits')  # Get detailed help on Table FITS writer
        >>> Table.write.list_formats()  # Print list of available formats

    The `serialize_method` argument is explained in the section on Table serialization methods.

    See also: https://docs.astropy.org/en/stable/io/unified.html

    Parameters:
      *args `python:tuple`, optional

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

      format `python:str`

        File format specifier.

      serialize_method `python:str`, `python:dict`, optional

        Serialization method specifier for columns.

      write_indices bool, optional

        Write table indices if defined (default is False).

      **kwargs `python:dict`, optional

        Keyword arguments passed through to data writer.

  Methods Documentation

  add_column(*args, **kwargs)

    See `add_column()`.

  add_columns(*args, **kwargs)

    See `add_columns()`.

  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:
      colnames `python:str` or `python:tuple`[`python:str`, …] or `python:list`[`python:str`]

        Single column name or tuple or list of column names to index.

      engine type or `python:None`

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

      unique bool (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:
      vals `python:tuple`, `python:list`, `python:dict` or `python:None`

        Use the specified values in the new row

      mask `python: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:
      keys `python: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`.

      reverse bool

        Sort in reverse order (default=False)

    Returns:
      index_array `ndarray`, `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_byteorder bool, optional

        By default the returned array has all columns in native byte order. However, if this option is `True` this preserves the byte order of all columns (if any are non-native).

      names `python:list`, optional:

        List of column names to include for returned structured array. Default is to include all table columns.

    Returns:
      table_array `array` 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_data bool

        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_value `python:str`

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

    Returns:
      filled_table `Table`

        New table with masked values filled

  fold(period=None, epoch_time=None, epoch_phase=0, wrap_phase=None, normalize_phase=False)

    Return a new `TimeSeries` folded with a period and epoch.

    Parameters:
      period `Quantity` [:ref: ‘time’]

        The period to use for folding

      epoch_time `Time`

        The time to use as the reference epoch, at which the relative time offset / phase will be `epoch_phase`. Defaults to the first time in the time series.

      epoch_phase `python:float` or `Quantity` [:ref: ‘dimensionless’, :ref: ‘time’]

        Phase of `epoch_time`. If `normalize_phase` is `True`, this should be a dimensionless value, while if `normalize_phase` is `False`, this should be a `Quantity` with time units. Defaults to 0.

      wrap_phase `python:float` or `Quantity` [:ref: ‘dimensionless’, :ref: ‘time’]

        The value of the phase above which values are wrapped back by one period. If `normalize_phase` is `True`, this should be a dimensionless value, while if `normalize_phase` is `False`, this should be a `Quantity` with time units. Defaults to half the period, so that the resulting time series goes from `-period / 2` to `period / 2` (if `normalize_phase` is `False`) or -0.5 to 0.5 (if `normalize_phase` is `True`).

      normalize_phase bool

        If `False` phase is returned as `TimeDelta`, otherwise as a dimensionless `Quantity`.

    Returns:
      folded_timeseries `TimeSeries`

        The folded time series object with phase as the `time` column.

  classmethod from_df(df, /, *, index=False, units=None)

    Create a `Table` from any `narwhals`-compatible dataframe (e.g., `pandas`, `polars`, `pyarrow`, etc).

    Parameters:
      df `Any`

        A dataframe-like object (e.g., a `pandas.DataFrame`, `polars.DataFrame`, `pyarrow.Table` or other `narwhals` compatible dataframe).

      index bool, optional

        Whether to include the index (if applicable, like in pandas) (default=False).

      units `python:dict`, optional

        A dict mapping column names to a `Unit`. The columns will have the specified unit in the Table.

    Returns:
      table `astropy.table.Table`
    Raises:
      `ImportError`

        If the narwhals library 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

    Here we convert a `polars.DataFrame` instance to a `QTable`.

        >>> import polars as pl
        >>> from astropy.table import QTable
        >>> df_polars = pl.DataFrame({
        ...     'time': [1998, 2002],
        ...     'values': [1.0, 2.0]
        ... })
        >>> QTable.from_df(df_polars, units={'values': 'm'})
        <QTable length=2>
        time  values
                m
        int64 float64
        ----- -------
        1998     1.0
        2002     2.0

  classmethod from_pandas(df, time_scale='utc')

    Convert a `DataFrame` to a `astropy.timeseries.TimeSeries`.

    Parameters:
      df `pandas.DataFrame`

        A pandas `pandas.DataFrame` instance.

      time_scale `python:str`

        The time scale to pass into `astropy.time.Time`. Defaults to `UTC`.

  group_by(keys)

    Group this table by the specified `keys`.

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

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

    > - String or list of strings corresponding to table column name(s)

    > - Numpy array (homogeneous or structured) with same length as this table

    > - `Table` with same length as this table

    Parameters:
      keys `python:str`, `python:list` of `python:str`, `numpy` `array`, or `Table`

        Key grouping object

    Returns:
      out `Table`

        New table with groups set

    Notes

    The underlying sorting algorithm is guaranteed stable, meaning that the original table order is preserved within each group.

  index_column(name)

    Return the positional index of column `name`.

    Parameters:
      name `python:str`

        column name

    Returns:
      index `python: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:
      mode `python: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:
      vals `python:tuple`, `python:list`, `python:dict` or `python:None`

        Use the specified values in the new row

      mask `python: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:
      names `python:list`

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

    Returns:
      rows python: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:
      names `python: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_lines `python:int`

        Maximum number of lines in table output

      max_width `python:int` or `python:None`

        Maximum character width of output

      show_name bool

        Include a header row for column names. Default is True.

      show_unit bool

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

      show_dtype bool

        Include a header row for column dtypes. Default 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_lines `python:int` or `python:None`

        Maximum number of rows to output

      max_width `python:int` or `python:None`

        Maximum character width of output

      show_name bool

        Include a header row for column names. Default is True.

      show_unit bool

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

      show_dtype bool

        Include a header row for column dtypes. Default is True.

      html bool

        Format the output as an HTML table. Default is False.

      tableid `python: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)

      align `python: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.

      tableclass `python: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:
      lines `python: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_lines `python:int` or `python:None`

        Maximum number of rows to output

      max_width `python:int` or `python:None`

        Maximum character width of output

      show_name bool

        Include a header row for column names. Default is True.

      show_unit bool

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

      show_dtype bool

        Include a header row for column dtypes. Default is True.

      html bool

        Format the output as an HTML table. Default is False.

      tableid `python: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)

      align `python: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.

      tableclass `python: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:
      lines `python: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_lines `python:int` or `python:None`

        Maximum number of lines in table output.

      max_width `python:int` or `python:None`

        Maximum character width of output.

      show_name bool

        Include a header row for column names. Default is True.

      show_unit bool

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

      show_dtype bool

        Include a header row for column dtypes. Default is False.

      align `python: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_lines `python:int` or `python:None`

        Maximum number of lines in table output.

      max_width `python:int` or `python:None`

        Maximum character width of output.

      show_name bool

        Include a header row for column names. Default is True.

      show_unit bool

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

      show_dtype bool

        Include a header row for column dtypes. Default is False.

      align `python: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_column=None, time_format=None, time_scale=None, format=None, *args, **kwargs)

    Read and parse a file and returns a `astropy.timeseries.TimeSeries`.

    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.TimeSeries` 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 import TimeSeries
        >>> ts = TimeSeries.read('sampled.dat', format='ascii.ecsv',
        ...                      time_column='date')

    Parameters:
      filename `python:str`

        File to parse.

      format `python:str`

        File format specifier.

      time_column `python:str`, optional

        The name of the time column.

      time_format `python:str`, optional

        The time format for the time column.

      time_scale `python:str`, optional

        The time scale for the time column.

      *args `python:tuple`, optional

        Positional arguments passed through to the data reader.

      **kwargs `python:dict`, optional

        Keyword arguments passed through to the data reader.

    Returns:
      out `astropy.timeseries.sampled.TimeSeries`

        TimeSeries corresponding to file contents.

    Notes

    The available built-in formats are:

    Format | Read | Write | Auto-identify
    --- | --- | --- | ---
    kepler.fits | Yes | No | No
    tess.fits | Yes | No | No

  remove_column(name)

    Remove a column from the table.

    This can also be done with:

        del table[name]

    Parameters:
      name `python:str`

        Name of column to remove

    Examples

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

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

    Remove column ‘b’ from the table:

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

    To remove several columns at the same time use remove_columns.

  remove_columns(names)

    Remove several columns from the table.

    Parameters:
      names `python: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:
      colname `python:str`

        Name of column

  remove_row(index)

    Remove a row from the table.

    Parameters:
      index `python:int`

        Index of row to remove

    Examples

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

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

    Remove row 1 from the table:

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

    To remove several rows at the same time use remove_rows.

  remove_rows(row_specifier)

    Remove rows from the table.

    Parameters:
      row_specifier `slice` 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:
      name `python:str`

        The current name of the column.

      new_name `python: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:
      names `python:list`, `python:tuple`

        A list or tuple of existing column names.

      new_names `python: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:
      name `python:str`

        Name of column to replace

      col `Column` or `ndarray` or python:sequence

        New column object to replace the existing column.

      copy bool

        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:
      name `python:str`

        Name of the column.

      default `object`

        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': False}, 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_lines `python:int`

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

      jsviewer bool

        If `True`, prepends some javascript headers so that the table is rendered as a DataTables data table. This allows in-browser searching & sorting, but requires a connection to the internet to load the necessary javascript libraries from a CDN. Working offline may work in limited circumstances, if the browser has cached the necessary libraries from a previous use of this method.

      browser `python:str`

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

      jskwargs `python:dict`

        Passed to the `astropy.table.JSViewer` init. Defaults to `{'use_local_files': False}` which means that the JavaScript libraries will be loaded from a CDN.

      tableid `python: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_class `python: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

      css `python:str`

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

      show_row_index `python: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.

      **kwargs `python: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:
      keys `python: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`.

      reverse bool

        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_df(backend, /, *, index=None, use_nullable_int=True)

    Convert the table to an eager DataFrame using the `narwhals` backend.

    This method supports converting Astropy Table instances into a variety of DataFrame formats via the `narwhals` library. The output can be any supported eager DataFrame type, such as `pandas`, `polars`, `pyarrow`, or others, depending on the specified backend.

    Mixin columns such as `Quantity`, `Time`, `TimeDelta`, or `SkyCoord` are automatically converted to plain Column or MaskedColumn types when necessary. Time-related mixins will be represented using `np.datetime64` or `np.timedelta64` as appropriate. All other mixins are serialized into a flat column structure using standard representations.

    Parameters:
      backend `python:str`

        The backend to use for conversion. This should be a string such as “pandas”, “polars”, or “pyarrow”.

      index `python:None`, bool, `python:str`, optional

        Specifies the index column in the resulting DataFrame.

        - If None (default), use the table’s primary index if it exists and is a single column.

        - If False, no index is set on the DataFrame.

        - If a string, use the column with that name as the index.

      use_nullable_int bool, optional

        If True (default), masked integer columns are converted to the backend’s nullable integer type. If False, an error is raised if a masked integer column is encountered.

    Returns:
      dataframe `Any`

        An eager DataFrame instance as specified by the backend.

    Raises:
      `ValueError`

        If the backend is not compatible with eager DataFrame conversion, or if the index argument is invalid.

      `ImportError`

        If the narwhals library is not installed.

    Examples

    Convert a QTable with mixin columns to a pandas DataFrame:

        >>> 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_df('pandas', index='tm')
        >>> 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

  to_pandas()

    Convert this `TimeSeries` to a `DataFrame` with a `DatetimeIndex` index.

    Returns:
      dataframe `pandas.DataFrame`

        A pandas `pandas.DataFrame` instance

  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:
      other astropy:table-like

        Data to update this table with.

      copy bool

        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:
      other astropy: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