Skip to main content
`Ctrl`+`K`

# Cds

class astropy.io.ascii.Cds(readme=None)

  Bases: `BaseReader`

  CDS format table.

  See: https://vizier.unistra.fr/doc/catstd.htx

  Example:

      Table: Table name here
      = ==============================================================================
      Catalog reference paper
          Bibliography info here
      ================================================================================
      ADC_Keywords: Keyword ; Another keyword ; etc

      Description:
          Catalog description here.
      ================================================================================
      Byte-by-byte Description of file: datafile3.txt
      --------------------------------------------------------------------------------
         Bytes Format Units  Label  Explanations
      --------------------------------------------------------------------------------
         1-  3 I3     ---    Index  Running identification number
         5-  6 I2     h      RAh    Hour of Right Ascension (J2000)
         8-  9 I2     min    RAm    Minute of Right Ascension (J2000)
        11- 15 F5.2   s      RAs    Second of Right Ascension (J2000)
      --------------------------------------------------------------------------------
      Note (1): A CDS file can contain sections with various metadata.
                Notes can be multiple lines.
      Note (2): Another note.
      --------------------------------------------------------------------------------
        1 03 28 39.09
        2 04 18 24.11

  About parsing the CDS format

  The CDS format consists of a table description and the table data. These can be in separate files as a `ReadMe` file plus data file(s), or combined in a single file. Different subsections within the description are separated by lines of dashes or equal signs (”——” or “======”). The table which specifies the column information must be preceded by a line starting with “Byte-by-byte Description of file:”.

  In the case where the table description is combined with the data values, the data must be in the last section and must be preceded by a section delimiter line (dashes or equal signs only).

  Basic usage

  Use the `ascii.read()` function as normal, with an optional `readme` parameter indicating the CDS ReadMe file. If not supplied it is assumed that the header information is at the top of the given table. Examples:

      >>> from astropy.io import ascii
      >>> table = ascii.read("data/cds.dat")
      >>> table = ascii.read("data/vizier/table1.dat", readme="data/vizier/ReadMe")
      >>> table = ascii.read("data/cds/multi/lhs2065.dat", readme="data/cds/multi/ReadMe")
      >>> table = ascii.read("data/cds/glob/lmxbrefs.dat", readme="data/cds/glob/ReadMe")

  The table name and the CDS ReadMe file can be entered as URLs. This can be used to directly load tables from the Internet. For example, Vizier tables from the CDS:

      >>> table = ascii.read("ftp://cdsarc.unistra.fr/pub/cats/VII/253/snrs.dat",
      ...             readme="ftp://cdsarc.unistra.fr/pub/cats/VII/253/ReadMe")

  If the header (ReadMe) and data are stored in a single file and there is content between the header and the data (for instance Notes), then the parsing process may fail. In this case you can instruct the reader to guess the actual start of the data by supplying `data_start='guess'` in the call to the `ascii.read()` function. You should verify that the output data table matches expectation based on the input CDS file.

  Using a reader object

  When `Cds` reader object is created with a `readme` parameter passed to it at initialization, then when the `read` method is executed with a table filename, the header information for the specified table is taken from the `readme` file. An `InconsistentTableError` is raised if the `readme` file does not have header information for the given table.

      >>> readme = "data/vizier/ReadMe"
      >>> r = ascii.get_reader(ascii.Cds, readme=readme)
      >>> table = r.read("data/vizier/table1.dat")
      >>> # table5.dat has the same ReadMe file
      >>> table = r.read("data/vizier/table5.dat")

  If no `readme` parameter is specified, then the header information is assumed to be at the top of the given table.

      >>> r = ascii.get_reader(ascii.Cds)
      >>> table = r.read("data/cds.dat")
      >>> #The following gives InconsistentTableError, since no
      >>> #readme file was given and table1.dat does not have a header.
      >>> table = r.read("data/vizier/table1.dat")
      Traceback (most recent call last):
        ...
      InconsistentTableError: No CDS section delimiter found

  Caveats:

  - The Units and Explanations are available in the column `unit` and `description` attributes, respectively.

  - The other metadata defined by this format is not available in the output table.

  Methods Summary

  `read`(table) | Read the `table` and return the results in a format determined by the `outputter` attribute.
  `write`([table]) | Not available for the CDS class (raises NotImplementedError).

  Methods Documentation

  read(table)

    Read the `table` and return the results in a format determined by the `outputter` attribute.

    The `table` parameter is any string or object that can be processed by the instance `inputter`. For the base Inputter class `table` can be one of:

    - File name

    - File-like object

    - String (newline separated) with all header and data lines (must have at least 2 lines)

    - List of strings

    Parameters:
      table `python:str`, python:file-like object, `python:list`

        Input table.

    Returns:
      table `Table`

        Output table

  write(table=None)

    Not available for the CDS class (raises NotImplementedError).