CLI

Note

Looking for documentation on how to use the CLI? Go here Getting Started.

ctdfjorder.cli.cli.add_arguments(parser)

Adds arguments to the argument parser.

Parameters:

parser (argparse.ArgumentParser) – The argument parser to add arguments to.

Notes

This function adds various command-line arguments to the parser, including options for plotting, verbosity, resetting the file environment, showing processing status, running in debug mode, specifying the master sheet path, setting the number of worker processes, providing a Mapbox token, and defining filters for data columns.

ctdfjorder.cli.cli.build_parser()

Builds the argument parser for the command-line interface.

Returns:

The configured argument parser.

Return type:

argparse.ArgumentParser

Notes

This function sets up the argument parser for the command-line interface, defining the available commands and their respective options. It uses RichHelpFormatterPlus for enhanced help text formatting.

ctdfjorder.cli.cli.build_parser_docs()

Builds the argument parser for the documentation.

Returns:

The configured argument parser.

Return type:

argparse.ArgumentParser

Notes

This function sets up the argument parser specifically for generating documentation, defining the available commands and their respective options without the enhanced formatting.

ctdfjorder.cli.cli.create_filters(args)

Creates filters from command-line arguments.

Parameters:

args (argparse.Namespace) – The parsed command-line arguments.

Returns:

A list of filters or None if no filters are specified.

Return type:

list[tuple] | None

Notes

This function generates a list of filters based on the specified columns, upper bounds, and lower bounds provided via command-line arguments. If not all required filter arguments are provided, it returns None.

ctdfjorder.cli.cli.display_config(args)

Displays the configuration of the processing pipeline.

Parameters:

args (argparse.Namespace) – The parsed command-line arguments.

Notes

This function generates a table displaying the configuration options specified via command-line arguments, providing a clear overview of the pipeline settings before execution.

ctdfjorder.cli.cli.generate_status_table(status_table)

Generates a status table displaying the processing status for each file.

Parameters:

status_table (list[tuple]) – A list of tuples containing the file name and its processing status.

Returns:

A rich Table object displaying the status of each file.

Return type:

rich.table.Table

Notes

The table includes columns for each processing step and uses color codes to indicate the status: green for success, yellow for warnings, and red for errors.

ctdfjorder.cli.cli.get_ctd_filenames_in_dir(directory, types)

Gets the filenames of CTD files in a directory.

Parameters:

• directory (str) – The directory to search for CTD files.

• types (list[str]) – A list of file extensions to search for.

Returns:

A list of CTD file paths in the directory.

Return type:

list[str]

Notes

This function searches the specified directory for files with the given extensions (e.g., .rsk, .csv) and returns a list of matching file paths.

ctdfjorder.cli.cli.get_cwd()

Gets the current working directory.

Returns:

The current working directory.

Return type:

str

Notes

If the script is running in a frozen state (e.g., packaged with PyInstaller), it returns the directory of the executable. Otherwise, it returns the standard current working directory.

ctdfjorder.cli.cli.main()

The main entry point for the application. Parses arguments and runs the appropriate processing pipeline.

Notes

This function initializes signal handlers, builds the argument parser, and parses the command-line arguments. Depending on the specified command, it runs the default or Fjord Phyto processing pipeline.

ctdfjorder.cli.cli.plot_data(my_data, plots_folder)

Generates plots for the given CTD data.

Parameters:

• my_data (pl.DataFrame) – The CTD data to plot.

• plots_folder (str) – The folder to save plots in.

Notes

This function generates two types of plots: depth vs potential density and depth vs salinity. The plots are saved in the specified folder.

ctdfjorder.cli.cli.plot_results(df, mapbox_access_token)

Generates plots for the processed CTD data and an interactive map view.

Parameters:

• df (pl.DataFrame) – The processed CTD data.

• mapbox_access_token (str) – The Mapbox access token for generating interactive maps.

Notes

This function generates an interactive map to visualize the data.

ctdfjorder.cli.cli.process_ctd_file(file: str, plot: bool, cached_master_sheet: MasterSheet | None, master_sheet_path: str | None, verbosity: int, plots_folder: str, filters: zip | None, mld_ref: list[int] | None, mld_delta: list[float] | None)

Processes a CTD file through a series of data cleaning and analysis steps.

Parameters:

• file (str) – The path to the CTD file.

• plot (bool) – Flag indicating whether to generate plots.

• cached_master_sheet (MasterSheet) – A cached instance of the master sheet for cross-checking site names.

• master_sheet_path (str) – The path to the master sheet.

• verbosity (int) – The verbosity level for logging.

• plots_folder (str) – The folder to save plots in.

• filters (list) – List of filters to apply to the data.

• mld_ref (list[int]) – List of reference densities for calculating MLD.

• mld_delta (list[float]) – List of delta values for calculating MLD.

Returns:

• pl.DataFrame | None – The processed data as a Polars DataFrame or None if an error occurred.

• list[str] – The status of each processing step, represented by color codes (“green”, “yellow”, “red”).

Notes

The function goes through several steps to process the CTD file, including filtering, removing upcasts and non-positive samples, cleaning salinity data, adding surface measurements, absolute salinity, density, potential density, mixed layer depth (MLD), and Brunt-Väisälä frequency squared (BF Squared). If plotting is enabled, it generates plots for potential density and salinity versus depth.

ctdfjorder.cli.cli.process_results(results, total_files, output_file, plot, plots_folder, mapbox_access_token)

Processes the results of the CTD file processing pipeline.

Parameters:

• results (list[pl.DataFrame]) – The list of processed CTD data.

• total_files (int) – The total number of files processed.

• output_file (str) – The path to the output CSV file.

• plot (bool) – Flag indicating whether to generate plots.

• plots_folder (str) – The folder to save plots in.

• mapbox_access_token (str) – The Mapbox access token for generating interactive maps.

Notes

This function combines the processed data from all files, generates a summary of the data, and saves the combined data to a CSV file. If mapbox access token is provided, it generates various plots and an interactive map using Mapbox.

ctdfjorder.cli.cli.reset_file_environment()

Resets the file environment by removing existing output files and creating necessary directories.

Notes

This function removes old output files and directories to ensure a clean environment for running the CTD file processing pipeline. It creates a new directory for plots.

ctdfjorder.cli.cli.run_default(plot: bool, master_sheet_path: str | None, max_workers: int, verbosity: int, output_file: str | None, debug_run: bool, status_show: bool, mapbox_access_token: str | None, filters: zip | None, mld_ref: list[int] | None = None, mld_delta: list[float] | None = None)

Runs the default processing pipeline for CTD files.

Parameters:

• plot (bool) – Flag indicating whether to generate plots.

• master_sheet_path (str) – The path to the master sheet.

• max_workers (int) – The maximum number of worker processes to use.

• verbosity (int) – The verbosity level for logging.

• output_file (str) – The path to the output CSV file.

• debug_run (bool) – Flag indicating whether to run in debug mode (processes only 20 files).

• status_show (bool) – Flag indicating whether to show the processing status.

• mapbox_access_token (str) – The Mapbox access token for generating interactive maps.

• filters (zip or None) – Filters to apply to the data.

• mld_ref (list[int]) – Reference densities for calculating MLD.

• mld_delta (list[float]) – Delta values for calculating MLD.

Notes

This function orchestrates the entire CTD file processing pipeline. It sets up logging, processes the master sheet, and uses a process pool to handle multiple CTD files concurrently. The processing status of each file is tracked, and results are compiled and saved to a CSV file. If plotting is enabled, it generates plots and an interactive map.

ctdfjorder.cli.cli.setup_logging(verbosity)

Sets up logging for the application.

Parameters:

verbosity (int) – The verbosity level for logging.

Returns:

The configured logger.

Return type:

logging.Logger

Notes

This function configures the logging settings for the application, including setting the log level based on verbosity, formatting log messages, and handling signals for graceful termination.

ctdfjorder.cli.cli.signal_handler(signal_received, frame)

Handles system signals to gracefully terminate the application.

Parameters:

• signal_received (Any) – The received signal.

• frame (frame) – The current stack frame.

Notes

This function handles system signals such as SIGINT and SIGTERM to allow for graceful termination of the application, cleaning up resources as needed.