astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v5.2.1 »
- Data Tables (`astropy.table`) »
- Column

# Column

class astropy.table.Column(data=None, name=None, dtype=None, shape=(), length=0, description=None, unit=None, format=None, meta=None, copy=False, copy_indices=True)

  Bases: `BaseColumn`

  Define a data column for use in a Table object.

  Parameters:
    data `python:list`, `ndarray`, or `python:None`

      Column data values

    name `python:str`

      Column name and key for reference within Table

    dtype `dtype` astropy:-like

      Data type for column

    shape `python:tuple` or ()

      Dimensions of a single row element in the column data

    length `python:int` or 0

      Number of row elements in column data

    description `python:str` or `python:None`

      Full description of column

    unit `python:str` or `python:None`

      Physical unit

    format `python:str`, `python:None`, or `python:callable()`

      Format string for outputting column values. This can be an “old-style” (`format % value`) or “new-style” (`str.format`) format specification string or a function or any callable object that accepts a single value and returns a string.

    meta dict-like or `python:None`

      Meta-data associated with the column

  Examples

  A Column can be created in two different ways:

  - Provide a `data` value but not `shape` or `length` (which are inferred from the data).

    Examples:

        col = Column(data=[1, 2], name='name')  # shape=(2,)
        col = Column(data=[[1, 2], [3, 4]], name='name')  # shape=(2, 2)
        col = Column(data=[1, 2], name='name', dtype=float)
        col = Column(data=np.array([1, 2]), name='name')
        col = Column(data=['hello', 'world'], name='name')

    The `dtype` argument can be any value which is an acceptable fixed-size data-type initializer for the numpy.dtype() method. See https://numpy.org/doc/stable/reference/arrays.dtypes.html. Examples include:

    - Python non-string type (float, int, bool)

    - Numpy non-string type (e.g. np.float32, np.int64, np.bool_)

    - Numpy.dtype array-protocol type strings (e.g. ‘i4’, ‘f8’, ‘S15’)

    If no `dtype` value is provide then the type is inferred using `np.array(data)`.

  - Provide `length` and optionally `shape`, but not `data`

    Examples:

        col = Column(name='name', length=5)
        col = Column(name='name', dtype=int, length=10, shape=(3,4))

    The default `dtype` is `np.float64`. The `shape` argument is the array shape of a single cell in the column.

  To access the `Column` data as a raw `numpy.ndarray` object, you can use one of the `data` or `value` attributes (which are equivalent):

      col.data
      col.value

  Attributes Summary

  `name` | The name of this column.
  `quantity` | A view of this table column as a `Quantity` object with units given by the Column's `unit` parameter.
  `unit` | The unit associated with this column.

  Methods Summary

  `convert_unit_to`(new_unit[, equivalencies]) | Converts the values of the column in-place from the current unit to the given unit.
  `copy`([order, data, copy_data]) | Return a copy of the current instance.
  `insert`(obj, values[, axis]) | Insert values before the given indices in the column and return a new `Column` object.
  `more`([max_lines, show_name, show_unit]) | Interactively browse column with a paging interface.
  `pformat`([max_lines, show_name, show_unit, ...]) | Return a list of formatted string representation of column values.
  `pprint`([max_lines, show_name, show_unit, ...]) | Print a formatted string representation of column values.
  `to`(unit[, equivalencies]) | Converts this table column to a `Quantity` object with the requested units.

  Attributes Documentation

  name

    The name of this column.

  quantity

    A view of this table column as a `Quantity` object with units given by the Column’s `unit` parameter.

  unit

    The unit associated with this column. May be a string or a `astropy.units.UnitBase` instance.

    Setting the `unit` property does not change the values of the data. To perform a unit conversion, use `convert_unit_to`.

  Methods Documentation

  convert_unit_to(new_unit, equivalencies=[])

    Converts the values of the column in-place from the current unit to the given unit.

    To change the unit associated with this column without actually changing the data values, simply set the `unit` property.

    Parameters:
      new_unit `python:str` or `astropy.units.UnitBase` instance

        The unit to convert to.

      equivalencies `python:list` of `python:tuple`

        A list of equivalence pairs to try if the unit are not directly convertible. See Equivalencies.

    Raises:
      `astropy.units.UnitsError`

        If units are inconsistent

  copy(order='C', data=None, copy_data=True)

    Return a copy of the current instance.

    If `data` is supplied then a view (reference) of `data` is used, and `copy_data` is ignored.

    Parameters:
      order{‘C’, ‘F’, ‘A’, ‘K’}, optional

        Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if `a` is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of `a` as closely as possible. (Note that this function and :func:numpy.copy are very similar, but have different default values for their order= arguments.) Default is ‘C’.

      data `array`, optional

        If supplied then use a view of `data` instead of the instance data. This allows copying the instance attributes and meta.

      copy_data bool, optional

        Make a copy of the internal numpy array instead of using a reference. Default is True.

    Returns:
      col `Column` or `MaskedColumn`

        Copy of the current column (same type as original)

  insert(obj, values, axis=0)

    Insert values before the given indices in the column and return a new `Column` object.

    Parameters:
      obj `python:int`, `slice` or python:sequence of `python:int`

        Object that defines the index or indices before which `values` is inserted.

      values numpy:array_like

        Value(s) to insert. If the type of `values` is different from that of the column, `values` is converted to the matching type. `values` should be shaped so that it can be broadcast appropriately.

      axis `python:int`, optional

        Axis along which to insert `values`. If `axis` is None then the column array is flattened before insertion. Default is 0, which will insert a row.

    Returns:
      out `Column`

        A copy of column with `values` and `mask` inserted. Note that the insertion does not occur in-place: a new column is returned.

  more(max_lines=None, show_name=True, show_unit=False)

    Interactively browse column 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.

      show_name bool

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

      show_unit bool

        Include a header row for unit. Default is False.

  pformat(max_lines=None, show_name=True, show_unit=False, show_dtype=False, html=False)

    Return a list of formatted string representation of column values.

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

    Parameters:
      max_lines `python:int`

        Maximum lines of output (header + data rows)

      show_name bool

        Include column name. Default is True.

      show_unit bool

        Include a header row for unit. Default is False.

      show_dtype bool

        Include column dtype. Default is False.

      html bool

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

    Returns:
      lines `python:list`

        List of lines with header and formatted column values

  pprint(max_lines=None, show_name=True, show_unit=False, show_dtype=False)

    Print a formatted string representation of column values.

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

    Parameters:
      max_lines `python:int`

        Maximum number of values in output

      show_name bool

        Include column name. Default is True.

      show_unit bool

        Include a header row for unit. Default is False.

      show_dtype bool

        Include column dtype. Default is True.

  to(unit, equivalencies=[], **kwargs)

    Converts this table column to a `Quantity` object with the requested units.

    Parameters:
      unit astropy:unit-like

        The unit to convert to (i.e., a valid argument to the `astropy.units.Quantity.to()` method).

      equivalencies `python:list` of `python:tuple`

        Equivalencies to use for this conversion. See `astropy.units.Quantity.to()` for more details.

    Returns:
      quantity `Quantity`

        A quantity object with the contents of this column in the units `unit`.