astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v0.3 »
- Data Tables (`astropy.table`) »
- Table

# Table

class `astropy.table.table.``Table`(data=None, masked=None, names=None, dtype=None, meta=None, copy=True, dtypes=None)

  Bases: `object`

  A class to represent tables of heterogeneous data.

  `Table` provides a class for heterogeneous tabular data, making use of a `numpy` structured array internally to store the data values. A key enhancement provided by the `Table` class is the ability to easily modify the structure of the table by adding or removing columns, or adding new rows of data. In addition table and column metadata are fully supported.

  `Table` differs from `NDData` by the assumption that the input data consists of columns of homogeneous data, where each column has a unique identifier and may contain additional metadata such as the data unit, format, and description.

  Parameters:

  data : numpy ndarray, dict, list, or Table, optional

  > Data to initialize table.

  masked : bool, optional

  > Specify whether the table is masked.

  names : list, optional

  > Specify column names

  dtype : list, optional

  > Specify column data types

  meta : dict, optional

  > Metadata associated with the table.

  copy : bool, optional

  > Copy the input data (default=True).

  Attributes Summary

  `ColumnClass` |
  `colnames` |
  `dtype` |
  `groups` |
  `mask` |
  `masked` |

  Methods Summary

  `add_column`(col[, index]) | Add a new Column object `col` to the table.
  `add_columns`(cols[, indexes]) | Add a list of new Column objects `cols` to the table.
  `add_row`([vals, mask]) | Add a new row to the end of the table.
  `argsort`([keys, kind]) | Return the indices which would sort the table according to one or more key columns.
  `copy`([copy_data]) | Return a copy of the table :Parameters: copy_data : bool If True (the default), copy the underlying data array.
  `create_mask`() |
  `field`(item) | Return column[item] for recarray compatibility.
  `filled`([fill_value]) | Return a copy of self, with masked values filled.
  `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.
  `index_column`(name) | Return the positional index of column `name`.
  `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.
  `next`() | Python 3 iterator
  `pformat`([max_lines, max_width, show_name, ...]) | Return a list of lines for the formatted string representation of the table.
  `pprint`([max_lines, max_width, show_name, ...]) | Print a formatted string representation of the table.
  `read`(*args, **kwargs) | Read and parse a data table and return as a Table.
  `remove_column`(name) | Remove a column from the table.
  `remove_columns`(names) | Remove several columns from the table :Parameters: names : list A list containing the names of the columns to remove ..
  `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.
  `reverse`() | Reverse the row order of table rows.
  `show_in_browser`([css, max_lines, jsviewer, ...]) | Render the table in HTML and show it in a web browser.
  `sort`(keys) | Sort the table according to one or more keys.
  `write`(*args, **kwargs) | Write this Table object out in the specified format.

  Attributes Documentation

  `ColumnClass`
  `colnames`
  `dtype`
  `groups`
  `mask`
  `masked`

  Methods Documentation

  `add_column`(col, index=None)

    Add a new Column object `col` to the table. If `index` is supplied then insert column before `index` position in the list of columns, otherwise append column to the end of the list.

    Parameters:

    col : Column

    > Column object to add.

    index : int or None

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

    Examples

    Create a table with two columns ‘a’ and ‘b’:

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

    Create a third column ‘c’ and append it to the end of the table:

        >>> col_c = Column(name='c', data=['x', 'y', 'z'])
        >>> t.add_column(col_c)
        >>> print t
         a   b   c
        --- --- ---
          1 0.1   x
          2 0.2   y
          3 0.3   z

    Add column ‘d’ at position 1. Note that the column is inserted before the given index:

        >>> col_d = Column(name='d', data=['a', 'b', 'c'])
        >>> t.add_column(col_d, 1)
        >>> print t
         a   d   b   c
        --- --- --- ---
          1   a 0.1   x
          2   b 0.2   y
          3   c 0.3   z

    To add several columns use add_columns.

  `add_columns`(cols, indexes=None)

    Add a list of new Column objects `cols` to the table. 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.

    Parameters:

    cols : list of Columns

    > Column objects to add.

    indexes : list of ints or None

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

    Examples

    Create a table with two columns ‘a’ and ‘b’:

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

    Create column ‘c’ and ‘d’ and append them to the end of the table:

        >>> col_c = Column(name='c', data=['x', 'y', 'z'])
        >>> col_d = Column(name='d', data=['u', 'v', 'w'])
        >>> t.add_columns([col_c, col_d])
        >>> print t
         a   b   c   d
        --- --- --- ---
          1 0.1   x   u
          2 0.2   y   v
          3 0.3   z   w

    Add column ‘c’ at position 0 and column ‘d’ at position 1. Note that the columns are inserted before the given position:

        >>> t = Table([[1, 2, 3], [0.1, 0.2, 0.3]], names=('a', 'b'))
        >>> col_c = Column(name='c', data=['x', 'y', 'z'])
        >>> col_d = Column(name='d', data=['u', 'v', 'w'])
        >>> t.add_columns([col_c, col_d], [0, 1])
        >>> print t
         c   a   d   b
        --- --- --- ---
          x   1   u 0.1
          y   2   v 0.2
          z   3   w 0.3

  `add_row`(vals=None, mask=None)

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

    > Use the specified 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'))
        >>> t.pprint()
         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])
        >>> t.pprint()
          a   b   c
          --- --- ---
          1   4   7
          2   5   8
          3   6   9

  `argsort`(keys=None, kind=None)

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

    > The column name(s) to order the table by

    kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

    > Sorting algorithm.

    Returns:

    index_array : ndarray, int

    > Array of indices that sorts the table by the specified key column(s).

  `copy`(copy_data=True)

    Return a copy of the table

    Parameters:

    copy_data : bool

    > If True (the default), copy the underlying data array. Otherwise, use the same data array

  `create_mask`()
  `field`(item)

    Return column[item] for recarray compatibility.

  `filled`(fill_value=None)

    Return a copy of self, with masked values filled.

    If input `fill_value` supplied then that value is used for all masked entries in the table. Otherwise the individual `fill_value` defined for each table column is used.

    Returns:

    filled_table : Table

    > New table with masked values filled

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

    > Key grouping object

    Returns:

    out : Table

    > New table with groups set

  `index_column`(name)

    Return the positional index of column `name`.

    Parameters:

    name : str

    > column name

    Returns:

    index : int

    > Positional index of column `name`.

    Examples

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

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

    Get index of column ‘b’ of the table:

        >>> t.index_column('b')
        1

  `keep_columns`(names)

    Keep only the columns specified (remove the others).

    Parameters:

    names : list

    > A list containing the names of the columns to keep. All other columns will be removed.

    Examples

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

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

    Specifying only a single column name keeps only this column. Keep only column ‘a’ of the table:

        >>> t.keep_columns('a')
        >>> print t
         a
        ---
          1
          2
          3

    Specifying a list of column names is keeps is also possible. Keep columns ‘a’ and ‘c’ of the table:

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

  `keys`()
  `more`(max_lines=None, max_width=None, show_name=True, show_unit=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 : int

    > Maximum number of lines in table output

    max_width : int or None

    > Maximum character width of output

    show_name : bool

    > Include a header row for column names (default=True)

    show_unit : bool

    > Include a header row for unit (default=False)

  `next`()

    Python 3 iterator

  `pformat`(max_lines=None, max_width=None, show_name=True, show_unit=False, html=False, tableid=None)

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

    If no value of `max_lines` is supplied then the height of the screen terminal is used to set `max_lines`. If the terminal height cannot be determined then the default is taken from the configuration item `astropy.table.pprint.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.table.pprint.MAX_WIDTH`.

    Parameters:

    max_lines : int or None

    > Maximum number of rows to output

    max_width : int or None

    > Maximum character width of output

    show_name : bool

    > Include a header row for column names (default=True)

    show_unit : bool

    > Include a header row for unit (default=False)

    html : bool

    > Format the output as an HTML table (default=False)

    tableid : str or None

    > An ID tag for the table; only used if html is set. Default is “table{id}”, where id is the unique integer id of the table object, id(self)

    Returns:

    lines : list

    > Formatted table as a list of strings

  `pprint`(max_lines=None, max_width=None, show_name=True, show_unit=False)

    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.table.pprint.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.table.pprint.MAX_WIDTH`.

    Parameters:

    max_lines : int

    > Maximum number of lines in table output

    max_width : int or None

    > Maximum character width of output

    show_name : bool

    > Include a header row for column names (default=True)

    show_unit : bool

    > Include a header row for unit (default=False)

  classmethod `read`(*args, **kwargs)

    Read and parse a data table and return as a Table.

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

        >>> from astropy.table import Table
        >>> dat = Table.read('table.dat', format='ascii')
        >>> events = Table.read('events.fits', format='fits')

    The arguments and keywords (other than `format`) provided to this function are passed through to the underlying data reader (e.g. `read`).

    The available built-in formats are:

    Format | Read | Write | Auto-identify | Deprecated
    --- | --- | --- | --- | ---
    ascii | Yes | Yes | No |
    ascii.aastex | Yes | Yes | No |
    ascii.basic | Yes | Yes | No |
    ascii.cds | Yes | No | No |
    ascii.commented_header | Yes | Yes | No |
    ascii.daophot | Yes | No | No |
    ascii.fixed_width | Yes | Yes | No |
    ascii.fixed_width_no_header | Yes | Yes | No |
    ascii.fixed_width_two_line | Yes | Yes | No |
    ascii.ipac | Yes | Yes | No |
    ascii.latex | Yes | Yes | Yes |
    ascii.no_header | Yes | Yes | No |
    ascii.rdb | Yes | Yes | Yes |
    ascii.sextractor | Yes | No | No |
    ascii.tab | Yes | Yes | No |
    fits | Yes | Yes | Yes |
    hdf5 | Yes | Yes | Yes |
    votable | Yes | Yes | Yes |
    aastex | Yes | Yes | No | Yes
    cds | Yes | No | No | Yes
    daophot | Yes | No | No | Yes
    ipac | Yes | Yes | No | Yes
    latex | Yes | Yes | No | Yes
    rdb | Yes | Yes | No | Yes

    Deprecated format names like `aastex` will be removed in a future version. Use the full name (e.g. `ascii.aastex`) instead.

  `remove_column`(name)

    Remove a column from the table.

    This can also be done with:

        del table[name]

    Parameters:

    name : str

    > Name of column to remove

    Examples

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

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

    Remove column ‘b’ from the table:

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

    To remove several columns at the same time use remove_columns.

  `remove_columns`(names)

    Remove several columns from the table

    Parameters:

    names : list

    > A list containing the names of the columns to remove

    Examples

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

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

    Remove columns ‘b’ and ‘c’ from the table:

        >>> t.remove_columns(['b', 'c'])
        >>> print t
         a
        ---
          1
          2
          3

    Specifying only a single column also works. Remove column ‘b’ from the table:

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

    This gives the same as using remove_column.

  `remove_row`(index)

    Remove a row from the table.

    Parameters:

    index : int

    > Index of row to remove

    Examples

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

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

    Remove row 1 from the table:

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

    To remove several rows at the same time use remove_rows.

  `remove_rows`(row_specifier)

    Remove rows from the table.

    Parameters:

    row_specifier : slice, int, or array of ints

    > Specification for rows to remove

    Examples

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

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

    Remove rows 0 and 2 from the table:

        >>> t.remove_rows([0, 2])
        >>> print t
         a   b   c
        --- --- ---
          2 0.2   y

    Note that there are no warnings if the slice operator extends outside the data:

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

  `rename_column`(name, new_name)

    Rename a column.

    This can also be done directly with by setting the `name` attribute for a column:

        table[name].name = new_name

    Parameters:

    name : str

    > The current name of the column.

    new_name : str

    > The new name for the column

    Examples

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

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

    Renaming column ‘a’ to ‘aa’:

        >>> t.rename_column('a' , 'aa')
        >>> t.pprint()
         aa  b   c
        --- --- ---
          1   3   5
          2   4   6

  `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'))
        >>> t.pprint()
        firstname   name  tel
        --------- ------- ---
              Max  Miller  12
               Jo  Miller  15
             John Jackson  18

    Reversing order:

        >>> t.reverse()
        >>> t.pprint()
        firstname   name  tel
        --------- ------- ---
             John Jackson  18
               Jo  Miller  15
              Max  Miller  12

  `show_in_browser`(css='table, th, td, tr, tbody {border: 1px solid black; border-collapse: collapse;}', max_lines=5000, jsviewer=False, jskwargs={}, tableid=None, browser='default')

    Render the table in HTML and show it in a web browser. In order to make a persistent html file, i.e. one that survives refresh, the returned file object must be kept in memory.

    Parameters:

    css : string

    > A valid CSS string declaring the formatting for the table

    max_lines : int

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

    jsviewer : bool

    > If True, prepends some javascript headers so that the table is rendered as a https://datatables.net data table. This allows in-browser searching & sorting. See `JSViewer`

    jskwargs : dict

    > Passed to the `JSViewer` init

    tableid : str or None

    > An html ID tag for the table. Default is “table{id}”, where id is the unique integer id of the table object, id(self)

    browser : str

    > Any legal browser name, e.g. ‘firefox’,’chrome’,’safari’ (for mac, you may need to use ‘open -a “/Applications/Google Chrome.app” %s’ for Chrome). If ‘default’, will use the system default browser.

    Returns: | A :py:`tempfile.NamedTemporaryFile` object pointing to the html file on : disk. :

  `sort`(keys)

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

    Parameters:

    keys : str or list of str

    > The key(s) to order the table by

    Examples

    Create a table with 3 columns:

        >>> t = Table([['Max', 'Jo', 'John'], ['Miller','Miller','Jackson'],
        ...         [12,15,18]], names=('firstname','name','tel'))
        >>> t.pprint()
        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'])
        >>> t.pprint()
        firstname   name  tel
        --------- ------- ---
             John Jackson  18
               Jo  Miller  15
              Max  Miller  12

  `write`(*args, **kwargs)

    Write this Table object out in the specified format.

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

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

    The arguments and keywords (other than `format`) provided to this function are passed through to the underlying data reader (e.g. `write`).

    The available built-in formats are:

    Format | Read | Write | Auto-identify | Deprecated
    --- | --- | --- | --- | ---
    ascii | Yes | Yes | No |
    ascii.aastex | Yes | Yes | No |
    ascii.basic | Yes | Yes | No |
    ascii.commented_header | Yes | Yes | No |
    ascii.fixed_width | Yes | Yes | No |
    ascii.fixed_width_no_header | Yes | Yes | No |
    ascii.fixed_width_two_line | Yes | Yes | No |
    ascii.ipac | Yes | Yes | No |
    ascii.latex | Yes | Yes | Yes |
    ascii.no_header | Yes | Yes | No |
    ascii.rdb | Yes | Yes | Yes |
    ascii.tab | Yes | Yes | No |
    fits | Yes | Yes | Yes |
    hdf5 | Yes | Yes | Yes |
    votable | Yes | Yes | Yes |
    aastex | Yes | Yes | No | Yes
    ipac | Yes | Yes | No | Yes
    latex | Yes | Yes | No | Yes
    rdb | Yes | Yes | No | Yes

    Deprecated format names like `aastex` will be removed in a future version. Use the full name (e.g. `ascii.aastex`) instead.