Skip to main content
`Ctrl`+`K`

# MaskedColumn

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

  Bases: `Column`, `_MaskedColumnGetitemShim`, `MaskedArray`

  Define a masked 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

    mask `python:list`, `ndarray` or `python:None`

      Boolean mask for which True indicates missing or invalid data

    fill_value `python:float`, `python:int`, `python:str`, or `python:None`

      Value used when filling masked column elements

    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 MaskedColumn is similar to a Column except that it includes `mask` and `fill_value` attributes. It can be created in two different ways:

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

    Examples:

        col = MaskedColumn(data=[1, 2], name='name')
        col = MaskedColumn(data=[1, 2], name='name', mask=[True, False])
        col = MaskedColumn(data=[1, 2], name='name', dtype=float, fill_value=99)

    The `mask` argument will be cast as a boolean array and specifies which elements are considered to be missing or invalid.

    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)`. When `data` is provided then the `shape` and `length` arguments are ignored.

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

    Examples:

        col = MaskedColumn(name='name', length=5)
        col = MaskedColumn(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.ma.MaskedArray` object, you can use one of the `data` or `value` attributes (which are equivalent):

      col.data
      col.value

  Attributes Summary

  `data` | The plain MaskedArray data held by this column.
  `fill_value` | The filling value of the masked array is a scalar.
  `info` | Container for meta information like name, description, format.
  `name` | The name of 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.
  `filled`([fill_value]) | Return a copy of self, with masked values filled with a given value.
  `insert`(obj, values[, mask, axis]) | Insert values along the given axis before the given indices and return a new `MaskedColumn` 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.

  Attributes Documentation

  data

    The plain MaskedArray data held by this column.

  fill_value
  info

    Container for meta information like name, description, format.

    This is required when the object is used as a mixin column within a table, but can be used as a general way to store meta information. In this case it just adds the `mask_val` attribute.

  name

    The name of this column.

  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)

  filled(fill_value=None)

    Return a copy of self, with masked values filled with a given value.

    Parameters:
      fill_value scalar; optional

        The value to use for invalid entries (`None` by default). If `None`, the `fill_value` attribute of the array is used instead.

    Returns:
      filled_column `Column`

        A copy of `self` with masked entries replaced by `fill_value` (be it the function argument or the attribute of `self`).

  insert(obj, values, mask=None, axis=0)

    Insert values along the given axis before the given indices and return a new `MaskedColumn` 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.

      mask bool or numpy:array_like

        Mask value(s) to insert. If not supplied, and values does not have a mask either, then False is used.

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

        A copy of column with `values` and `mask` inserted. Note that the insertion does not occur in-place: a new masked 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=-1, show_name=True, show_unit=False, show_dtype=False, html=False)

    Return a list of formatted string representation of column values.

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

    Parameters:
      max_lines `python:int` or `python:None`

        Maximum lines of output (header + data rows). -1 (default) implies no limit, `None` implies using the height of the current terminal.

      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 `max_lines=None` (default) 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.