Output files

FrameIt produces NetCDF output files that are designed to be shareable and easy to reuse with standard tools (xarray, NCO, CDO, ncview).

The output files are :

  • cyclone track dataset

  • user-requested variables extracted on a cartesian box

  • user-requested variables extracted on a polar grid (optional)

Naming convention

All files use the configuration field conf.simulation_name as a prefix (see Configuration file (YAML)), referred to below as SIMU.

Track file:

  • SIMU.track.nc

Group files (one file per group key in the output dictionaries):

  • SIMU.cart.<group>.nc (cartesian crop products)

  • SIMU.polar.<group>.nc (polar projection products)

The <group> token is the corresponding key of the dictionary (for example surface, level, heightAboveGround). The name is sanitized for filenames (any non-alphanumeric character is replaced by _), but the original group name is preserved in the file metadata (see below).

By default, files are written in the runner output directory: conf.frameit_output_dir (see Configuration file (YAML)),

Produced files

SIMU.track.nc

This file contains the cyclone trajectory and kinematic diagnostics computed by the tracking module and typically includes:

  • Coordinates: time

  • Data variables: center indices (for example cx, cy), latitude and longitude, motion estimates (for example heading_deg, speed), and any additional diagnostic variables created by enrich_track_with_kinematics.

This file is intended to be the minimal entry point to interpret all other FrameIt products.

SIMU.cart.<group>.nc

These files contain user-requested fields extracted on a cartesian box around the storm center or the fixed subdomain center.

Typical structure:

  • Dimensions: time, plus spatial axes such as x_box and y_box

  • Optional vertical dimension depending on the group (level or heightAboveGround)

  • Coordinates commonly include: latitude, longitude, and box metrics ( x_box_km, y_box_km) when available

  • Data variables depend on the YAML request (see Configuration file (YAML))

Derived wind variables

If the zonal (u) and meridional (v) wind components are included in the requested variables, FrameIt automatically computes and appends wind_speed to the target group (heightAboveGround for AROME, level for MNH):

\[\mathrm{wind\_speed} = \sqrt{u^2 + v^2}\]

If u or v are absent from the group, the computation is silently skipped.

If you export cartesian crops, you obtain one file per vertical group, which keeps the outputs modular and avoids mixing incompatible vertical coordinates in a single file.

SIMU.polar.<group>.nc

These files contain the polar-projected products. They are typically created after the cartesian extraction, using the polar projection module.

Typical structure:

  • Dimensions: time, radial coordinate (r), angular coordinate (theta), plus optional vertical dimension depending on the group

  • Coordinates may include: - Polar grid axes: r and theta (and optionally a degree representation such as theta_deg) - Derived cartesian coordinates on the polar grid: x_km and y_km - Geolocation: latitude(time, r, theta), longitude(time, r, theta)

  • Data variables depend on the requested fields (see Configuration file (YAML)).

The polar files also include a set of attributes that document the angular convention (for example the zero-angle location and rotation direction) as produced by the polar projection module.

Metadata and attributes

FrameIt adds a minimal set of global attributes to each file:

  • Conventions (currently CF-1.8)

  • title, summary, institution, source

  • simulation_id (from conf.simulation_name)

  • FRAMEIT_version (from the installed FrameIt package)

Additional export-specific attributes:

  • product_type: one of track, cart, polar

  • group: the original dictionary key (for group files)

  • track_filename: the corresponding track file name (for group files)

A history attribute is appended at write time and includes a UTC timestamp and the exporting module.

Attribute sanitization

NetCDF backends do not accept complex Python objects as attributes. During export:

  • Python dictionaries, lists, or tuples found in ds.attrs are converted to JSON strings and stored under a *_json attribute name.

  • Boolean attributes are converted to integer flags (0 or 1), because the netCDF4 backend does not support boolean attributes.

Compression and performance

By default, the exporter applies DEFLATE compression to all data variables:

  • zlib=True, shuffle=True, complevel=<compress_level>

Notes:

  • Lower compression levels (for example 1) typically write faster but generate larger files.

  • Higher compression levels reduce size but increase CPU cost during export.

  • Export time is also controlled by dask materialization, because writing triggers computation of lazy arrays.

Coordinates are not compressed by default. You can enable coordinate compression using compress_coords=True.

You may want to tune compression, then launch frameit with --compress-level option:

frameit run path/to/config.yml --compress-level 2

Default value is compress-level=1

NetCDF exports

By default, the CLI runs NetCDF exports at the end of the pipeline:

  • NetCDF export: enabled by default

  • Polar export: enabled by default

  • Cartesian export: enabled by default

To disable some exports:

# Disable all NetCDF exports
frameit run path/to/config.yml --no-export-netcdf

# Disable only polar exports
frameit run path/to/config.yml --no-export-polar

# Disable only cartesian exports
frameit run path/to/config.yml --no-export-cart