Metadata-Version: 2.4
Name: slocum-ad2cp
Version: 2.1.0
Summary: Processing and analysis of TWR Slocum Glider-Nortek AD2CP data
Home-page: https://github.com/JGradone/Slocum-AD2CP
Author: Joe Gradone
License: MIT
Project-URL: Bug Tracker, https://github.com/JGradone/Slocum-AD2CP/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: xarray
Requires-Dist: pandas
Requires-Dist: netCDF4
Requires-Dist: scipy
Requires-Dist: gsw
Requires-Dist: dask
Provides-Extra: erddap
Requires-Dist: erddapy; extra == "erddap"
Provides-Extra: dbd
Requires-Dist: dbdreader>=0.6; extra == "dbd"
Requires-Dist: lz4; extra == "dbd"
Provides-Extra: all
Requires-Dist: erddapy; extra == "all"
Requires-Dist: dbdreader>=0.6; extra == "all"
Requires-Dist: lz4; extra == "all"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Slocum-AD2CP

Slocum-AD2CP is a package designed to process Nortek AD2CP data from Teledyne Webb Research Slocum gliders. The package is designed to walk through the steps to process AD2CP data in several Jupyter notebooks.

Please cite this package using this [DOI](https://doi.org/10.5281/zenodo.7416126). The intention for publishing this code on GitHub is twofold: 1) to make glider based acoustic current profiler data easier to work with and 2) to improve upon the processing workflow and make it more transparent. For these reasons, I encourage comments, questions, concerns, and for users of this code to report any potential bugs. Please do not hesitate to reach out to me at jgradone@marine.rutgers.edu.

<img width="680" alt="Screen Shot 2022-11-30 at 1 01 27 PM" src="https://user-images.githubusercontent.com/43152605/204873998-595184d4-4221-49bf-9134-cc85f56b9bb0.png">

Installation
----------------------
slocum_ad2cp can be install via: <br/>
`pip install slocum_ad2cp`

Processing Raw AD2CP Data
----------------------
This package is built under the assumption that users are processing their AD2CP data to NetCDFs using the Nortek MIDAS software.


Changelog
----------------------
**2.1.0, 2026-10-02**

- Added a `glider.py` module with an interchangeable glider data backend: alongside the existing `get_erddap_dataset` path, `load_glider_dbd`/`load_glider`(`source="dbd"`) reads raw Slocum dbd/ebd files (and their LZ4-compressed dcd/ecd counterparts, needs `dbdreader>=0.6`) directly, useful before a deployment is published to ERDDAP. Both backends return the same segment-table schema.
- Added `correct_ad2cp_mounting` / `detect_roll_offset` to `make_dataset.py`. Some Slocum payload-bay AD2CP mounts report roll 180 degrees from the glider's own frame; left uncorrected, `cell_vert` returns negative cell depths and `binmap_adcp` silently drops every bin. Opt-in, not called by the existing pipeline.
- **Fixed a bug in `beam2enu`** (`make_dataset.py`): the function computed a pitch-dependent 3-of-4-beam selection (dropping the aft beam on downcasts, the forward beam on upcasts, per the glider's actual attitude) and then unconditionally discarded that choice, always applying the beam 2/3/4 transform regardless of pitch. `beam2enu` now takes `honour_pitch_selection` (default `True`, the corrected behaviour); pass `False` to reproduce the pre-fix output. Verified against an independent AHRS rotation matrix and glider compass on a deployment where the beam-selection bug produced a horizontal-velocity direction scattered by 117 degrees against the glider's own heading versus 12 degrees corrected, and biased mean vertical velocity by -0.14 m/s.
  - **This changes output for existing callers**, including both example notebooks, which call `beam2enu(subset_ad2cp)` with no argument. `processed_data/RU29_2024_Processed_AD2CP.nc` and the per-segment CSVs have been regenerated with the fix; the pre-fix files are kept in `processed_data/pre_beam2enu_fix_backup/` for reference. RMS difference across the regenerated grid is 0.02 m/s (u) and 0.017 m/s (v), with individual bins shifting up to 0.26 m/s; 97.5% of output bins changed at all. Coverage is unchanged (97.5%). These files were regenerated before the two `beam2enu` fixes below and do not include them yet.
- **Fixed the AHRS rotation in `beam2enu`**: `calcAHRS` stores each 3x3 rotation matrix flattened column by column, but `beam2enu` read it back row by row, which gives the transpose (the inverse rotation). The horizontal velocity direction was off by roughly (constant - 2 x heading), up to 160 degrees on ru37 and uvi_01; corrected, the flow bearing agrees with the glider compass to within a few degrees. New argument `ahrs_order` (default `'F'`, corrected); pass `'C'` to reproduce older output.
- **`beam2enu` now uses all four beams**: the three-beam solution (a 3x3 slice of the 4x4 beam-to-XYZ matrix) drops one of the forward/aft pair that the along-glider velocity depends on, X = 0.678 (b1 - b3). That roughly halved the along-glider velocity (and its shear) and leaked it into a spurious vertical velocity. Because the four beams are redundant (b1 + b3 = r (b2 + b4)), the beam pointing the wrong way for the pitch is now rebuilt from the other three and the full matrix is applied, as `gliderad2cp` does. On uvi_01 this raises horizontal speed from 0.09 m/s to 0.36 m/s, matching dead reckoning. New argument `redundant_beams` (default `True`); raises an error if the instrument's matrix is not the standard Janus layout. Pass `redundant_beams=False, honour_pitch_selection=False, ahrs_order='C'` to reproduce 2.0.0 output.
  - **This changes `UVelocity`, `VVelocity` and `WVelocity` for all existing callers.** Reprocess any output made with 2.0.0.
