Next Previous Up Contents
Next: CDF
Up: Supported Input Formats
Previous: VOTable

#### 4.1.1.4 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 per-column and per-table metadata used by TOPCAT is preserved when de/serializing to this format. TOPCAT currently supports 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 also allows TOPCAT to read the file much more efficiently, and to recognise the file format automatically.

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

Next Previous Up Contents
Next: CDF
Up: Supported Input Formats
Previous: VOTable

TOPCAT - Tool for OPerations on Catalogues And Tables
Starlink User Note253
TOPCAT web page: http://www.starlink.ac.uk/topcat/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk