CFA(1)

NAME
cfa - create aggregated CF datasets

SYNOPSIS
cfa [-a options] [-d dir] [-f format] [-h] [-o file] [-r options] [-v] [-w options] [FILE] ...

DESCRIPTION
The cfa tool creates and writes to disk the CF fields contained in the input files.

The input files are treated as a single CF dataset following the aggregation rules currently documented in CF ticket #78 and written to a single file (see the -o option), or each input file is aggregated separately and written to its own output file (see the -d option).

Accepts CF-netCDF and CFA-netCDF files (or URLs if DAP access is enabled) and Met Office (UK) PP format files as input. Multiple input files in a mixture of formats may be given and normal UNIX file globbing rules apply. For example:

    cfa -o out.nc file1.nc file2.nc
    cfa -o out.nc file[1-9].nc
    cfa -f NETCDF3_CLASSIC -o out.nc data1/*.nc data2/*.nc
    cfa -f CFA -o out.nca data[12]/*.nc
    cfa -o out.nc test?a.pp
    cfa -f CFA -o out.nca test?a.pp fileb.nca
    cfa -d /data/archive ../test*.pp
    cfa -o out.nc file.nca
    cfa -o out.nc file.nca file?.nc
    cfa -o out.nc http://test.opendap.org/dap/coads_climatology.nc
    cfa -o out.nc http://test.opendap.org/dap/coads_climatology.nc file*.nc

The output file, or files, are in CF-netCDF or CFA-netCDF format (see the -f option).

OPTIONS

-a options, --aggregate=options
    Configure the field aggregation process with the following options:

    0   Do not aggregate fields. By default fields are aggregated if possible.

    contiguous
        Requires that aggregated fields have adjacent dimension coordinate cells which partially overlap or share common boundary values. Ignored if the dimension coordinates do not have bounds.

    no_overlap
        Requires that aggregated fields have adjacent dimension coordinate cells which do not overlap (but they may share common boundary values). Ignored if the dimension coordinates do not have bounds.

    equal_all
        Requires that aggregated fields have the same set of non-standard CF properties (including long_name), with the same values.

    exist_all
        Requires that aggregated fields have the same set of non-standard CF properties (including long_name), but not requiring the values to be the same.

    dimension=properties
        Create new dimensions for each input field which has one or more of the given properties. For each CF property in the colon (:) separated list of property names, if an input field has the property then, prior to aggregation, a new dimension is created with an auxiliary coordinate whose datum is the property's value and the property itself is deleted from that field.

    no_strict_units
        Assume that fields or their components (such as coordinates) with the same identity but missing units all have equivalent (but unspecified) units, so that aggregation may occur. This is the default for input PP files, but not for other formats.

    messages
        Print messages giving reasons why particular fields have not been aggregated.

    Multiple options are separated by commas. For example:

        -a 0
        -a exist_all
        -a contiguous,no_overlap,equal_all
        -a messages,dimension=ensemble_member
        -a dimension=ensemble_member:model,no_strict_units

-d dir, --directory=dir
    Set the directory for the output files. In this case there will one output file per input file and there will be no inter-file aggregation, but the contents of each file will be aggregated independently of the others. Output file names will be the same as their input counterparts, but with the suffix .nc or .nca for CF-netCDF and CFA-netCDF output formats respectively.

-f format, --format=format
    Set the format of the output file(s). Valid choices are NETCDF4, NETCDF4_CLASSIC, NETCDF3_64BIT and NETCDF3_CLASSIC for outputting CF-netCDF files in those netCDF formats; or CFA for outputting CFA-netCDF files (in NETCDF3_CLASSIC format). Note that the NETCDF3 and NETCDF4_CLASSIC formats may be slower than any of the other options.

    By default, NETCDF3_CLASSIC is assumed.

-h, --help
    Display the man page.

-o outfile, --outfile=file
    Set the output netCDF file name. In this case the CF fields from all input files are written to this file.

-r options, --read=options
    Configure the file reading process with the following options:

    ignore_ioerror
        Ignore, without failing, any file which causes an I/O error whilst being read, as would be the case for an empty file, unknown file format, etc. By default, an error occurs and the return code is non-zero.

    umversion=version
        For PP format files only, the Unified Model (UM) version to be used when decoding the PP header. Valid versions are, for example, 4.2, 6.6.3 and 8.2. The default version is 4.5. The version is ignored if it can be inferred from the PP headers, which will generally be the case for files created at versions 5.3 and later. Note that the PP header can not encode tertiary version elements (such as the 3 in 6.6.3), so it may be necessary to provide a UM version in such cases.

        Ignored for input files of any other format.

    Multiple options are separated by commas. For example:

        -r ignore_ioerror
        -r umversion=5.1
        -r umversion=6.6.3,ignore_ioerror

-v, --verbose
    Display a one-line summary of each output CF field.

-w options, --write=options
    Configure the file writing process with the following options:

    overwrite
        Allow pre-existing output files to be overwritten.

    base, base=value
        For output CFA-netCDF files only. File names referenced by an output CFA-netCDF file have relative, as opposed to absolute, paths or URL bases. This may be useful when relocating a CFA-netCDF file together with the datasets referenced by it.

        If set with no value then file names are given relative to the directory or URL base containing the output CFA-netCDF file. If set with a value then file names are given relative to the directory or URL base described by the value. By default, file names within CFA-netCDF files are stored with absolute paths.

        Ignored for output files of any other format.

    Multiple options are separated by commas. For example:

        -w overwrite
        -w base=/data/archive
        -w base=../archive,overwrite
        -w base=$HOME
        -w base

SEE ALSO
cfdump(1)

BUGS
Reports of bugs are welcome at cfpython.bitbucket.org

LICENSE
Open Source Initiative MIT License

AUTHOR
David Hassell