es_sfgtools.workflows.utils.protocols module

class es_sfgtools.workflows.utils.protocols.HasNetworkStationCampaign(*args, **kwargs)

Bases: Protocol

A protocol for classes that have network, station, and campaign attributes.

current_campaign_name: str | None

current_network_name: str | None

current_station_name: str | None

class es_sfgtools.workflows.utils.protocols.WorkflowABC(directory: Path = None, asset_catalog: PreProcessCatalogHandler | None = None, directory_handler: DirectoryHandler | None = None, station_metadata: Site | None = None)

Bases: ABC

Abstract base class for seafloor geodesy workflow implementations.

This class provides a standardized framework for managing hierarchical contexts in seafloor geodesy data processing workflows. It handles the organization of data across four hierarchical levels: network → station → campaign → survey.

The class supports two operational modes:

Setup workflows (mid_process_workflow=False): For initial data organization and directory structure creation
Mid-process workflows (mid_process_workflow=True): For scientific data processing with metadata validation and loading

mid_process_workflow

Flag indicating whether this is a mid-process workflow that requires metadata validation and loading.

Type:: bool, default False

directory

Root directory for the workflow data structure.

Type:: Path

directory_handler

Handler for managing the hierarchical directory structure.

Type:: DirectoryHandler

asset_catalog

Handler for managing data asset catalogs and metadata.

Type:: PreProcessCatalogHandler

current_network_name

Name of the currently active network.

Type:: str or None

current_network_dir

Directory handler for the current network.

Type:: NetworkDir or None

current_station_name

Name of the currently active station.

Type:: str or None

current_station_dir

Directory handler for the current station.

Type:: StationDir or None

current_station_metadata

Metadata object for the current station (loaded in mid-process workflows).

Type:: Site or None

current_campaign_name

Name of the currently active campaign.

Type:: str or None

current_campaign_dir

Directory handler for the current campaign.

Type:: CampaignDir or None

current_campaign_metadata

Metadata object for the current campaign (loaded in mid-process workflows).

Type:: Campaign or None

current_survey_name

Name of the currently active survey.

Type:: str or None

current_survey_dir

Directory handler for the current survey.

Type:: SurveyDir or None

current_survey_metadata

Metadata object for the current survey (loaded in mid-process workflows).

Type:: Survey or None

Notes

The hierarchical context system ensures data organization consistency across different workflow implementations. Each level must be set in order: network → station → campaign → survey.

Context switching at any level automatically resets all dependent lower levels to maintain data integrity and prevent cross-contamination between different organizational contexts.

See also

DirectoryHandler: Core directory management functionality
PreProcessCatalogHandler: Asset catalog management
Site: Station metadata model
Campaign: Campaign metadata model
Survey: Survey metadata model

mid_process_workflow: bool = False

set_campaign(campaign_id: str)

Set the current campaign context and reset survey-level context.

Establishes the campaign-level context within the current station. A campaign represents a specific deployment or measurement period, typically lasting several days to months, during which multiple surveys are conducted.

For mid-process workflows, this method validates that the campaign exists in the station metadata and loads the corresponding Campaign object with deployment details and survey configurations.

Parameters:

campaign_id (str) – The identifier for the campaign to activate. This should match both the directory name in the data structure and the campaign identifier in the station metadata campaigns list.

Raises:

ValueError – If mid_process_workflow=True and the campaign is not found in the current station metadata campaigns list, or if the campaign directory cannot be created or accessed.
AssertionError – If set_station() has not been called first to establish the station context, or if mid_process_workflow=True but station metadata is not available.

Notes

The method performs these operations in sequence:

Reset campaign and survey contexts via _reset_campaign()
If mid_process_workflow=True: - Search station metadata for matching campaign - Load Campaign object into current_campaign_metadata - Set current_campaign_name from metadata
If not mid_process_workflow: - Set current_campaign_name directly from campaign_id
Retrieve or create CampaignDir object from current_station_dir
Store the CampaignDir in current_campaign_dir

Campaign validation in mid-process workflows ensures that only properly configured campaigns are activated, preventing processing errors downstream. The campaign metadata includes deployment dates, instrument configurations, and survey parameters specific to that measurement period.

See also

set_station: Must be called before this method
set_survey: Next step in context hierarchy (mid-process workflows only)
set_network_station_campaign: Convenience method to set multiple contexts
Campaign: Campaign metadata model used for validation and loading

set_network(network_id: str)

Set the current network context and reset all dependent contexts.

Establishes the network-level context for workflow operations. The network represents the top level of the organizational hierarchy and typically corresponds to a geographic region, institutional boundary, or collection of related seafloor geodesy sites.

This method resets all existing contexts and initializes the network-level directory structure, creating the network directory if it doesn’t exist.

Parameters:: network_id (str) – The identifier for the network to activate. This should match the expected directory name in the data structure and serve as a unique identifier for the network.
Raises:: ValueError – If the network directory cannot be created or accessed through the directory handler.

Notes

The method performs these operations in sequence:

Reset all contexts (network, station, campaign, survey) via _reset_network()
Set current_network_name to the provided network_id
Retrieve existing NetworkDir or create new one via directory_handler
Store the NetworkDir in current_network_dir

The network directory is created automatically if it doesn’t exist, making this method suitable for both setup and mid-process workflows. All dependent contexts (station, campaign, survey) are cleared when the network changes to ensure proper hierarchical isolation.

This is typically the first method called in a workflow sequence, followed by set_station(), set_campaign(), and optionally set_survey().

See also

set_station: Next step in context hierarchy
set_network_station_campaign: Convenience method to set multiple contexts
NetworkDir: Network directory management class

set_network_station_campaign(network_id: str, station_id: str, campaign_id: str)

Set the current network, station, and campaign contexts in sequence.

Convenience method that establishes the complete hierarchical context (network → station → campaign) in a single call. This is equivalent to calling set_network(), set_station(), and set_campaign() in sequence, but with parameter validation to ensure all are strings.

Parameters:

network_id (str) – The identifier for the network to activate. This should match the expected directory name and serve as a unique network identifier.
station_id (str) – The identifier for the station to activate. This should match both the directory name and station identifier in metadata files.
campaign_id (str) – The identifier for the campaign to activate. This should match both the directory name and campaign identifier in station metadata.

Raises:

AssertionError – If any of the input parameters are not strings.
ValueError – If any of the individual context setting operations fail. Error messages will indicate which specific context failed to set.

Notes

The method performs parameter validation before calling the individual context setting methods:

Validate all parameters are strings
Call set_network(network_id)
Call set_station(station_id)
Call set_campaign(campaign_id)

This method is particularly useful for workflows that need to establish a known hierarchical context at startup, such as processing workflows that operate on specific campaign data.

All the same rules and behaviors of the individual set_* methods apply, including metadata loading for mid-process workflows and directory creation for setup workflows.

See also

set_network: First step in the sequence
set_station: Second step in the sequence
set_campaign: Third step in the sequence

set_station(station_id: str)

Set the current station context and reset all dependent contexts.

Establishes the station-level context within the current network. The station represents a specific seafloor geodesy site with associated transponders, benchmarks, and measurement infrastructure.

For mid-process workflows (mid_process_workflow=True), this method also loads and validates the station metadata file, which contains critical information about transponder positions, site configuration, and processing parameters.

Parameters:

station_id (str) – The identifier for the station to activate. This should match both the directory name in the data structure and the station identifier in the site metadata files.

Raises:

AssertionError – If mid_process_workflow=True and the site metadata file is not found for the specified station. The metadata file is required for scientific processing operations.
ValueError – If the station directory cannot be created or accessed through the directory handler.

Notes

The method performs these operations in sequence:

Reset station, campaign, and survey contexts via _reset_station()
Set current_station_name to the provided station_id
Retrieve or create the StationDir object from current_network_dir
Store the StationDir in current_station_dir
If mid_process_workflow=True: - Verify site metadata file exists - Load Site metadata from JSON file - Store in current_station_metadata

The site metadata loading in mid-process workflows provides access to transponder configurations, campaign definitions, and other scientific parameters required for data processing and analysis.

See also

set_network: Must be called before this method
set_campaign: Next step in context hierarchy
set_network_station_campaign: Convenience method to set multiple contexts
Site.from_json: Used internally to load station metadata

set_survey(survey_id: str)

Set the current survey context within the current campaign.

Establishes the survey-level context, which represents an individual measurement session within a campaign. Surveys are the finest-grained organizational unit and contain the actual observational data and processing results.

This method is only available for mid-process workflows as it requires access to campaign metadata to validate survey existence and load survey-specific configuration parameters.

Parameters:

survey_id (str) – The identifier for the survey to activate. This should match the survey ID defined in the current campaign’s metadata and correspond to the survey directory name.

Raises:

AssertionError – If mid_process_workflow=False (survey context only available for mid-process workflows), or if survey_id is not a string.
ValueError – If the survey is not found in the current campaign metadata, or if the survey directory cannot be created or accessed.

Notes

The method performs these operations in sequence:

Validate mid_process_workflow=True and survey_id is string
Reset survey context via _reset_survey()
Search current campaign metadata for matching survey
Load Survey object into current_survey_metadata
Retrieve or create SurveyDir object from current_campaign_dir
Store the SurveyDir in current_survey_dir

The decorator @validate_network_station_campaign ensures that network, station, and campaign contexts are properly established before this method can be called.

Survey metadata includes measurement timestamps, instrument configurations, data quality parameters, and processing settings specific to that measurement session.

See also

set_network_station_campaign: Must establish these contexts first
validate_network_station_campaign: Decorator ensuring proper context
Survey: Survey metadata model used for validation and loading

es_sfgtools.workflows.utils.protocols.validate_network_station_campaign(func: Callable[[Concatenate[HasNetworkStationCampaign, P]], R]) → Callable[[Concatenate[HasNetworkStationCampaign, P]], R]