Next Previous Up Contents
Next: ascii
Up: Input Formats
Previous: csv

#### 5.1.1.6 `ecsv`

The Enhanced Character Separated Values format was developed within the Astropy project and is described at https://github.com/astropy/astropy-APEs/blob/master/APE6.rst. It is composed of a YAML header followed by a CSV-like body, and is intended to be a human-readable and maybe even human-writable format with rich metadata. Most of the useful per-column and per-table metadata is preserved when de/serializing to this format. The version supported by this reader is currently ECSV 0.9.

There are various ways to format the YAML header, but a simple example of an ECSV file looks like this:

    # %ECSV 0.9
    # ---
    # delimiter: ','
    # datatype: [
    #   { name: index,   datatype: int32   },
    #   { name: Species, datatype: string  },
    #   { name: Name,    datatype: string  },
    #   { name: Legs,    datatype: int32   },
    #   { name: Height,  datatype: float64, unit: m },
    #   { name: Mammal,  datatype: bool    },
    # ]
    index,Species,Name,Legs,Height,Mammal
    1,pig,Bland,4,,True
    2,cow,Daisy,4,2,True
    3,goldfish,Dobbin,,0.05,False
    4,ant,,6,0.001,False
    5,ant,,6,0.001,False
    6,human,Mark,2,1.9,True

If you follow this pattern, it's possible to write your own ECSV files by taking an existing CSV file and decorating it with a header that gives column datatypes, and possibly other metadata such as units. This allows you to force the datatype of given columns (the CSV reader guesses datatype based on content, but can get it wrong) and it can also be read much more efficiently than a CSV file and its format can be detected automatically.

The ECSV datatypes that work well with this reader are `bool`, `int8`, `int16`, `int32`, `int64`, `float32`, `float64` and `string`.

The handler behaviour may be modified by specifying one or more comma-separated name=value configuration options in parentheses after the handler name, e.g. "`ecsv(header=http://andromeda.star.bris.ac.uk/gaia-edr3/edr3-header.ecsv,colcheck=FAIL)`". The following options are available:

`header = <filename-or-url>`
  Location of a file containing a header to be applied to the start of the input file. By using this you can apply your own ECSV-format metadata to plain CSV files.
`colcheck = IGNORE|WARN|FAIL`
  Determines the action taken if the columns named in the YAML header differ from the columns named in the first line of the CSV part of the file.

This format can be automatically identified by its content so you do not need to specify the format explicitly when reading ECSV tables, regardless of the filename.

Next Previous Up Contents
Next: ascii
Up: Input Formats
Previous: csv

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk