You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/source/api_reference.rst
+137-6Lines changed: 137 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,6 +3,29 @@ API Reference
3
3
4
4
This section provides detailed API documentation for all SeaSenseLib modules.
5
5
6
+
Top-Level API Functions
7
+
-----------------------
8
+
9
+
These convenience functions are the main entry points for most users and are available directly on the ``seasenselib`` package (commonly imported as ``ssl``).
The Level-1 processing pipeline transforms raw data into standardized, CF/ACDD-compliant datasets through a sequence of configurable stages. See the :doc:`user_guide` for a conceptual overview; the classes and factory functions below make up its public API.
``seasenselib.parameters`` defines the canonical (standardized) variable names used throughout SeaSenseLib — for example ``TEMPERATURE = 'temperature'`` and ``SALINITY = 'salinity'``. Reader mappings translate instrument-specific column names onto these canonical names.
351
+
352
+
To list the canonical parameters available at runtime, use the top-level helper:
You do not need to install these individually — they come with SeaSenseLib.
15
+
16
+
If you are new to Python, first check that Python 3.10+ is available:
17
+
18
+
.. code-block:: bash
19
+
20
+
python3 --version
21
+
22
+
If it reports a version below 3.10 (or the command is not found), install a current Python from `python.org <https://www.python.org/downloads/>`_ or via a distribution such as Miniconda (see below) before continuing.
12
23
13
24
Install from PyPI
14
25
-----------------
@@ -21,6 +32,25 @@ The easiest way to install SeaSenseLib is using pip:
21
32
22
33
This will install SeaSenseLib and all required dependencies.
23
34
35
+
Using conda or mamba
36
+
--------------------
37
+
38
+
Many oceanographers manage Python with Anaconda/Miniconda (``conda``) or its faster drop-in replacement ``mamba``. SeaSenseLib is not yet published on conda-forge, so you create a conda environment and then install SeaSenseLib into it with ``pip``:
39
+
40
+
.. code-block:: bash
41
+
42
+
# with conda
43
+
conda create -n seasenselib python=3.11
44
+
conda activate seasenselib
45
+
pip install seasenselib
46
+
47
+
# or with mamba (same commands, faster solver)
48
+
mamba create -n seasenselib python=3.11
49
+
mamba activate seasenselib
50
+
pip install seasenselib
51
+
52
+
Installing with ``pip`` inside an activated conda environment is expected and supported here. Do not run ``conda install seasenselib`` — the package is not on any conda channel and that command will fail.
53
+
24
54
Development Installation
25
55
------------------------
26
56
@@ -63,7 +93,21 @@ If you want to contribute to the project or modify the code, follow these steps:
63
93
pip install --upgrade pip setuptools wheel
64
94
pip install -e ".[dev]"
65
95
66
-
This installs SeaSenseLib in "editable" mode along with development dependencies like pytest and sphinx.
96
+
This installs SeaSenseLib in "editable" mode (changes to the source take effect immediately without reinstalling). The ``[dev]`` part is an optional dependency group that adds tools needed only for development — pytest (running tests), sphinx, nbsphinx, myst-parser and the RTD theme (building these docs), plus build and twine (packaging). A plain ``pip install -e .`` skips those.
97
+
98
+
The same editable install works inside a conda/mamba environment: activate the environment first, then run the ``pip install -e ".[dev]"`` command.
99
+
100
+
**Using the conda environment file:**
101
+
102
+
For development with conda, the repository provides an ``environment.yml`` that creates an environment named ``seasenselib`` with Python (3.10–3.13), ``gsw``, ``pandoc``, and all runtime and development dependencies:
103
+
104
+
.. code-block:: bash
105
+
106
+
conda env create -f environment.yml
107
+
conda activate seasenselib
108
+
pip install -e .
109
+
110
+
The environment file installs the dependencies but not SeaSenseLib itself, so the final ``pip install -e .`` installs the package in editable mode from the repository root.
67
111
68
112
Alternative Installation Methods
69
113
--------------------------------
@@ -111,7 +155,9 @@ This should display the available commands and options.
111
155
112
156
.. code-block:: bash
113
157
114
-
python -m unittest discover tests/
158
+
python -m pytest tests/
159
+
160
+
(``python -m unittest discover tests/`` also works if you prefer the standard library test runner.)
SeaSenseLib reads oceanographic sensor data from many instrument formats, standardizes it, and lets you convert or visualize it — all through a single, consistent interface built on `xarray <https://docs.xarray.dev/>`_ Datasets.
4
5
5
-
Some notes about how to use the SeaSenseLib package, and where it fits into a data processing pipeline.
6
+
This page describes how the pieces fit together. For installation see :doc:`installation`, for the full list of formats see :doc:`supported_formats`, and for detailed signatures see :doc:`api_reference`.
7
+
8
+
Where it fits in a data workflow
9
+
--------------------------------
10
+
11
+
A typical SeaSenseLib workflow has three steps:
12
+
13
+
1. **Read** a raw instrument file into an xarray ``Dataset``. During reading, an optional processing *pipeline* normalizes variable names and units, derives parameters, and adds CF/ACDD-compliant metadata.
14
+
2. **Process** the Dataset further if needed — subset, resample, or compute statistics — using standard xarray operations or the built-in processors.
15
+
3. **Write** the Dataset to a standard format (NetCDF, CSV, Excel), or **plot** it (depth profile, time series, T-S diagram).
When automatic format detection is not enough (ambiguous extensions such as ``.mat`` or ``.hex``), pass an explicit ``file_format`` key — see :doc:`supported_formats`.
46
+
47
+
The processing pipeline
48
+
-----------------------
49
+
50
+
By default, reading applies a processing pipeline that turns raw data into a standardized Level-1 dataset. You can choose how much processing to apply with the ``pipeline_profile`` argument:
51
+
52
+
.. code-block:: python
53
+
54
+
ds = ssl.read("station001.cnv", pipeline_profile="minimal") # mapping only
ds = ssl.read("station001.cnv", pipeline_profile="full") # all stages
57
+
58
+
- ``minimal`` — variable-name mapping and finalization only.
59
+
- ``default`` — conservative Level-1 processing (no unit conversion).
60
+
- ``full`` — the complete Level-1 pipeline with all stages and handlers.
61
+
62
+
For raw, unprocessed data, use the CLI ``--raw-only`` flag or skip the pipeline stages you do not want. The pipeline is fully configurable; its stages, profiles, and public API are described in :doc:`user_guide` and :doc:`api_reference`.
63
+
64
+
Command-line interface
65
+
----------------------
66
+
67
+
Everything above is also available from the command line:
0 commit comments