Skip to content

Commit d992cb3

Browse files
jklymakjklymak
committed
DOC: add start fo docs
1 parent 982d401 commit d992cb3

19 files changed

+519
-7
lines changed

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
*.egg-info
22
__pycache__
3+
_build
34

45
*.nc
56
*.png

‎docs/Install.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Installation
2+
3+
## Dependencies
4+
5+
- install conda/miniconda
6+
- clone the repository onto your computer and cd into the directory
7+
- from inside the cloned repository directory run
8+
`conda env create -f environment.yml`, it will read environment.yml and
9+
automatically install the dependencies, and create environment `pyglider`,
10+
(though you can change the name by editing `environment.yml`)
11+
12+
## Editable installation
13+
14+
If you want to be able to edit the files in `pyglider/pyglider` then install
15+
as above, and then do `pip install -e .`. That will re-install pyglider
16+
with links to the local directory, so you can edit the library files.
17+
If you do so consider making a pull-request with your changes!

‎docs/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/conf.py

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
# import os
14+
# import sys
15+
# sys.path.insert(0, os.path.abspath('.'))
16+
17+
18+
# -- Project information -----------------------------------------------------
19+
20+
project = 'pyglider'
21+
copyright = '2022, Jody Klymak, Callum Rollo'
22+
author = 'Jody Klymak, Callum Rollo'
23+
24+
# The full version, including alpha/beta/rc tags
25+
release = '0.0'
26+
27+
28+
# -- General configuration ---------------------------------------------------
29+
30+
# Add any Sphinx extension module names here, as strings. They can be
31+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32+
# ones.
33+
extensions = [
34+
"numpydoc",
35+
"myst_parser",
36+
'sphinx.ext.autodoc',
37+
'sphinx.ext.inheritance_diagram',
38+
'autoapi.sphinx',
39+
]
40+
41+
extensions.append('sphinx.ext.intersphinx')
42+
43+
intersphinx_mapping = {
44+
'xarray': ('http://xarray.pydata.org/en/stable/', None),
45+
'python': ('https://docs.python.org/3/', None),
46+
}
47+
48+
49+
50+
autoapi_modules = {'pyglider': None}
51+
52+
# Add any paths that contain templates here, relative to this directory.
53+
templates_path = ['_templates']
54+
55+
# List of patterns, relative to source directory, that match files and
56+
# directories to ignore when looking for source files.
57+
# This pattern also affects html_static_path and html_extra_path.
58+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
59+
60+
61+
# -- Options for HTML output -------------------------------------------------
62+
63+
# The theme to use for HTML and HTML Help pages. See the documentation for
64+
# a list of builtin themes.
65+
#
66+
html_theme = 'alabaster'
67+
68+
# Add any paths that contain custom static files (such as style sheets) here,
69+
# relative to this directory. They are copied after the builtin static files,
70+
# so a file named "default.css" will overwrite the builtin "default.css".
71+
html_static_path = ['_static']

‎docs/getting-started-seaexplorer.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Getting Started: SeaExplorer
2+
3+
4+
## Gather data
5+
6+
SeaExplorers send back and record two main types of files, glider files (`*.gli.*`) that contain glider navigation information, and payload files (`*.pld1.*`) that contain the science data. These can be subset files, `*.sub.*` that Alseamar decimates for transmission, or they can be full resolution files from the glider (`*.raw.*`), offloaded post mission. The raw or subset files need to be made available in a single directory for `pyglider` to process.
7+
8+
## Make a deployment configuration file
9+
10+
The processing routines all take a `deployment.yaml` file as an argument, and information from this is used to fill in metadata and to map sensor names to NetCDF variable names. See {ref}`ExDepl`, below.
11+
12+
There are four top-levels to the `deployment.yaml`
13+
14+
- `metadata`: The only field that is necessary here is `glider_name`. The rest of the fields will be added to the netcdf files as top-level attributes
15+
- `glider_devices`: This is a list of the glider devices, and any information about them like make, mode, serial number. This is optional, and again is added to the netcdf top-level attributes
16+
- `netcdf_variables`: These are necessary, and map from sensor name (e.g. `source: GPCTD_CONDUCTIVITY`) to a data variable name (e.g. `conductivity`). The fields other than `source:` are optional for the processing to run, and are placed in the attributes of the netCDF variable. However, note that many of these attributes are necessary for CF compliance.
17+
- `profile_variables`: This is a mapping for variables that are per-profile, rather than timeseries. They include variables like a mean position and time for the profile, and a mean derived ocean velocities.
18+
19+
## Process
20+
21+
The example script is relatively straight forward if there is no intermediate processing. See {ref}`ExProc`, below.
22+
23+
Data comes from an input directory, and is translated to raw glider-dependent netCDF files and put in a new directory. These files are useful of their own right, but are not CF compliant. These files are then merged into a single monolithic netCDF file, and this is translated to a CF-compliant timeseries file. Finally individual profiles are saved and a 2-D 1-m grid in time-depth is saved.
24+
25+
It is likely that between these steps the user will want to add any screening steps, or adjustments to the calibrations. PyGlider does not provide those steps.
26+
27+
## Plotting
28+
29+
Optionally, PyGlider provides some bespoke plotting routines. We find these useful for realtime monitoring of data as it is telemetered back from deployed gliders, so they are provided here for reference. They use a separate `plotting.yml` file to configure the subplots.
30+
31+
32+
(ExDepl)=
33+
### Example deployment.yaml
34+
35+
```{literalinclude} ../example-seaexplorer/deploymentRealtime.yml
36+
:language: yaml
37+
```
38+
39+
(ExProc)=
40+
### Example processing script
41+
42+
```{literalinclude} ../example-seaexplorer/process_deploymentRealtime.py
43+
:language: python
44+
```

‎docs/getting-started-slocum.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Getting Started: Slocum
2+
3+
## Gather data
4+
5+
## Make configuration files
6+
7+
## Process

‎docs/index.md

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
2+
PyGlider: Convert glider data to NetCDF
3+
=======================================
4+
5+
PyGlider converts raw glider files to NetCDF timeseries and netcdf depth-time grids,
6+
using python and based on {ref}`xarray`. The NetCDF files should be largely CF compliant.
7+
8+
The basic workflow is three glider-dependent steps to make a netcdf timeseries, followed
9+
by optional steps to create profiles or depth-time grids.
10+
11+
```python
12+
seaexplorer.raw_to_rawnc(rawdir, rawncdir, deploymentyaml)
13+
seaexplorer.merge_rawnc(rawncdir, rawncdir, deploymentyaml, kind='sub')
14+
outname = seaexplorer.raw_to_timeseries(rawncdir, tsdir, deploymentyaml, kind='sub')
15+
# optional...
16+
ncprocess.extract_timeseries_profiles(outname, profiledir, deploymentyaml)
17+
outname2 = ncprocess.make_gridfiles(outname, griddir, deploymentyaml)
18+
# optional plotting
19+
pgplot.grid_plots(outname2, plottingyaml)
20+
```
21+
22+
Data comes from and is written in directories, and metadata is supplied by a yaml file.
23+
24+
Currently only [Alseamar SeaExplorer](https://www.alseamar-alcen.com/products/underwater-glider/seaexplorer) and [Teledyne/Webb Slocum](http://www.teledynemarine.com/autonomous-underwater-gliders) glider data files are supported, and those with limited configurations. Other gliders will hopefully be added. If you have a glider type or configuration you would like added, [open an issue or pull request!](https://github.com/c-proof/pyglider).
25+
26+
```{toctree}
27+
---
28+
maxdepth: 1
29+
---
30+
Install
31+
getting-started-seaexplorer
32+
getting-started-slocum
33+
plotting
34+
pyglider/pyglider
35+
36+
```
37+
38+
### Acknowledgements
39+
40+
- Slocum binary translator based on
41+
<https://gitlab.oceantrack.org/ocean-gliders-canada/dinkum/tree/seabBranch_py3>
42+
- Processing steps closely follow the work by SOCIB
43+
<https://github.com/socib/glider_toolbox>
44+
- Rutger's description of the Slocum binary files is very helpful: <https://github.com/kerfoot/spt/wiki/Slocum-Glider-Data-File-Primer>
45+
- The somewhat arcane metadata format for NGDAC is here: <https://github.com/ioos/ioosngdac/wiki/NGDAC-NetCDF-File-Format-Version-2>
46+
47+
48+
Indices and tables
49+
==================
50+
51+
* {ref}`genindex`
52+
* {ref}`modindex`
53+
* {ref}`search`

‎docs/make.bat

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/plotting.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Plotting

0 commit comments

Comments
 (0)