Usage
=====
Installation
------------
This software can be used in a few different ways. To run processing workflows,
called 'procedures', there is a command line cli, that resides in main.py and
runs workflow files on given CTD data files.
The easiest way to install CLI interface called 'ctdam' is to use `uv `_ or `pipx `_:
.. code-block:: console
$ uv tool install --from 'ctdam[all]' ctdam
$ uv run ctdam check
All set, you are ready to go.
.. code-block:: console
$ pipx install ctdam
$ ctdam check
All set, you are ready to go.
Otherwise, via basic python package managers, like pip, conda or poetry:
.. code-block:: console
# using pip
$ python -m venv .venv
$ source .venv/bin/activate
$ pip install ctd-processing
$ python src/processing/main.py check
All set, you are ready to go.
# using poetry
$ poetry install
$ poetry env activate
$ ctdam check
All set, you are ready to go.
CLI
---
The CLI 'ctdam' should be the main entry point to the software. It allows
running and editing of procedure workflows. It features the following commands:
.. code-block:: console
$ ctdam --help
Usage: ctdam [OPTIONS] COMMAND [ARGS]...
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or customize the installation. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ run Processes one target file using the given procedure workflow file. │
│ convert Converts a list of Sea-Bird raw data files (.hex) to .cnv files. │
│ batch Applies a processing config to multiple .hex or. cnv files. │
│ edit Opens a procedure workflow file in GUI for editing. │
│ show Display the contents of a procedure workflow file. │
│ check Assures that all requirements to use this tool are met. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
The top three commands are the commands to run processing workflows, while the
other ones are for editing workflow files and general checking whether the
requirements are met.
To get more specific information to the individual commands and their arguments,
you can display help sites for each of them:
.. code-block:: console
$ ctdam batch --help
Usage: ctdam batch [OPTIONS] INPUT_DIR CONFIG
Applies a processing config to multiple .hex or. cnv files.
Parameters ---------- input_dir: Path | str : The data directory with the target files. config: dict | Path | str: Either an explicit config as dict or a path to a .toml config file. pattern: str : A
name pattern to filter the target files with. (Default is ".cnv")
Returns ------- A list of paths or CnvFiles of the processed files.
╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * input_dir TEXT [default: None] [required] │
│ * config TEXT [default: None] [required] │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --pattern TEXT [default: .cnv] │
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Processing workflows
-----
The workflow files configure everything needed to run a processing procedure and are easy to understand and write.
Another way is to run processing procedures directly from your python code,
using either workflow files or the fact that these workflows correspond to a
basic python dictionary internally. This allows for quick scripts that can use
flexible input variables.
.. warning:: To run Sea-Bird processing modules, you need a local installation of `them, from their website. `__
.. code-block:: python
from ctdam.proc import Procedure
# using own dictionary:
proc_config = {
"psa_directory": "path_to_psas",
"output_dir": "path_to_output",
"modules": {
"datcnv": {"psa": "DatCnv.psa"},
"wildedit_geomar": {"std1": 3.0, "window_size": 100},
"celltm": {"psa": ("CellTM.psa")},
},
}
procedure = Procedure(proc_config)
# using a .toml workflow file:
procedure = Procedure("proc_template.toml")
Workflow files
--------------
The workflow dictionary used in the example above corresponds to this .toml workflow file:
.. code-block:: toml
# example_config.toml
psa_directory = "path_to_psas"
output_dir = "path_to_output"
[modules.datcnv]
psa = "DatCnv.psa"
[modules.wildedit_geomar]
std1 = 3.0
window_size = 100
[modules.celltm]
psa = "CellTM.psa"
It does not matter, which way you provide the processing workflow information,
the two above examples work in exactly the same way. The different options
available and how to use them, are shown below:
.. literalinclude:: ../proc_template.toml
:language: toml
:caption: proc_template.toml
.. tip:: The only mandatory option is the **modules** dictionary, describing the steps to run on the file(s). All other options are optional.
A simple gui can be used to write and edit workflow files,
which, at the moment, is run like this:
.. code-block:: console
ctdam edit path_to_toml.toml
.. image:: images/procedure_gui.png
.. note:: All options for the Procedure class can be found :doc:`here `.