Worked examples: the ANTS command line tools#

ANTS Command Line Tools introduces the five general purpose command line tools that ship with ANTS, and their individual pages (ancil_2anc.py, ancil_create_shapefile.py, ancil_fill_n_merge.py, ancil_general_regrid.py, ancil_vertical_regrid.py) document their full set of arguments. This tutorial instead walks through a realistic invocation of each tool, so you can see how they fit together in practice.

All five tools share a common command line interface, provided by ants.command_parse.AntsArgParser:

<tool>.py <SOURCE1> [<SOURCE2> ...] --output <OUTPUT> [--ants-config <CONFIG>]

and are typically launched via the ants-launch wrapper, as shown below.

ancil_2anc: converting between fileformats#

ancil_2anc.py loads one or more cubes and writes them out as NetCDF and/or an F03 ancillary file, inferring as much metadata as it can from the source. It is a straight fileformat translation - see Loading and saving data with ANTS for the underlying load/save mechanics.

ancil_2anc.py land_cover_fraction.nc \
    --output land_cover_fraction_ancil \
    --grid-staggering 6 \
    --ants-config rose-app-run.conf

The --grid-staggering argument (3 for New Dynamics, 6 for ENDGame) is often required, since it usually cannot be inferred from a NetCDF source.

ancil_create_shapefile: producing a validity polygon#

ancil_create_shapefile.py turns a JSON file containing a list of [longitude, latitude] pairs into a shapefile polygon, which can then be used as the validity_polygon input to ancil_fill_n_merge (see Merging datasets and filling missing data).

A minimal input JSON, defining a simple box:

[[-10.0, 40.0], [-10.0, 60.0], [10.0, 60.0], [10.0, 40.0]]

ancil_create_shapefile.py validity_region.json validity_region.shp

ancil_fill_n_merge: merging and filling#

ancil_fill_n_merge.py merges a primary and (optional) alternate source and fills any remaining missing points - see Merging datasets and filling missing data for the concepts. --search-method kdtree is recommended for consistency across UM and LFRic pipelines:

ancil_fill_n_merge.py primary_source.nc alternate_source.nc \
    --output merged_filled \
    --target-lsm target_lsm.nc \
    --polygon validity_region.shp \
    --search-method kdtree \
    --ants-config rose-app-run.conf

If only primary_source.nc is provided (no alternate), only the fill stage runs.

ancil_general_regrid: regridding to a target grid#

ancil_general_regrid.py regrids a source onto a target grid or target land sea mask - see Regridding an ancillary field to a target grid for the underlying mechanics:

ancil_general_regrid.py source_field.nc \
    --output regridded_field \
    --target-grid target_grid_namelist \
    --ants-config rose-app-run.conf

To regrid directly onto a target land sea mask instead of a plain grid, use --target-lsm in place of --target-grid; the result will be made consistent with that mask using the same fill algorithms discussed in Merging datasets and filling missing data.

This application has no default regridding scheme the --ants-config file passed above (rose-app-run.conf) must include a [ants_regridding_horizontal] section (and a [ants_regridding_vertical] section too, if the target also varies vertically), for example:

[ants_regridding_horizontal]
scheme = Linear

See ants.config.GlobalConfiguration for the full list of valid scheme values. Omitting this section raises an error.

Note

ancil_vertical_regrid is available for vertical only regrid operations or cases where you want to ensure a vertical regrid is carried out before any other processing.

ancil_vertical_regrid: regridding onto a new vertical level set#

ancil_vertical_regrid.py is the vertical-only counterpart to ancil_general_regrid. Rather than moving data onto a new horizontal grid, it interpolates onto a new set of vertical levels (for example a target vertical namelist), and requires that the source and target already share the same horizontal (latitude/longitude) coordinates:

ancil_vertical_regrid.py aerosol_3d.nc \
    --output aerosol_3d_L70 \
    --target-grid vertlevs_L70_50t_20s_80km \
    --ants-config rose-app-run.conf

This application has no default vertical scheme - the --ants-config file passed above (rose-app-run.conf) must include a [ants_regridding_vertical] section specifying one, for example:

[ants_regridding_vertical]
scheme = Linear

See ants.config.GlobalConfiguration for the full list of valid scheme values. Omitting this section raises an error.

Note

ancil_vertical_regrid checks its target before regridding: if the target is a UGrid mesh, it raises an error directing you to the regrid-to-mesh application in UG-ANTS instead; if the target’s latitude/longitude coordinates do not match the source’s, it raises an error rather than silently regridding horizontally too. Use ancil_general_regrid.py (see Regridding an ancillary field to a target grid) when a horizontal regrid is also needed.

Decomposition configuration#

All five tools accept --ants-config to point at an ANTS configuration file. This is most commonly used to enable ANTS Decomposition Framework for large datasets, for example:

[ants_decomposition]
x_split = 2
y_split = 2

[ants_logging]
enabled = True

Key Points#

  • All five command line tools share the same <sources> --output <output> [--ants-config <config>] interface via ants.command_parse.AntsArgParser.

  • ancil_2anc is for fileformat translation, ancil_create_shapefile produces validity polygons, ancil_fill_n_merge combines and fills data, ancil_general_regrid moves data onto a target horizontal grid (and can carry out vertical regridding too), and ancil_vertical_regrid moves data onto a target set of vertical levels.

  • Prefer --search-method kdtree on ancil_fill_n_merge and ancil_general_regrid for consistency across UM and LFRic pipelines (see Merging datasets and filling missing data).

  • If you want to do a vertical regrid for UGrid target domains use the UG-ANTS tooling instead.

  • See the rose-stem/app/ directory in the ANTS repository for complete, runnable configurations of each of these tools.

See Also#

On this page
Show Source