YAML Configuration Reference

Complete reference for all YAML configuration fields in CruisePlan.

Configuration Structure 

CruisePlan YAML files have three main sections:

# 1. Cruise-wide metadata and settings
cruise_name: "Example Cruise 2025"
description: "Oceanographic survey"
start_date: "2025-06-15"

# 2. Global catalog (reusable definitions)
points: [...]        # Point operations
lines: [...]         # Line operations
areas: [...]         # Area operations

# 3. Schedule organization
legs: [...]          # Execution phases

Coordinate Conventions 

Latitude: -90.0 to 90.0 decimal degrees (negative = South)
Longitude: -180.0 to 180.0 decimal degrees (negative = West)
Depth: meters below sea level (positive values)
Distance: kilometers
Duration: minutes

Units Reference 

All numeric fields use the units shown below. Units are fixed and not configurable.

Field	Unit	Notes
`latitude`, `longitude`	decimal degrees	WGS-84; negative = South / West
`water_depth`, `operation_depth`	metres	Positive below sea level (e.g., `3500` = 3500 m)
`distance_between_stations`	km	Along-track spacing when expanding CTD sections
`default_vessel_speed`	knots	Transit speed used for scheduling
`ctd_descent_rate`, `ctd_ascent_rate`	m/s	Used to compute CTD cast duration from depth
`duration`	minutes	Station occupation time
`turnaround_time`	minutes	Gap between consecutive operations
`delay_start`	minutes	Hold before an operation or leg begins
`delay_end`	minutes	Hold after an operation completes
`buffer_time`	minutes	Contingency reserve on a leg (stored but not applied to schedule)
`default_distance_between_stations`	km	Default station spacing for section expansion (cruise level)
`tolerance` (validate)	percent	Allowable depth difference between planned and bathymetric depth

Cruise Metadata 

Root-level cruise configuration fields:

cruise_name: "North Atlantic Survey 2025"
description: "Overflow monitoring survey"        # Optional free-text description
start_date: "2025-06-15"                         # ISO format YYYY-MM-DD
start_time: "08:00"                              # Cruise start time (default: "08:00")
day_start_hour: 8                                # Start of working day (0-23); default: 8
day_end_hour: 20                                 # End of working day (0-23); default: 20
default_vessel_speed: 10.0                       # Transit speed in knots; default: 10.0
default_distance_between_stations: 15.0          # Station spacing in km; default: 15.0
turnaround_time: 30                              # Time between operations in minutes; default: 30
ctd_descent_rate: 1.0                            # CTD descent speed in m/s; default: 1.0
ctd_ascent_rate: 1.0                             # CTD ascent speed in m/s; default: 1.0

Ports 

Ports are used as departure and arrival points for legs. They can be defined inline or as named entries in a global ports catalog and referenced by name:

# Named port catalog (referenced by name in legs)
ports:
  - name: "port_reykjavik"
    latitude: 64.15
    longitude: -21.95
    display_name: "Reykjavik"
  - name: "port_bergen"
    latitude: 60.39
    longitude: 5.32
    display_name: "Bergen"

# For single-leg cruises, departure/arrival may be set at cruise level
departure_port: port_reykjavik     # Named reference or inline PointDefinition
arrival_port: port_bergen          # Required for single-leg cruises; forbidden for multi-leg

For multi-leg cruises, departure_port and arrival_port are set on each leg (see Schedule Organization below).

Point Operations 

Individual station operations (CTD, moorings, sampling):

Required Fields 

points:
  - name: "STN_001"               # Unique identifier
    latitude: 60.0               # Decimal degrees
    longitude: -30.0             # Decimal degrees

Optional Fields 

points:
  - name: "STN_001"
    latitude: 60.0
    longitude: -30.0
    operation_type: CTD          # Operation category
    action: profile              # Specific action
    water_depth: 3500            # Water depth at seafloor in metres (auto-filled by 'process')
    operation_depth: 2000        # Target cast depth in metres (default: full water column)
    duration: 45                 # Override cast time in minutes (suppresses depth-based calculation)
    delay_start: 60              # Wait before starting in minutes (e.g., daylight constraint)
    delay_end: 30                # Wait after completing in minutes (e.g., equipment recovery)
    equipment: "SBE911plus"      # Equipment note (informational only, not used in scheduling)
    comment: "Deep water station"

Coordinate Formats 

Coordinates may be given in decimal degrees (preferred) or degrees decimal minutes:

# Decimal degrees (preferred)
points:
  - name: "STN_001"
    latitude: 60.2440
    longitude: -31.3177

# Degrees decimal minutes (DDM) — both formats accepted
points:
  - name: "STN_001"
    latitude_decmin: "60 14.640 N"
    longitude_decmin: "031 19.062 W"

Both formats produce identical internal representations. latitude and longitude_decmin cannot be mixed within the same definition.

Line Operations 

Transect and underway survey operations:

Required Fields 

lines:
  - name: "transect_A"
    route:                       # List of waypoints
      - latitude: 60.0
        longitude: -30.0
      - latitude: 60.0
        longitude: -20.0

Optional Fields 

lines:
  - name: "transect_A"
    operation_type: underway
    action: ADCP
    route:
      - latitude: 60.0
        longitude: -30.0
      - latitude: 60.0
        longitude: -20.0
    comment: "Cross-slope section"
    vessel_speed: 8.0               # Speed during transect in knots
    distance_between_stations: 10.0 # Station spacing for CTD section expansion (km)
    max_depth: 2000                 # Maximum cast depth for expanded stations (metres)

Area Operations 

Box surveys and mapping operations:

Required Fields 

areas:
  - name: "survey_box"
    corners:                     # Polygon corners (min 3)
      - latitude: 60.5
        longitude: -28.0
      - latitude: 61.5
        longitude: -28.0
      - latitude: 61.5
        longitude: -27.0
      - latitude: 60.5
        longitude: -27.0

Optional Fields 

areas:
  - name: "survey_box"
    operation_type: survey
    action: bathymetry
    corners:
      - latitude: 60.5
        longitude: -28.0
      - latitude: 61.5
        longitude: -28.0
      - latitude: 61.5
        longitude: -27.0
      - latitude: 60.5
        longitude: -27.0
    duration: 120               # Total survey time in minutes
    comment: "High-priority mapping area"

Schedule Organization 

Legs organize activities into cruise phases:

Basic Leg 

legs:
  - name: "leg1"
    departure_port: port_reykjavik   # Required
    arrival_port: port_bergen        # Required
    activities: ["STN_001", "STN_002", "transect_A"]

Advanced Leg Options 

legs:
  - name: "leg1"
    description: "Main science leg"
    departure_port: port_reykjavik     # Required: departure port name or inline definition
    arrival_port: port_bergen          # Required: arrival port name or inline definition
    first_activity: STN_001            # Routing hint: first activity (not executed separately)
    last_activity: transect_A          # Routing hint: last activity (not executed separately)
    activities: ["STN_001", "STN_002", "transect_A"]

    # Timing
    delay_start: 120             # Hold at departure port in minutes (e.g., port clearance)
    buffer_time: 60              # Contingency reserve for weather delays (minutes; stored, not applied)

    # Ordering
    ordered: true                # Whether activities must run in listed order

    # Leg-level parameter overrides (cascade from cruise defaults)
    vessel_speed: 12.0
    turnaround_time: 20
    distance_between_stations: 25.0

Clusters 

Group activities within legs for advanced scheduling:

legs:
  - name: "leg1"
    clusters:
      - name: "northern_stations"
        activities: ["CTD_001", "CTD_002"]
        strategy: "sequential"           # Only implemented strategy
      - name: "southern_stations"
        activities: ["CTD_003", "CTD_004"]
        strategy: "sequential"

Operation Types 

Standard operation types with default durations:

Type	Default Duration	Description
`ctd`	45 min	CTD/rosette operations
`underway`	Transit time	Continuous measurements
`multibeam`	2 hours	Seafloor mapping
`mooring`	4 hours	Mooring operations
`net_tow` (planned)	90 min	Biological sampling — not yet implemented
`grab_sample` (planned)	30 min	Sediment/water sampling — not yet implemented
`adcp` (planned)	Transit time	Current profiling — not yet implemented
`xbt` (planned)	15 min	Expendable temperature probe — not yet implemented

Overriding Calculated Duration 

Setting duration: <value> (in minutes) on any point operation overrides the depth-based cast time calculation entirely. This is useful when a station requires a non-standard instrument configuration, a fixed time budget, or must match a pre-agreed slot in a joint cruise plan:

points:
  - name: "STN_001"
    latitude: 60.0
    longitude: -30.0
    operation_type: CTD
    action: profile
    duration: 120     # 2-hour cast regardless of water depth

When duration is set, the enrichment step will not overwrite it. Omitting duration (or setting it to 0) restores depth-based calculation.

All time fields in YAML are in minutes: duration, turnaround_time, delay_start, and buffer_time.

Repeat Stations 

The same activity name may appear more than once in an activities list. Each occurrence is scheduled as a separate, independent operation — the scheduler looks up the definition by name on every pass with no deduplication. Back-to-back repeats require no extra configuration:

legs:
  - name: "leg1"
    activities: ["STN_001", "STN_001"]   # two consecutive casts at the same location

For time-series stations where a gap between occupations is needed, define separate entries with the same coordinates and set delay_start on the later ones. delay_start is part of the point definition and is shared by every reference to that name, so a gap can only be expressed by giving each occupation a distinct name:

points:
  - name: "STN_001_t0"
    latitude: 60.0
    longitude: -20.0
    operation_type: CTD
    # no delay_start — departs immediately

  - name: "STN_001_t6"
    latitude: 60.0
    longitude: -20.0
    operation_type: CTD
    delay_start: 360    # 6-hour hold before this occupation (minutes)

legs:
  - name: "leg1"
    activities: ["STN_001_t0", "STN_001_t6"]

Validation Rules 

CruisePlan validates configurations with these rules:

Unique names: All point, line, and area definitions must have unique names within their catalog. The same name may appear multiple times in an activities list (see Repeat Stations above).
Valid coordinates: Lat/lon within valid ranges
Date format: ISO format YYYY-MM-DD
Positive durations: Times must be > 0
Referenced activities: All leg activities must exist in catalog

Parameter Inheritance 

Parameters cascade from cruise → leg → cluster → operation:

# Cruise level (applied to all legs)
default_vessel_speed: 10.0

legs:
  - name: "leg1"
    vessel_speed: 12.0      # Overrides cruise default
    activities:
      - "CTD_001"           # Uses leg speed: 12.0 kt

points:
  - name: "CTD_001"
    vessel_speed: 8.0       # Overrides leg speed for this operation

Comments and Documentation 

Add comments to document your configuration:

points:
  - name: "CTD_001"
    latitude: 60.0
    longitude: -30.0
    comment: "Deep water station for overflow monitoring"

legs:
  - name: "leg1"
    comment: "Main science operations in Denmark Strait"
    activities: ["CTD_001"]

File Processing 

CruisePlan processes files in this sequence:

Parse YAML: Load and validate syntax
Validate structure: Check required fields and references
Enrich data: Add depths, distances, durations
Generate outputs: Create timeline and deliverables

For examples and workflows, see Workflows.