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

#### 5.1.2.4 `ecsv`

The Enhanced Character Separated Values format was developed within the Astropy project and is described in Astropy APE6 (DOI). 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 writer is currently ECSV 1.0.

ECSV allows either a space or a comma for delimiting values, controlled by the `delimiter` configuration option. If `ecsv(delimiter=comma)` is used, then removing the YAML header will leave a CSV file that can be interpreted by the CSV input handler or imported into other CSV-capable applications.

Following the ECSV 1.0 specification, array-valued columns are supported. ECSV 1.0, required for working with array-valued columns, is supported by Astropy v4.3 and later.

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(delimiter=comma,encoding=UTF-8)`". The following options are available:

`delimiter = comma|space`
  Delimiter character, which for ECSV may be either a space or a comma. Permitted values are "`space`" or "`comma`".
`encoding = ASCII|UTF-8|UTF-16|...`
  Specifies the character encoding used to write the output. ECSV 1.0 is defined to use ASCII-encoded header and data sections, so setting this encoding to a non-ASCII value such as UTF-8 will write output that is not legal ECSV 1.0. However, such files may be readable by ECSV readers that do not enforce the ASCII restriction. (Default: `US-ASCII`)

If no output format is explicitly chosen, writing to a filename with the extension "`.ecsv`" (case insensitive) will select `ECSV` format for output.

An example looks like this:

    # %ECSV 1.0
    # ---
    # datatype:
    # -
    #   name: RECNO
    #   datatype: int32
    # -
    #   name: SPECIES
    #   datatype: string
    # -
    #   name: NAME
    #   datatype: string
    #   description: How one should address the animal in public & private.
    # -
    #   name: LEGS
    #   datatype: int32
    #   meta:
    #     utype: anatomy:limb
    # -
    #   name: HEIGHT
    #   datatype: float64
    #   unit: m
    #   meta:
    #     VOTable precision: 2
    # -
    #   name: MAMMAL
    #   datatype: bool
    # meta:
    #   name: animals.vot
    #   Description: Some animals
    #   Author: Mark Taylor
    RECNO SPECIES NAME LEGS HEIGHT MAMMAL
    1 pig "Pigling Bland" 4 0.8 True
    2 cow Daisy 4 2.0 True
    3 goldfish Dobbin "" 0.05 False
    4 ant "" 6 0.001 False
    5 ant "" 6 0.001 False
    6 "queen ant" Ma'am 6 0.002 False
    7 human Mark 2 1.8 True

Next Previous Up Contents
Next: ascii
Up: Output 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