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 = 'etopo2022', bathy_dir: str = 'data', bathy_stride: int = 5, figsize: list | None = None, show_plot: bool = False, no_ports: bool = False, verbose: bool = False) → 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: “etopo2022”)
bathy_dir (str) – Directory containing bathymetry data (default: “data”)
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)
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 = 'etopo2022', 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, figsize: list | None = None, no_port_map: bool = False, verbose: bool = False) → 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: “etopo2022”)
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”, “pdf”, “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_port_map (bool) – Skip port overview map generation (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 = 'etopo2022', bathy_dir: str = 'data/bathymetry', bathy_stride: int = 10, figsize: list | None = None, verbose: bool = False) → 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])
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.stations(lat_bounds: tuple[float, float] | None = None, lon_bounds: tuple[float, float] | None = None, output_dir: str = 'data', output: str | None = None, pangaea_file: str | None = None, bathy_source: str = 'etopo2022', bathy_dir: str = 'data', high_resolution: bool = False, 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 PANGAEA data or defaults.
lon_bounds (tuple, optional) – Longitude bounds as (min, max). If None, derived from PANGAEA data or defaults.
output_dir (str) – Output directory for generated YAML file
output (str, optional) – Output filename (default: “stations.yaml” or based on PANGAEA file)
pangaea_file (str, optional) – Path to PANGAEA campaigns pickle file
bathy_source (str) – Bathymetry source (“etopo2022” or “gebco2025”)
bathy_dir (str) – Bathymetry data directory
high_resolution (bool) – Use high resolution bathymetry (slower)
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 or PANGAEA file cannot be loaded
FileNotFoundError – If 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 = 'etopo2022', 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: “etopo2022”)
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 = 'etopo2022', 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, suffix: str = 'map') → 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 = 'etopo2022', bathy_dir: str = 'data', bathy_stride: int = 5, figsize: list | None = None, show_plot: bool = False, no_ports: bool = False, verbose: bool = False) → 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: “etopo2022”)
bathy_dir (str) – Directory containing bathymetry data (default: “data”)
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)
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 = 'etopo2022', 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: “etopo2022”)
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 = 'etopo2022', bathymetry_dir: str = 'data', 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: “etopo2022”).
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 = 'etopo2022', 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, figsize: list | None = None, no_port_map: bool = False, verbose: bool = False) → 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: “etopo2022”)
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”, “pdf”, “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_port_map (bool) – Skip port overview map generation (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 = 'etopo2022', 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: “etopo2022”)
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 = 'etopo2022', bathymetry_dir: str = 'data') → 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: “etopo2022”).

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 = 'etopo2022', bathy_dir: str = 'data/bathymetry', bathy_stride: int = 10, figsize: list | None = None, verbose: bool = False) → 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])
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: