API Functions 

Raises:

ValidationError – If configuration validation fails
FileError – If file operations fail (reading, writing, permissions)
BathymetryError – If bathymetry operations fail

Examples

>>> import cruiseplan
>>> result = cruiseplan.enrich(config_file="cruise.yaml", add_depths=True)
>>> print(f"Enriched file: {result.output_file}")
>>> print(f"Summary: {result.summary}")

cruiseplan.api.enrich_with_config(config_file: str | Path, config: EnrichConfig = None) → EnrichResult[source]

Enrich cruise configuration using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy enrich() function with individual parameters is still available.

Parameters:

config_file (str or Path) – Input YAML configuration file
config (EnrichConfig, optional) – Configuration object containing all enrichment options. If None, default configuration is used.

Returns:

Result object containing enriched config and summary

Return type:

Examples

Basic usage with defaults:

>>> result = enrich_with_config("cruise.yaml")

Custom configuration:

>>> from cruiseplan.api.config import EnrichConfig, BathymetryConfig
>>> config = EnrichConfig(
...     add_depths=True,
...     coord_format="dd",
...     bathymetry=BathymetryConfig(source="gebco2025")
... )
>>> result = enrich_with_config("cruise.yaml", config)

cruiseplan.api.map(config_file: str | Path, output_dir: str = 'data', output: str | None = None, format: str = 'all', bathy_source: str = 'gebco2025', bathy_dir: str = 'data/bathymetry', bathy_stride: int = 5, bathy_contours: list | None = None, lat_bounds: list | None = None, lon_bounds: list | None = None, figsize: list | None = None, show_plot: bool = False, no_ports: bool = False, no_title: bool = False, no_labels: bool = False, no_legend: bool = False, verbose: bool = False, max_depth: int | None = None) → MapResult[source]

Generate cruise track map (mirrors: cruiseplan map).

Parameters:

config_file (str or Path) – Input YAML configuration file
output_dir (str) – Output directory for map files (default: “data”)
output (str, optional) – Base filename for output maps (default: use config filename)
format (str) – Map output format: “png”, “kml”, or “all” (default: “all”)
bathy_source (str) – Bathymetry dataset (default: “gebco2025”)
bathy_dir (str) – Directory containing bathymetry data (default: “data/bathymetry”)
bathy_stride (int) – Bathymetry contour stride for map background (default: 5)
figsize (list) – Figure size for PNG maps [width, height] (default: [12, 8])
show_plot (bool) – Display plot interactively (default: False)
no_ports (bool) – Suppress plotting of departure and arrival ports (default: False)
no_title (bool) – Omit the map title from PNG output (default: False)
no_labels (bool) – Omit station name annotations from PNG output (default: False)
no_legend (bool) – Omit the legend from PNG output (default: False)
verbose (bool) – Enable verbose logging (default: False)

Returns:

Structured result containing generated map files and summary information.

Return type:

Examples

>>> import cruiseplan
>>> # Generate PNG map
>>> cruiseplan.map(config_file="cruise.yaml")
>>> # Generate KML map with custom size
>>> cruiseplan.map(config_file="cruise.yaml", format="kml", figsize=[16, 10])

cruiseplan.api.map_with_config(config_file: str | Path, config: MapConfig = None) → MapResult[source]

Generate cruise track map using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy map() function with individual parameters is still available.

Parameters:

config_file (str or Path) – Input YAML configuration file
config (MapConfig, optional) – Configuration object containing all map generation options. If None, default configuration is used.

Returns:

Result object containing list of generated map files

Return type:

Examples

Basic usage with defaults:

>>> result = map_with_config("cruise.yaml")

Custom configuration:

>>> from cruiseplan.api.config import MapConfig, BathymetryConfig
>>> config = MapConfig(
...     bathymetry=BathymetryConfig(source="gebco2025", stride=5),
...     visualization=VisualizationConfig(show_plot=True)
... )
>>> result = map_with_config("cruise.yaml", config)

cruiseplan.api.pangaea(query_terms: str, output_dir: str = 'data', output: str | None = None, lat_bounds: list[float] | None = None, lon_bounds: list[float] | None = None, limit: int = 10, rate_limit: float = 1.0, merge_campaigns: bool = True, verbose: bool = False) → PangaeaResult[source]

Search and download PANGAEA oceanographic data (mirrors: cruiseplan pangaea).

Parameters:

query_terms (str) – Search terms for PANGAEA database
output_dir (str) – Output directory for station files (default: “data”)
output (str, optional) – Base filename for outputs (default: derived from query)
lat_bounds (List[float], optional) – Latitude bounds [min_lat, max_lat]
lon_bounds (List[float], optional) – Longitude bounds [min_lon, max_lon]
limit (int) – Maximum number of results to process (default: 10)
rate_limit (float) – API request rate limit in requests per second (default: 1.0)
merge_campaigns (bool) – Merge campaigns with the same name (default: True)
verbose (bool) – Enable verbose logging (default: False)

Returns:

Structured result containing stations data, generated files, and summary information. Stations data contains the loaded PANGAEA campaign data for analysis. Files list contains paths to all generated files (DOI list, stations pickle). Summary contains metadata about the search and processing.

Return type:

PangaeaResult

Examples

>>> import cruiseplan
>>> # Search for CTD data in Arctic
>>> result = cruiseplan.pangaea("CTD", lat_bounds=[70, 80], lon_bounds=[-10, 10])
>>> print(f"Found {len(result.stations_data)} campaigns in {len(result.files_created)} files")
>>> # Search with custom output directory and filename
>>> result = cruiseplan.pangaea("temperature", output_dir="pangaea_data", output="arctic_temp")
>>> # Access the data directly
>>> for campaign in result.stations_data:
...     print(f"Campaign: {campaign['Campaign']}, Stations: {len(campaign['Stations'])}")

cruiseplan.api.pangaea_with_config(query_terms: str, config: PangaeaConfig = None) → PangaeaResult[source]

Search PANGAEA oceanographic database using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy pangaea() function with individual parameters is still available.

Parameters:

query_terms (str) – Search terms for PANGAEA database query
config (PangaeaConfig, optional) – Configuration object containing all PANGAEA search options. If None, default configuration is used.

Returns:

Result object containing search results and metadata

Return type:

PangaeaResult

Examples

Basic usage with defaults:

>>> result = pangaea_with_config("temperature CTD")

Custom configuration:

>>> from cruiseplan.api.config import PangaeaConfig, OutputConfig
>>> config = PangaeaConfig(
...     lat_bounds=[-60, -40],
...     lon_bounds=[-180, 180],
...     limit=20,
...     output=OutputConfig(directory="results")
... )
>>> result = pangaea_with_config("temperature CTD", config)

cruiseplan.api.process(config_file: str | Path, output_dir: str = 'data', output: str | None = None, bathy_source: str = 'gebco2025', bathy_dir: str = 'data/bathymetry', add_depths: bool = True, add_coords: bool = True, expand_sections: bool = True, run_validation: bool = True, run_map_generation: bool = True, depth_check: bool = True, tolerance: float = 10.0, format: str = 'all', bathy_stride: int = 10, bathy_contours: list | None = None, lat_bounds: list | None = None, lon_bounds: list | None = None, figsize: list | None = None, no_ports: bool = False, no_title: bool = False, no_labels: bool = False, no_legend: bool = False, verbose: bool = False, max_depth: int | None = None) → ProcessResult[source]

Process cruise configuration with unified workflow (mirrors: cruiseplan process).

This function runs the complete processing workflow: enrichment -> validation -> map generation.

Parameters:

config_file (str or Path) – Input YAML configuration file
output_dir (str) – Output directory for generated files (default: “data”)
output (str, optional) – Base filename for outputs (default: use cruise name from config)
bathy_source (str) – Bathymetry dataset (default: “gebco2025”)
bathy_dir (str) – Directory containing bathymetry data (default: “data/bathymetry”)
add_depths (bool) – Add missing depth values to stations using bathymetry data (default: True)
add_coords (bool) – Add formatted coordinate fields (default: True)
expand_sections (bool) – Expand CTD sections into individual station definitions (default: True)
run_validation (bool) – Run validation after enrichment (default: True)
run_map_generation (bool) – Generate maps after validation (default: True)
depth_check (bool) – Compare existing depths with bathymetry data during validation (default: True)
tolerance (float) – Depth difference tolerance in percent for validation (default: 10.0)
format (str) – Map output format(s): “png”, “kml”, “all” (default: “all”)
bathy_stride (int) – Bathymetry contour stride for maps (default: 10)
figsize (list, optional) – Figure size for maps [width, height] (default: auto)
no_ports (bool) – Suppress plotting of departure and arrival ports on maps (default: False)
no_title (bool) – Omit the map title from PNG output (default: False)
no_labels (bool) – Omit station name annotations from PNG output (default: False)
no_legend (bool) – Omit the legend from PNG output (default: False)
verbose (bool) – Enable verbose logging (default: False)

Returns:

Structured result with all files created, validation results, and summary

Return type:

Examples

>>> import cruiseplan
>>> # Process with all defaults
>>> result = cruiseplan.process("cruise.yaml")
>>> print(f"Files created: {len(result.files_created)}")
>>> # Custom processing workflow
>>> result = cruiseplan.process("cruise.yaml", run_map_generation=False, depth_check=False)

cruiseplan.api.process_with_config(config_file: str | Path, config: ProcessConfig = None) → ProcessResult[source]

Process cruise configuration with unified workflow using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy process() function with individual parameters is still available.

Parameters:

config_file (str or Path) – Input YAML configuration file
config (ProcessConfig, optional) – Configuration object containing all processing options. If None, default configuration is used.

Returns:

Result object containing enriched config and list of output files

Return type:

Examples

Basic usage with defaults:

>>> result = process_with_config("cruise.yaml")

Custom configuration:

>>> from cruiseplan.api.config import ProcessConfig, BathymetryConfig
>>> config = ProcessConfig(
...     add_depths=True,
...     bathymetry=BathymetryConfig(source="gebco2025", stride=5)
... )
>>> result = process_with_config("cruise.yaml", config)

cruiseplan.api.schedule(config_file: str | Path, output_dir: str = 'data', output: str | None = None, format: str | None = 'all', leg: str | None = None, derive_netcdf: bool = False, bathy_source: str = 'gebco2025', bathy_dir: str = 'data/bathymetry', bathy_stride: int = 10, bathy_contours: list | None = None, lat_bounds: list | None = None, lon_bounds: list | None = None, figsize: list | None = None, no_ports: bool = False, no_title: bool = False, no_labels: bool = False, no_legend: bool = False, verbose: bool = False, max_depth: int | None = None) → ScheduleResult[source]

Generate cruise schedule (mirrors: cruiseplan schedule).

Parameters:

config_file (str or Path) – Input YAML configuration file
output_dir (str) – Output directory for schedule files (default: “data”)
output (str, optional) – Base filename for outputs (default: use cruise name from config)
format (str or None) – Output formats: “html”, “latex”, “csv”, “kml”, “netcdf”, “png”, “all”, or None (default: “all”). If None, only computes timeline without generating files.
leg (str, optional) – Process specific leg only (default: process all legs)
derive_netcdf (bool) – Generate specialized NetCDF files (_points.nc, _lines.nc, _areas.nc) (default: False)
bathy_source (str) – Bathymetry dataset (default: “etopo2022”)
bathy_dir (str) – Directory containing bathymetry data (default: “data”)
bathy_stride (int) – Bathymetry contour stride for PNG maps (default: 10)
figsize (list) – Figure size for PNG maps [width, height] (default: [12, 8])
no_ports (bool) – Exclude ports from PNG schedule maps (default: False)
no_title (bool) – Omit the map title from PNG output (default: False)
no_labels (bool) – Omit station name annotations from PNG output (default: False)
no_legend (bool) – Omit the legend from PNG output (default: False)
max_depth (int, optional) – Maximum water depth (m) for the bathymetry colour scale on PNG maps. When provided, clips the deep end so shallow-water structure uses the full colour range. Example: max_depth=1000 spans -1000 to +200 m. Default is None (full -8000 to +200 m range).
verbose (bool) – Enable verbose logging (default: False)

Returns:

Structured result containing timeline, generated files, and summary information. Timeline contains computed schedule data for programmatic use. Files list contains paths to all generated files (HTML, CSV, NetCDF, etc.). Summary contains metadata about the generation process.

Return type:

Examples

>>> import cruiseplan
>>> # Generate all formats and get timeline for analysis
>>> result = cruiseplan.schedule(config_file="cruise.yaml", format="all")
>>> print(f"Generated files: {result.files_created}")
>>> print(f"Timeline has {len(result.timeline)} activities")
>>>
>>> # Find specific file type from generated files
>>> netcdf_file = next(f for f in result.files_created if f.suffix == '.nc')
>>> html_file = next(f for f in result.files_created if f.suffix == '.html')
>>>
>>> # Get only timeline data without generating files
>>> result = cruiseplan.schedule(config_file="cruise.yaml", format=None)
>>> for activity in result.timeline:
...     print(f"{activity['label']}: {activity['start_time']} -> {activity['end_time']}")
>>>
>>> # Load NetCDF file with xarray
>>> result = cruiseplan.schedule(config_file="cruise.yaml", format="netcdf")
>>> netcdf_file = result.files_created[0]  # NetCDF file
>>> import xarray as xr
>>> ds = xr.open_dataset(netcdf_file)

cruiseplan.api.schedule_with_config(config_file: str | Path, config: ScheduleConfig = None) → ScheduleResult[source]

Generate cruise schedule using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy schedule() function with individual parameters is still available.

Parameters:

config_file (str or Path) – Input YAML configuration file
config (ScheduleConfig, optional) – Configuration object containing all scheduling options. If None, default configuration is used.

Returns:

Result object containing list of generated schedule files

Return type:

Examples

Basic usage with defaults:

>>> result = schedule_with_config("cruise.yaml")

Custom configuration:

>>> from cruiseplan.api.config import ScheduleConfig, BathymetryConfig
>>> config = ScheduleConfig(
...     leg="leg1",
...     derive_netcdf=True,
...     bathymetry=BathymetryConfig(source="gebco2025", stride=5)
... )
>>> result = schedule_with_config("cruise.yaml", config)

cruiseplan.api.stationplan_forecast(schedule_file: str | Path, start_index: int, start_time: str, duration_hours: float = 24.0, transit_speed: float = 10.0) → StationplanResult[source]

Generate station plan forecast starting from specified activity.

This function reads a NetCDF schedule file, generates a time-shifted forecast starting from the specified activity index with a new start time, and formats the output as letsgo.m compatible text.

Parameters:

schedule_file (str or Path) – Path to NetCDF schedule file (e.g., ‘MSM142_leg_2_schedule.nc’)
start_index (int) – Index of first activity in forecast (0-based)
start_time (str) – New absolute start time for the selected activity (ISO format: “2026-08-30T14:00:00”)
duration_hours (float, optional) – Forecast duration in hours (default: 24.0)
transit_speed (float, optional) – Ship transit speed in knots for header metadata (default: 10.0)

Returns:

Result object containing: - success: True if successful, False if error - message: Status message - output: Formatted letsgo.m forecast text (if successful)

Return type:

Examples

>>> result = stationplan_forecast("data/cruise_schedule.nc", 18, "2026-08-30T14:00:00", 36.0)
>>> if result.success:
...     print(result.output)
... else:
...     print(f"Error: {result.message}")

cruiseplan.api.stationplan_forecast_kml(schedule_file: str | Path, start_index: int, start_time: str, duration_hours: float, output_path: str | Path | None = None) → StationplanResult[source]

Generate KML forecast from a cruise schedule for a specific time window.

Creates a Google Earth compatible KML file showing scientific operations within the specified forecast period.

Parameters:

schedule_file (Union[str, Path]) – Path to the NetCDF schedule file
start_index (int) – Activity index to start forecast from
start_time (str) – Forecast start time in ISO format (e.g., ‘2026-05-05 08:00’)
duration_hours (float) – Forecast duration in hours
output_path (Union[str, Path, None], optional) – Path to output KML file, by default None

Returns:

Result object with success status, message, and output path

Return type:

cruiseplan.api.stationplan_forecast_png(schedule_file: str | Path, start_index: int, start_time: str, duration_hours: float, output_path: str | Path | None = None, bathy_source: str = 'gebco2025', bathy_dir: str = 'data/bathymetry', bathy_stride: int = 10, figsize: tuple[float, float] = (12.0, 8.0), lat_bounds: list[float] = None, lon_bounds: list[float] = None) → StationplanResult[source]

Generate PNG map forecast from a cruise schedule for a specific time window.

Creates a static PNG map showing scientific operations within the specified forecast period, using the same map generation system as ‘cruiseplan schedule –format png’ but filtered to show only work from the start-index for the specified duration.

Parameters:

schedule_file (Union[str, Path]) – Path to the NetCDF schedule file
start_index (int) – Activity index to start forecast from
start_time (str) – Forecast start time in ISO format (e.g., ‘2026-05-05 08:00’)
duration_hours (float) – Forecast duration in hours
output_path (Union[str, Path, None], optional) – Path to output PNG file, by default None
bathy_source (str, optional) – Bathymetry dataset to use, by default “etopo2022”
bathy_dir (str, optional) – Directory containing bathymetry data, by default “data”
bathy_stride (int, optional) – Bathymetry contour stride, by default 10
figsize (tuple[float, float], optional) – Figure size in inches, by default (12.0, 8.0)
lat_bounds (list[float], optional) – Latitude bounds [min, max], by default None
lon_bounds (list[float], optional) – Longitude bounds [min, max], by default None

Returns:

Result object with success status, message, and output path

Return type:

cruiseplan.api.stationplan_forecast_tex(schedule_file: str | Path, start_index: int, start_time: str, duration_hours: float = 24.0, output_path: str | Path = None, logo_path: str | Path = None, workplan_number: str = None, cruise_title: str = None) → StationplanResult[source]

Generate TeX station forecast starting from specified activity.

Combines forecast generation with TeX formatting - generates a time-shifted forecast and outputs it as a complete LaTeX document.

Parameters:

schedule_file (str or Path) – Path to NetCDF schedule file
start_index (int) – Index of first activity in forecast (0-based)
start_time (str) – New absolute start time (ISO format: “2026-08-30T14:00:00”)
duration_hours (float) – Forecast duration in hours (default: 24.0)
output_path (str or Path, optional) – Output path for .tex file
logo_path (str or Path, optional) – Path to logo image file (PNG, JPG, or PDF). If None, checks for default logos in images/ folder

Returns:

Result object with success status and generated file path

Return type:

cruiseplan.api.stationplan_list(schedule_file: str | Path) → StationplanResult[source]

List all activities in a cruise schedule with indices.

This function reads a NetCDF schedule file and returns a formatted table of all activities with their indices, time offsets, categories, durations, and names. This is used for the –list mode of the stationplan command.

Parameters:: schedule_file (str or Path) – Path to NetCDF schedule file (e.g., ‘MSM142_leg_2_schedule.nc’)
Returns:: Result object containing: - success: True if successful, False if error - message: Status message - output: Formatted activities table (if successful)
Return type:: StationplanResult

Examples

>>> result = stationplan_list("data/cruise_schedule.nc")
>>> if result.success:
...     print(result.output)
... else:
...     print(f"Error: {result.message}")

cruiseplan.api.stationplan_tex(schedule_file: str | Path, output_path: str | Path = None, logo_path: str | Path = None, workplan_number: str = None, cruise_title: str = None) → StationplanResult[source]

Generate TeX station table in letsgo.m format from NetCDF schedule file.

This function reads a NetCDF schedule file and generates a TeX table in the letsgo.m format using rich NetCDF data with proper coordinates, depths, and distance calculations.

Parameters:

schedule_file (str or Path) – Path to NetCDF schedule file (e.g., ‘MSM142_leg_2_schedule.nc’)
output_path (str or Path, optional) – Output path for .tex file. If None, uses schedule_file name with .tex extension

Returns:

Result object containing: - success: True if successful, False if error - message: Status message - output: Path to generated .tex file (if successful)

Return type:

Examples

>>> result = stationplan_tex("data/cruise_schedule.nc", "station_plan.tex")
>>> if result.success:
...     print(f"TeX table generated: {result.output}")
... else:
...     print(f"Error: {result.message}")

cruiseplan.api.stationplan_waypoints(schedule_file: str | Path, start_index: int, start_time: str = None, duration_hours: float = 48.0, current_position: tuple[float, float] = None, output_path: str | Path = None) → StationplanResult[source]

Generate bridge waypoints file in Stationsplan.txt format.

Creates a simple waypoint list suitable for bridge navigation systems with DDM coordinate format and work type codes.

Parameters:

schedule_file (str or Path) – Path to NetCDF schedule file
start_index (int, optional) – Starting activity index for forecast mode (if None, uses full schedule)
start_time (str, optional) – New start time for forecast mode (ISO format)
duration_hours (float, optional) – Forecast duration in hours (if None, uses remaining schedule)
current_position (tuple[float, float], optional) – Current ship position as (lat, lon) in decimal degrees
output_path (str or Path, optional) – Output file path. If None, returns content as string

Returns:

Result object containing success status and waypoint content

Return type:

cruiseplan.api.stations(lat_bounds: tuple[float, float] | None = None, lon_bounds: tuple[float, float] | None = None, output_dir: str = 'data', output: str | None = None, config_file: str | None = None, pangaea_file: str | None = None, bathy_source: str = 'gebco2025', bathy_dir: str = 'data/bathymetry', bathy_contours: list | None = None, bathy_stride: int = 10, max_depth: int | None = None, overwrite: bool = False, verbose: bool = False) → StationPickerResult[source]

Launch interactive station picker for cruise planning.

This function moves all business logic from cli/stations.py with no changes to core functionality, just better error handling and structured returns.

Parameters:

lat_bounds (tuple, optional) – Latitude bounds as (min, max). If None, derived from config file, PANGAEA data, or defaults.
lon_bounds (tuple, optional) – Longitude bounds as (min, max). If None, derived from config file, PANGAEA data, or defaults.
output_dir (str) – Output directory for generated YAML file
output (str, optional) – Output filename (default: “stations.yaml” or based on input files)
config_file (str, optional) – Path to existing YAML cruise configuration file to load and edit
pangaea_file (str, optional) – Path to PANGAEA campaigns pickle file
bathy_source (str) – Bathymetry source (“etopo2022” or “gebco2025”)
bathy_dir (str) – Bathymetry data directory
bathy_stride (int) – Bathymetry downsampling factor (default: 10, lower = finer detail but slower)
max_depth (int, optional) – Maximum water depth (m) for the colour scale. If set, the colour range spans -max_depth to +200 m instead of the default -8000 to +200 m.
overwrite (bool) – Overwrite existing output file
verbose (bool) – Enable verbose logging

Returns:

Result with output file path and summary information

Return type:

StationPickerResult

Raises:

ImportError – If matplotlib is not available
ValueError – If coordinate bounds are invalid, config file cannot be loaded, or PANGAEA file cannot be loaded
FileNotFoundError – If config file, PANGAEA file, or bathymetry data not found

cruiseplan.api.stations_with_config(config: StationsConfig = None) → StationPickerResult[source]

Launch interactive station picker using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy stations() function with individual parameters is still available.

Parameters:: config (StationsConfig, optional) – Configuration object containing all station picker options. If None, default configuration is used.
Returns:: Result object containing output file and metadata
Return type:: StationPickerResult

Examples

Basic usage with defaults:

>>> result = stations_with_config()

Custom configuration:

>>> from cruiseplan.api.config import StationsConfig, OutputConfig
>>> config = StationsConfig(
...     lat_bounds=(-65, -45),
...     lon_bounds=(160, 180),
...     pangaea_file="pangaea_data.pkl",
...     output=OutputConfig(directory="cruise_stations")
... )
>>> result = stations_with_config(config)

cruiseplan.api.validate(config_file: str | Path, bathy_source: str = 'gebco2025', bathy_dir: str = 'data/bathymetry', check_depths: bool = True, tolerance: float = 10.0, warnings_only: bool = False, verbose: bool = False) → ValidationResult[source]

Validate a cruise configuration file (mirrors: cruiseplan validate).

Parameters:

config_file (str or Path) – Input YAML configuration file
bathy_source (str) – Bathymetry dataset (default: “gebco2025”)
bathy_dir (str) – Directory containing bathymetry data (default: “data”)
check_depths (bool) – Compare existing depths with bathymetry data (default: True)
tolerance (float) – Depth difference tolerance in percent (default: 10.0)
warnings_only (bool) – Show warnings without failing - warnings don’t affect return value (default: False)
verbose (bool) – Enable verbose logging (default: False)

Returns:

Structured validation result with success status, errors, warnings, and summary.

Return type:

Examples

>>> import cruiseplan
>>> # Validate cruise configuration with depth checking
>>> is_valid = cruiseplan.validate(config_file="cruise.yaml", check_depths=True)
>>> # Custom tolerance validation
>>> is_valid = cruiseplan.validate(config_file="cruise.yaml", tolerance=5.0)
>>> if is_valid:
...     print("✅ Configuration is valid")

cruiseplan.api.validate_with_config(config_file: str | Path, config: ValidateConfig = None) → ValidationResult[source]

Validate cruise configuration using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy validate() function with individual parameters is still available.

Parameters:

config_file (str or Path) – Input YAML configuration file
config (ValidateConfig, optional) – Configuration object containing all validation options. If None, default configuration is used.

Returns:

Result object containing validation status and issues

Return type:

Examples

Basic usage with defaults:

>>> result = validate_with_config("cruise.yaml")

Custom configuration:

>>> from cruiseplan.api.config import ValidateConfig, BathymetryConfig
>>> config = ValidateConfig(
...     check_depths=True,
...     tolerance=5.0,
...     bathymetry=BathymetryConfig(source="gebco2025")
... )
>>> result = validate_with_config("cruise.yaml", config)

cruiseplan.api.data module

Data acquisition API functions.

This module provides functions for downloading bathymetry data and searching PANGAEA oceanographic databases.

cruiseplan.api.data.bathymetry(bathy_source: str = 'gebco2025', output_dir: str | None = None, citation: bool = False) → BathymetryResult[source]

Download bathymetry data (mirrors: cruiseplan bathymetry).

Parameters:

bathy_source (str) – Bathymetry dataset to download (“etopo2022” or “gebco2025”)
output_dir (str, optional) – Output directory for bathymetry files (default: “data/bathymetry” relative to project root)
citation (bool) – Show citation information for the bathymetry source (default: False)

Returns:

Structured result containing data file path, source information, and summary.

Return type:

BathymetryResult

Examples

>>> import cruiseplan
>>> # Download ETOPO2022 data to project root data/bathymetry/
>>> cruiseplan.bathymetry()
>>> # Download GEBCO2025 data to custom location
>>> cruiseplan.bathymetry(bathy_source="gebco2025", output_dir="my_data/bathymetry")

cruiseplan.api.data.bathymetry_with_config(config: BathymetryDownloadConfig = None) → BathymetryResult[source]

Download bathymetry data using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy bathymetry() function with individual parameters is still available.

Parameters:: config (BathymetryDownloadConfig, optional) – Configuration object containing all bathymetry download options. If None, default configuration is used.
Returns:: Result object containing data file path, source information, and summary
Return type:: BathymetryResult

Examples

Basic usage with defaults:

>>> result = bathymetry_with_config()

Custom configuration:

>>> from cruiseplan.api.config import BathymetryDownloadConfig
>>> config = BathymetryDownloadConfig(
...     source="gebco2025",
...     output_dir="my_data/bathymetry",
...     citation=True
... )
>>> result = bathymetry_with_config(config)

cruiseplan.api.data.pangaea(query_terms: str, output_dir: str = 'data', output: str | None = None, lat_bounds: list[float] | None = None, lon_bounds: list[float] | None = None, limit: int = 10, rate_limit: float = 1.0, merge_campaigns: bool = True, verbose: bool = False) → PangaeaResult[source]

Search and download PANGAEA oceanographic data (mirrors: cruiseplan pangaea).

Parameters:

query_terms (str) – Search terms for PANGAEA database
output_dir (str) – Output directory for station files (default: “data”)
output (str, optional) – Base filename for outputs (default: derived from query)
lat_bounds (List[float], optional) – Latitude bounds [min_lat, max_lat]
lon_bounds (List[float], optional) – Longitude bounds [min_lon, max_lon]
limit (int) – Maximum number of results to process (default: 10)
rate_limit (float) – API request rate limit in requests per second (default: 1.0)
merge_campaigns (bool) – Merge campaigns with the same name (default: True)
verbose (bool) – Enable verbose logging (default: False)

Returns:

Structured result containing stations data, generated files, and summary information. Stations data contains the loaded PANGAEA campaign data for analysis. Files list contains paths to all generated files (DOI list, stations pickle). Summary contains metadata about the search and processing.

Return type:

PangaeaResult

Examples

>>> import cruiseplan
>>> # Search for CTD data in Arctic
>>> result = cruiseplan.pangaea("CTD", lat_bounds=[70, 80], lon_bounds=[-10, 10])
>>> print(f"Found {len(result.stations_data)} campaigns in {len(result.files_created)} files")
>>> # Search with custom output directory and filename
>>> result = cruiseplan.pangaea("temperature", output_dir="pangaea_data", output="arctic_temp")
>>> # Access the data directly
>>> for campaign in result.stations_data:
...     print(f"Campaign: {campaign['Campaign']}, Stations: {len(campaign['Stations'])}")

cruiseplan.api.data.pangaea_with_config(query_terms: str, config: PangaeaConfig = None) → PangaeaResult[source]

Search PANGAEA oceanographic database using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy pangaea() function with individual parameters is still available.

Parameters:

query_terms (str) – Search terms for PANGAEA database query
config (PangaeaConfig, optional) – Configuration object containing all PANGAEA search options. If None, default configuration is used.

Returns:

Result object containing search results and metadata

Return type:

PangaeaResult

Examples

Basic usage with defaults:

>>> result = pangaea_with_config("temperature CTD")

Custom configuration:

>>> from cruiseplan.api.config import PangaeaConfig, OutputConfig
>>> config = PangaeaConfig(
...     lat_bounds=[-60, -40],
...     lon_bounds=[-180, 180],
...     limit=20,
...     output=OutputConfig(directory="results")
... )
>>> result = pangaea_with_config("temperature CTD", config)

cruiseplan.api.init_utils module

Helper functions for __init__.py to reduce complexity in API functions.

cruiseplan.api.init_utils.generate_csv_format(cruise_config: Any, timeline: list[Any], output_dir_path: Path, base_name: str) → Path | None[source]: Generate CSV schedule output.

cruiseplan.api.init_utils.generate_html_format(cruise_config: Any, timeline: list[Any], output_dir_path: Path, base_name: str) → Path | None[source]: Generate HTML schedule output.

cruiseplan.api.init_utils.generate_latex_format(cruise_config: Any, timeline: list[Any], output_dir_path: Path, base_name: str) → Path | None[source]: Generate LaTeX schedule output.

cruiseplan.api.init_utils.generate_netcdf_format(cruise_config: Any, timeline: list[Any], output_dir_path: Path, base_name: str) → Path | None[source]: Generate NetCDF schedule output.

cruiseplan.api.init_utils.generate_png_format(cruise: Any, timeline: list[Any], output_dir_path: Path, base_name: str, bathy_source: str, bathy_dir: str, bathy_stride: int, figsize: tuple, bathy_contours: list | None = None, lat_bounds: list | None = None, lon_bounds: list | None = None, no_ports: bool = False, no_title: bool = False, no_labels: bool = False, no_legend: bool = False, suffix: str = 'map', max_depth: int | None = None) → Path | None[source]: Generate PNG map output.

cruiseplan.api.init_utils.generate_specialized_netcdf(cruise_config: Any, timeline: list[Any], output_dir_path: Path) → list[Path][source]: Generate specialized NetCDF files.

cruiseplan.api.map_cruise module

Cruise map generation API.

This module provides the main map() function that generates cruise track maps in various formats (PNG, KML).

cruiseplan.api.map_cruise.map(config_file: str | Path, output_dir: str = 'data', output: str | None = None, format: str = 'all', bathy_source: str = 'gebco2025', bathy_dir: str = 'data/bathymetry', bathy_stride: int = 5, bathy_contours: list | None = None, lat_bounds: list | None = None, lon_bounds: list | None = None, figsize: list | None = None, show_plot: bool = False, no_ports: bool = False, no_title: bool = False, no_labels: bool = False, no_legend: bool = False, verbose: bool = False, max_depth: int | None = None) → MapResult[source]

Generate cruise track map (mirrors: cruiseplan map).

Parameters:

config_file (str or Path) – Input YAML configuration file
output_dir (str) – Output directory for map files (default: “data”)
output (str, optional) – Base filename for output maps (default: use config filename)
format (str) – Map output format: “png”, “kml”, or “all” (default: “all”)
bathy_source (str) – Bathymetry dataset (default: “gebco2025”)
bathy_dir (str) – Directory containing bathymetry data (default: “data/bathymetry”)
bathy_stride (int) – Bathymetry contour stride for map background (default: 5)
figsize (list) – Figure size for PNG maps [width, height] (default: [12, 8])
show_plot (bool) – Display plot interactively (default: False)
no_ports (bool) – Suppress plotting of departure and arrival ports (default: False)
no_title (bool) – Omit the map title from PNG output (default: False)
no_labels (bool) – Omit station name annotations from PNG output (default: False)
no_legend (bool) – Omit the legend from PNG output (default: False)
verbose (bool) – Enable verbose logging (default: False)

Returns:

Structured result containing generated map files and summary information.

Return type:

Examples

>>> import cruiseplan
>>> # Generate PNG map
>>> cruiseplan.map(config_file="cruise.yaml")
>>> # Generate KML map with custom size
>>> cruiseplan.map(config_file="cruise.yaml", format="kml", figsize=[16, 10])

cruiseplan.api.map_cruise.map_with_config(config_file: str | Path, config: MapConfig = None) → MapResult[source]

Generate cruise track map using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy map() function with individual parameters is still available.

Parameters:

config_file (str or Path) – Input YAML configuration file
config (MapConfig, optional) – Configuration object containing all map generation options. If None, default configuration is used.

Returns:

Result object containing list of generated map files

Return type:

Examples

Basic usage with defaults:

>>> result = map_with_config("cruise.yaml")

Custom configuration:

>>> from cruiseplan.api.config import MapConfig, BathymetryConfig
>>> config = MapConfig(
...     bathymetry=BathymetryConfig(source="gebco2025", stride=5),
...     visualization=VisualizationConfig(show_plot=True)
... )
>>> result = map_with_config("cruise.yaml", config)

cruiseplan.api.process_cruise module

Cruise processing workflow API.

This module provides the complete processing workflow including enrich(), validate(), and process() functions that coordinate the full data processing pipeline.

cruiseplan.api.process_cruise.enrich(config_file: str | Path, output_dir: str = 'data', output: str | None = None, add_depths: bool = True, add_coords: bool = True, bathy_source: str = 'gebco2025', bathy_dir: str = 'data/bathymetry', coord_format: str = 'ddm', expand_sections: bool = True, verbose: bool = False) → EnrichResult[source]

Enrich a cruise configuration file (mirrors: cruiseplan enrich).

This function now handles all validation, file operations, and error handling that was previously in the CLI layer.

Parameters:

config_file (str or Path) – Input YAML configuration file
output_dir (str) – Output directory for enriched file (default: “data”)
output (str, optional) – Base filename for output (default: use input filename)
add_depths (bool) – Add missing depth values to stations using bathymetry data (default: True)
add_coords (bool) – Add formatted coordinate fields (default: True)
expand_sections (bool) – Expand CTD sections into individual station definitions (default: True)
bathy_source (str) – Bathymetry dataset (default: “gebco2025”)
bathy_dir (str) – Directory containing bathymetry data (default: “data”)
coord_format (str) – Coordinate format (default: “ddm”)
verbose (bool) – Enable verbose logging (default: False)

Returns:

Structured result with output file, files created, and summary

Return type:

Raises:

ValidationError – If configuration validation fails
FileError – If file operations fail (reading, writing, permissions)
BathymetryError – If bathymetry operations fail

Examples

>>> import cruiseplan
>>> result = cruiseplan.enrich(config_file="cruise.yaml", add_depths=True)
>>> print(f"Enriched file: {result.output_file}")
>>> print(f"Summary: {result.summary}")

cruiseplan.api.process_cruise.enrich_configuration(config_path: Path, add_depths: bool = False, add_coords: bool = False, expand_sections: bool = False, bathymetry_source: str = 'gebco2025', bathymetry_dir: str = 'data/bathymetry', coord_format: str = 'ddm', output_path: Path | None = None) → dict[str, Any]

Add missing data to cruise configuration.

Enriches the cruise configuration by adding bathymetric depths and formatted coordinates where missing. Port references are automatically resolved to full PortDefinition objects during loading.

Parameters:

config_path (Path) – Path to input YAML configuration.
add_depths (bool, optional) – Whether to add missing depth values (default: False).
add_coords (bool, optional) – Whether to add formatted coordinate fields (default: False).
expand_sections (bool, optional) – Whether to expand CTD sections into individual stations (default: False).
bathymetry_source (str, optional) – Bathymetry dataset to use (default: “gebco2025”).
coord_format (str, optional) – Coordinate format (“ddm” or “dms”, default: “ddm”).
output_path (Optional[Path], optional) – Path for output file (if None, modifies in place).

Returns:

Dictionary with enrichment summary containing: - stations_with_depths_added: Number of depths added - stations_with_coords_added: Number of coordinates added - sections_expanded: Number of CTD sections expanded - stations_from_expansion: Number of stations generated from expansion - total_stations_processed: Total stations processed

Return type:

Dict[str, Any]

cruiseplan.api.process_cruise.enrich_with_config(config_file: str | Path, config: EnrichConfig = None) → EnrichResult[source]

Enrich cruise configuration using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy enrich() function with individual parameters is still available.

Parameters:

config_file (str or Path) – Input YAML configuration file
config (EnrichConfig, optional) – Configuration object containing all enrichment options. If None, default configuration is used.

Returns:

Result object containing enriched config and summary

Return type:

Examples

Basic usage with defaults:

>>> result = enrich_with_config("cruise.yaml")

Custom configuration:

>>> from cruiseplan.api.config import EnrichConfig, BathymetryConfig
>>> config = EnrichConfig(
...     add_depths=True,
...     coord_format="dd",
...     bathymetry=BathymetryConfig(source="gebco2025")
... )
>>> result = enrich_with_config("cruise.yaml", config)

cruiseplan.api.process_cruise.process(config_file: str | Path, output_dir: str = 'data', output: str | None = None, bathy_source: str = 'gebco2025', bathy_dir: str = 'data/bathymetry', add_depths: bool = True, add_coords: bool = True, expand_sections: bool = True, run_validation: bool = True, run_map_generation: bool = True, depth_check: bool = True, tolerance: float = 10.0, format: str = 'all', bathy_stride: int = 10, bathy_contours: list | None = None, lat_bounds: list | None = None, lon_bounds: list | None = None, figsize: list | None = None, no_ports: bool = False, no_title: bool = False, no_labels: bool = False, no_legend: bool = False, verbose: bool = False, max_depth: int | None = None) → ProcessResult[source]

Process cruise configuration with unified workflow (mirrors: cruiseplan process).

This function runs the complete processing workflow: enrichment -> validation -> map generation.

Parameters:

config_file (str or Path) – Input YAML configuration file
output_dir (str) – Output directory for generated files (default: “data”)
output (str, optional) – Base filename for outputs (default: use cruise name from config)
bathy_source (str) – Bathymetry dataset (default: “gebco2025”)
bathy_dir (str) – Directory containing bathymetry data (default: “data/bathymetry”)
add_depths (bool) – Add missing depth values to stations using bathymetry data (default: True)
add_coords (bool) – Add formatted coordinate fields (default: True)
expand_sections (bool) – Expand CTD sections into individual station definitions (default: True)
run_validation (bool) – Run validation after enrichment (default: True)
run_map_generation (bool) – Generate maps after validation (default: True)
depth_check (bool) – Compare existing depths with bathymetry data during validation (default: True)
tolerance (float) – Depth difference tolerance in percent for validation (default: 10.0)
format (str) – Map output format(s): “png”, “kml”, “all” (default: “all”)
bathy_stride (int) – Bathymetry contour stride for maps (default: 10)
figsize (list, optional) – Figure size for maps [width, height] (default: auto)
no_ports (bool) – Suppress plotting of departure and arrival ports on maps (default: False)
no_title (bool) – Omit the map title from PNG output (default: False)
no_labels (bool) – Omit station name annotations from PNG output (default: False)
no_legend (bool) – Omit the legend from PNG output (default: False)
verbose (bool) – Enable verbose logging (default: False)

Returns:

Structured result with all files created, validation results, and summary

Return type:

Examples

>>> import cruiseplan
>>> # Process with all defaults
>>> result = cruiseplan.process("cruise.yaml")
>>> print(f"Files created: {len(result.files_created)}")
>>> # Custom processing workflow
>>> result = cruiseplan.process("cruise.yaml", run_map_generation=False, depth_check=False)

cruiseplan.api.process_cruise.process_with_config(config_file: str | Path, config: ProcessConfig = None) → ProcessResult[source]

Process cruise configuration with unified workflow using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy process() function with individual parameters is still available.

Parameters:

config_file (str or Path) – Input YAML configuration file
config (ProcessConfig, optional) – Configuration object containing all processing options. If None, default configuration is used.

Returns:

Result object containing enriched config and list of output files

Return type:

Examples

Basic usage with defaults:

>>> result = process_with_config("cruise.yaml")

Custom configuration:

>>> from cruiseplan.api.config import ProcessConfig, BathymetryConfig
>>> config = ProcessConfig(
...     add_depths=True,
...     bathymetry=BathymetryConfig(source="gebco2025", stride=5)
... )
>>> result = process_with_config("cruise.yaml", config)

cruiseplan.api.process_cruise.validate(config_file: str | Path, bathy_source: str = 'gebco2025', bathy_dir: str = 'data/bathymetry', check_depths: bool = True, tolerance: float = 10.0, warnings_only: bool = False, verbose: bool = False) → ValidationResult[source]

Validate a cruise configuration file (mirrors: cruiseplan validate).

Parameters:

config_file (str or Path) – Input YAML configuration file
bathy_source (str) – Bathymetry dataset (default: “gebco2025”)
bathy_dir (str) – Directory containing bathymetry data (default: “data”)
check_depths (bool) – Compare existing depths with bathymetry data (default: True)
tolerance (float) – Depth difference tolerance in percent (default: 10.0)
warnings_only (bool) – Show warnings without failing - warnings don’t affect return value (default: False)
verbose (bool) – Enable verbose logging (default: False)

Returns:

Structured validation result with success status, errors, warnings, and summary.

Return type:

Examples

>>> import cruiseplan
>>> # Validate cruise configuration with depth checking
>>> is_valid = cruiseplan.validate(config_file="cruise.yaml", check_depths=True)
>>> # Custom tolerance validation
>>> is_valid = cruiseplan.validate(config_file="cruise.yaml", tolerance=5.0)
>>> if is_valid:
...     print("✅ Configuration is valid")

cruiseplan.api.process_cruise.validate_configuration(config_path: Path, check_depths: bool = False, tolerance: float = 10.0, bathymetry_source: str = 'gebco2025', bathymetry_dir: str = 'data/bathymetry') → tuple[bool, list[str], list[str]]

Comprehensive validation of YAML configuration file.

Performs schema validation, logical consistency checks, and optional depth verification against bathymetry data.

Parameters:

config_path (Path) – Path to input YAML configuration.
check_depths (bool, optional) – Whether to validate depths against bathymetry (default: False).
tolerance (float, optional) – Depth difference tolerance percentage (default: 10.0).
bathymetry_source (str, optional) – Bathymetry dataset to use (default: “gebco2025”).

Returns:

Tuple of (success, errors, warnings) where: - success: True if validation passed - errors: List of error messages - warnings: List of warning messages

Return type:

Tuple[bool, List[str], List[str]]

cruiseplan.api.process_cruise.validate_with_config(config_file: str | Path, config: ValidateConfig = None) → ValidationResult[source]

Validate cruise configuration using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy validate() function with individual parameters is still available.

Parameters:

config_file (str or Path) – Input YAML configuration file
config (ValidateConfig, optional) – Configuration object containing all validation options. If None, default configuration is used.

Returns:

Result object containing validation status and issues

Return type:

Examples

Basic usage with defaults:

>>> result = validate_with_config("cruise.yaml")

Custom configuration:

>>> from cruiseplan.api.config import ValidateConfig, BathymetryConfig
>>> config = ValidateConfig(
...     check_depths=True,
...     tolerance=5.0,
...     bathymetry=BathymetryConfig(source="gebco2025")
... )
>>> result = validate_with_config("cruise.yaml", config)

cruiseplan.api.schedule_cruise module

Cruise schedule generation API.

This module provides the main schedule() function that generates cruise timelines and various output formats (HTML, CSV, NetCDF, PNG, LaTeX).

cruiseplan.api.schedule_cruise.schedule(config_file: str | Path, output_dir: str = 'data', output: str | None = None, format: str | None = 'all', leg: str | None = None, derive_netcdf: bool = False, bathy_source: str = 'gebco2025', bathy_dir: str = 'data/bathymetry', bathy_stride: int = 10, bathy_contours: list | None = None, lat_bounds: list | None = None, lon_bounds: list | None = None, figsize: list | None = None, no_ports: bool = False, no_title: bool = False, no_labels: bool = False, no_legend: bool = False, verbose: bool = False, max_depth: int | None = None) → ScheduleResult[source]

Generate cruise schedule (mirrors: cruiseplan schedule).

Parameters:

config_file (str or Path) – Input YAML configuration file
output_dir (str) – Output directory for schedule files (default: “data”)
output (str, optional) – Base filename for outputs (default: use cruise name from config)
format (str or None) – Output formats: “html”, “latex”, “csv”, “kml”, “netcdf”, “png”, “all”, or None (default: “all”). If None, only computes timeline without generating files.
leg (str, optional) – Process specific leg only (default: process all legs)
derive_netcdf (bool) – Generate specialized NetCDF files (_points.nc, _lines.nc, _areas.nc) (default: False)
bathy_source (str) – Bathymetry dataset (default: “etopo2022”)
bathy_dir (str) – Directory containing bathymetry data (default: “data”)
bathy_stride (int) – Bathymetry contour stride for PNG maps (default: 10)
figsize (list) – Figure size for PNG maps [width, height] (default: [12, 8])
no_ports (bool) – Exclude ports from PNG schedule maps (default: False)
no_title (bool) – Omit the map title from PNG output (default: False)
no_labels (bool) – Omit station name annotations from PNG output (default: False)
no_legend (bool) – Omit the legend from PNG output (default: False)
max_depth (int, optional) – Maximum water depth (m) for the bathymetry colour scale on PNG maps. When provided, clips the deep end so shallow-water structure uses the full colour range. Example: max_depth=1000 spans -1000 to +200 m. Default is None (full -8000 to +200 m range).
verbose (bool) – Enable verbose logging (default: False)

Returns:

Structured result containing timeline, generated files, and summary information. Timeline contains computed schedule data for programmatic use. Files list contains paths to all generated files (HTML, CSV, NetCDF, etc.). Summary contains metadata about the generation process.

Return type:

Examples

>>> import cruiseplan
>>> # Generate all formats and get timeline for analysis
>>> result = cruiseplan.schedule(config_file="cruise.yaml", format="all")
>>> print(f"Generated files: {result.files_created}")
>>> print(f"Timeline has {len(result.timeline)} activities")
>>>
>>> # Find specific file type from generated files
>>> netcdf_file = next(f for f in result.files_created if f.suffix == '.nc')
>>> html_file = next(f for f in result.files_created if f.suffix == '.html')
>>>
>>> # Get only timeline data without generating files
>>> result = cruiseplan.schedule(config_file="cruise.yaml", format=None)
>>> for activity in result.timeline:
...     print(f"{activity['label']}: {activity['start_time']} -> {activity['end_time']}")
>>>
>>> # Load NetCDF file with xarray
>>> result = cruiseplan.schedule(config_file="cruise.yaml", format="netcdf")
>>> netcdf_file = result.files_created[0]  # NetCDF file
>>> import xarray as xr
>>> ds = xr.open_dataset(netcdf_file)

cruiseplan.api.schedule_cruise.schedule_with_config(config_file: str | Path, config: ScheduleConfig = None) → ScheduleResult[source]

Generate cruise schedule using configuration object.

This is the modern API that uses a configuration object to reduce the number of function parameters. For backward compatibility, the legacy schedule() function with individual parameters is still available.

Parameters:

config_file (str or Path) – Input YAML configuration file
config (ScheduleConfig, optional) – Configuration object containing all scheduling options. If None, default configuration is used.

Returns:

Result object containing list of generated schedule files

Return type: