Registries

A cruise config names three things by slug or code — institutions, a platform, and contributor roles. The valid values ship inside the installed package, so rather than open a YAML file in site-packages to find one, list them:

ctdcast list                              # the three registries
ctdcast list institutions                 # what ships + your user directory
ctdcast list institutions config.yaml     # ... plus what this config adds
ctdcast list platforms --search meteor    # filter by slug or name
ctdcast list roles --vocabulary W08        # one role vocabulary

The full command reference is in CLI reference. What each registry is, and how to add to it without editing package data, follows.

Institutions

Research organisations, referenced by cruise_info.institutions (see Cruise metadata (cruise_info)). They resolve from four sources, later winning slug by slug — the Source column in ctdcast list institutions tells you which supplied each entry:

  1. packaged — the shipped ctdcast/config/institutions.yaml;

  2. user — ~/.config/ctdcast/institutions.yaml (or $CTDCAST_CONFIG_DIR), for organisations you use across cruises;

  3. a config file named by cruise_info.institutions_file, kept beside the cruise config;

  4. inline — an entry in cruise_info.institutions written with its own name and id, which needs no registry at all.

Tiers 3 and 4 are only visible when you pass the config, so ctdcast list institutions with no config prints a footer saying so.

Platforms

Vessels, referenced by cruise_info.platform (or the older ship_slug). The platform drives the EXPOCODE via its ICES code, so a wrong slug is refused rather than guessed. Two sources:

  1. packaged — the shipped ctdcast/config/platforms.yaml;

  2. inline — cruise_info.platform written as a mapping, for a vessel not in the shared registry:

    cruise_info:
  platform:
    name: "RRS Discovery"
    ices_code: "74E3"        # drives the EXPOCODE
    platform: "..."          # optional L06 category

    This works end to end — no need to edit platforms.yaml.

ctdcast list platforms also prints two sets of traps that platforms.yaml records and the resolver refuses: ambiguous_slugs (a name shared by several hulls — meteor alone is refused; use meteor3) and forbidden_codes (ICES codes that must not be used, each with the reason). They are shown so you can see why a slug is refused, not only that it was.

Roles

Contributor role codes, referenced by cruise_info.role_vocabulary (people) and cruise_info.institution_role_vocabulary (institutions). There are four vocabularies on two axes:

  • Person roles — C89 (BODC dataset roles, the default) and G04;

  • Institution roles — C59 (the default) and W08.

ctdcast list roles groups them by axis and marks each axis’s default, so a person role is never mistaken for one usable where an institution role is required. --vocabulary shows a single one.