CLI reference

The seagliderOG1 command converts Seaglider basestation files to OG1 with one subcommand per verb. The typical workflow is draft (optional) → init → validate → process → report; enrich adds metadata to a written file; inspect and list are read-only helpers.

$ seagliderOG1 draft --raw-dir /data/005/20080606 -o drafts/
$ seagliderOG1 init sg005.yaml --raw-dir /data/005/20080606
$ seagliderOG1 validate sg005.yaml
$ seagliderOG1 process  sg005.yaml
$ seagliderOG1 report   out/sg005_20080606T180256_delayed.nc

The same entry point is available as a module:

$ python -m seagliderOG1.cli --help

See mission.yaml reference for the configuration file the verbs read and write.

Data mode

process --mode (and the mode key in mission.yaml) sets the OG1 data mode, which determines the data-mode suffix of the output id: realtime gives the suffix R and delayed gives delayed (vocabularies.MODE_SUFFIX). With neither set the mode is realtime: a file is delayed mode only when you say so.

Conversion page

seagliderOG1 report FILE.nc writes the HTML conversion page <id>_conversion.html for a written OG1 file: beside the file by default, directly into -o DIR, or into ROOT/<id>/ with --report-dir ROOT — so the pages can live apart from the archived data. process --report (or report: true in mission.yaml) writes the same page as it converts, and process --report-dir ROOT puts it under ROOT. An existing page is refused unless --force. inspect prints text only. See The conversion page for the sections the page shows.

process also writes <id>_conversion.json beside each OG1 file: the input files (name, size, dive number, dimension lengths and global-attribute count) and which dives each basestation variable was present in and had values in. The page reads it for its Presence across dives and Before → after sections. When the input dives disagree, process prints one line per mission after wrote:

wrote outputs/sg271_20260302T193828_R.nc
  sg271_20260302T193828_R: 542 variables over 3 dives; 500 on every dive, 42 on some (5 patterns) — see seagliderOG1 report outputs/sg271_20260302T193828_R.nc

The conversion record belongs to its OG1 file: it is replaced whenever the file is written. It records the file’s tracking_id (a new UUID on every write) and the SHA-256 of its bytes; report warns when the file beside it has changed since.

Draft

seagliderOG1 draft --raw-dir DIR [-o OUT] [--dives FIRST LAST] converts one mission with no mission.yaml, to see what the basestation files hold before writing one. It writes <id>_draft.nc, <id>_draft_conversion.html, <id>_draft_conversion.json and <id>_draft_mission.yaml (the init template with raw_dir, dives and the platform fields filled, and the derived id in a comment). None of these is an OG1 file: every name ends _draft, the netCDF carries a draft global attribute, and its Conventions has no OG-1.0. If any of the four files exists, draft writes nothing unless given --force (the proposal may have been edited in place). The draft page shows the basestation files’ own global attributes, marking those that differ between files, and what mission.yaml must still supply.

Adding metadata later

seagliderOG1 enrich FILE.nc [mission.yaml] [--doi DOI] sets global attributes on a written OG1 file without converting again — a DOI assigned after publication, or a corrected global-attribute section or global_attributes: value. It changes the netCDF file, not the configuration: the globals are edited in place, date_modified is set, a history line names the keys, tracking_id is renewed, date_created is kept, and the conversion record is rebound. Values must be text, numbers or dates (a date is written as ISO 8601 text); every value is checked before the file is opened, so a refused one leaves the file unchanged. Replacing a different value already in the file warns with both values. id cannot change: the file name and conversion record are bound to it, so a new id means converting again. The globals enrich writes itself (date_modified, history, tracking_id, draft) and the conversion_* records cannot be set. Reserving the DOI first and setting rights_and_access.doi before process is the alternative.

Listing the vocabulary

seagliderOG1 list prints what an OG1 file expects, read from the tables the converter uses:

$ seagliderOG1 list                          # the registry names
$ seagliderOG1 list globals                  # every OG1 global: tier, source, where it is set
$ seagliderOG1 list platform                 # the platform: keys and where each is written
$ seagliderOG1 list variables --search temp  # OG1 variables, filtered on any column
$ seagliderOG1 list variables TEMP           # one variable's attributes in full
$ seagliderOG1 list sensors                  # the sensor catalogue (NERC L22)

Verbs

Convert Seaglider basestation files to OG1 format.

usage: seagliderOG1 [-h] [--version] [-v] <command> ...

Positional Arguments

<command>: Possible choices: draft, init, validate, process, report, enrich, inspect, list

Named Arguments

--version

show program’s version number and exit

-v, --verbose

library diagnostics to stderr: -v for progress (INFO), -vv for debug

Default: 0

Sub-commands

draft

Convert one mission with no mission config and write a draft netCDF, its conversion page and a proposed mission.yaml. Nothing written is an OG1 file: every name ends _draft.

seagliderOG1 draft [-h] --raw-dir DIR [-o DIR] [--dives FIRST LAST] [--force]

Named Arguments

--raw-dir

one mission directory of basestation files (pSSSDDDD*.nc)

-o, --output-dir

where the draft files go (default: .)

Default: '.'

--dives

dive range to convert (default: every file)

--force

overwrite existing draft files

Default: False

example:: seagliderOG1 draft –raw-dir /data/005/20080606 -o drafts/ then: seagliderOG1 init sg005.yaml –raw-dir /data/005/20080606, or edit drafts/<id>_draft_mission.yaml, validate it and process it.

init

Write a commented mission.yaml. dest is a directory (mission.yaml is written inside) or a .yaml file name; default the current directory.

seagliderOG1 init [-h] [--raw-dir PATH] [--example] [--force] [dest]

Positional Arguments

dest

directory (mission.yaml inside) or a .yaml file name (default: .)

Default: '.'

Named Arguments

--raw-dir

basestation directory, or one pSSSDDDD*.nc file in it, to fill raw_dir and the platform block from

--example

write the bundled sg271 sample config (raw_dir set to the packaged dives); then seagliderOG1 process <dest> runs the demo. dest default: ./sg271.yaml

Default: False

--force

overwrite an existing file

Default: False

examples:: seagliderOG1 init ./mission.yaml seagliderOG1 init –example ./sg271.yaml (the bundled sample) seagliderOG1 init outputs/ –raw-dir /data/005/ outputs/mission.yaml seagliderOG1 init sg005.yaml –raw-dir /data/005/ that file

validate

check a mission.yaml for errors

seagliderOG1 validate [-h] [--strict] config

Positional Arguments

config: path to mission.yaml

Named Arguments

--strict

also require every dive in the range to be present (no gaps)

Default: False

process

convert basestation missions to OG1 files

seagliderOG1 process [-h] [--raw-dir DIR_OR_ROOT] [--all | --mission GLOB]
                     [-o DIR] [--mode {realtime,delayed}] [--dives FIRST LAST]
                     [--repair] [--force | --skip-existing] [--report]
                     [--report-dir ROOT] [-n]
                     config

Positional Arguments

config: path to mission.yaml

Named Arguments

--raw-dir

override the config raw_dir (a mission dir or a root of SN/DATE dirs)

--all

convert every SN/DATE mission under a root

Default: False

--mission

select missions by SN/DATE glob, e.g. 103/*

-o, --output-dir

override the config output_dir

--mode

Possible choices: realtime, delayed

override the config data mode

--dives

dive range to convert (overrides the config dives)

--repair

repair basestation time metadata before loading (writes the raw_dir tree)

Default: False

--force

overwrite an existing output file

Default: False

--skip-existing

skip a mission whose output file already exists

Default: False

--report

also write the HTML conversion page <id>_conversion.html beside each file

Default: False

--report-dir

write each conversion page into ROOT/<id>/ instead (implies –report)

-n, --dry-run

print what would be written; write nothing

Default: False

report

Write <id>_conversion.html for an OG1 file written by seagliderOG1: beside the file, in -o DIR, or in –report-dir ROOT/<id>/.

seagliderOG1 report [-h] [-o DIR | --report-dir ROOT] [--title TEXT] [--force]
                    files [files ...]

Positional Arguments

files: OG1 netCDF file(s)

Named Arguments

-o, --output-dir

write the page(s) directly into DIR

--report-dir

write each page into ROOT/<id>/

--title

title for the page

--force

overwrite an existing page

Default: False

examples:: seagliderOG1 report out/<id>.nc beside the file seagliderOG1 report out/<id>.nc -o pages/ into pages/ seagliderOG1 report out/<id>.nc –report-dir site/ into site/<id>/

enrich

Set global attributes on a written OG1 file, without converting again. Changes the netCDF file (not the config): sets date_modified, adds a history line and a new tracking_id, keeps date_created, and rebinds the conversion record beside it.

seagliderOG1 enrich [-h] [--doi DOI] file [config]

Positional Arguments

file: the OG1 netCDF file
config: mission.yaml whose global-attribute sections and global_attributes: are applied

Named Arguments

--doi: set the doi global

examples:: seagliderOG1 enrich out/<id>.nc –doi 10.5281/zenodo.123 seagliderOG1 enrich out/<id>.nc mission.yaml

inspect

Show the inventory of one basestation or OG1 netCDF file as a text table. With –conversion, print the conversion record; with –conversion -o, write the HTML conversion page.

seagliderOG1 inspect [-h]
                     [--attrs | --variables | --by-dimension DIM | --conversion | --parameter NAME]
                     [--all]
                     file

Positional Arguments

file: path to a basestation or OG1 netCDF file

Named Arguments

--attrs

show global attributes

Default: False

--variables

show variables (the default)

Default: False

--by-dimension

show only variables on dimension DIM

--conversion

show what the conversion recorded (dimensions, variables, dropped, sources)

Default: False

--parameter

decode one per-dive JSON scalar to a dive/value table

--all

with –conversion, list the constant scalars in full (not just a count)

Default: False

Examples:: seagliderOG1 inspect sg005_20080606_delayed.nc variables as a table seagliderOG1 inspect sg005_20080606_delayed.nc –attrs global attributes seagliderOG1 inspect p0050001.nc –by-dimension sg_data_point seagliderOG1 inspect sg005_20080606_delayed.nc –conversion what the conversion did

list

Print a seagliderOG1 registry as a table.

seagliderOG1 list [-h] [--search TEXT]
                  [{roles,institutions,missions,globals,platform,variables,sensors}]
                  [PATH|NAME]

Positional Arguments

registry

Possible choices: roles, institutions, missions, globals, platform, variables, sensors

which registry to print; omit to see the registry names

PATH|NAME

root or mission directory for ‘missions’; a variable name for ‘variables’

Named Arguments

--search: case-insensitive filter across every column

Examples:: seagliderOG1 list # the registries seagliderOG1 list globals # every OG1 global with its tier seagliderOG1 list platform # the platform: keys in mission.yaml seagliderOG1 list variables –search temp # filter by any column seagliderOG1 list variables TEMP # one variable’s attributes in full seagliderOG1 list missions /data/005 # missions under a root

typical workflow:: seagliderOG1 draft –raw-dir /data/005/20080606 look at the data, no config seagliderOG1 init sg005.yaml –raw-dir /data/005/20080606 template from the first file seagliderOG1 validate sg005.yaml config, raw_dir, dive range seagliderOG1 process sg005.yaml -> <output_dir>/<OG1 id>.nc seagliderOG1 report <output_dir>/<OG1 id>.nc the conversion page

Exit status

0 — success.
1 — a handled error (a missing file, an invalid configuration, a conversion that wrote nothing).
2 — a usage error (argparse: an unknown flag or a missing argument).