diff --git a/.gitignore b/.gitignore index 1ab2593..46dc655 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,5 @@ extensions/test *.so notebooks/ .idea +mkdocs-venv +site \ No newline at end of file diff --git a/docs/adcp_functions.md b/docs/adcp_functions.md new file mode 100644 index 0000000..ecde67a --- /dev/null +++ b/docs/adcp_functions.md @@ -0,0 +1,3 @@ +# ADCP Functions Reference + +::: ion_functions.data.adcp_functions diff --git a/docs/assets/NSF-OOI-RGB.png b/docs/assets/NSF-OOI-RGB.png new file mode 100755 index 0000000..3586ba6 Binary files /dev/null and b/docs/assets/NSF-OOI-RGB.png differ diff --git a/docs/co2_functions.md b/docs/co2_functions.md new file mode 100644 index 0000000..b7e0c0f --- /dev/null +++ b/docs/co2_functions.md @@ -0,0 +1,3 @@ +# CO2 Functions Reference + +::: ion_functions.data.co2_functions diff --git a/docs/ctd_functions.md b/docs/ctd_functions.md new file mode 100644 index 0000000..3286964 --- /dev/null +++ b/docs/ctd_functions.md @@ -0,0 +1,3 @@ +# CTD Functions Reference + +::: ion_functions.data.ctd_functions diff --git a/docs/do2_functions.md b/docs/do2_functions.md new file mode 100644 index 0000000..2d56911 --- /dev/null +++ b/docs/do2_functions.md @@ -0,0 +1,3 @@ +# DOSTA Functions Reference + +::: ion_functions.data.do2_functions diff --git a/docs/flo_functions.md b/docs/flo_functions.md new file mode 100644 index 0000000..aea662c --- /dev/null +++ b/docs/flo_functions.md @@ -0,0 +1,3 @@ +# Fluorometer Functions Reference + +::: ion_functions.data.flo_functions \ No newline at end of file diff --git a/docs/hyd_functions.md b/docs/hyd_functions.md new file mode 100644 index 0000000..bab796e --- /dev/null +++ b/docs/hyd_functions.md @@ -0,0 +1,3 @@ +# Hydrophone Functions Reference + +::: ion_functions.data.hyd_functions \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..7edf7fe --- /dev/null +++ b/docs/index.md @@ -0,0 +1,35 @@ +# Ocean Observatories Initiative Ion Functions Documentation + +This is documentation for the Ocean Observatories Initiative (OOI) Ion Functions package, which contains code for calculating L1 and L2 properties from OOI L0 observational data. For information on the OOI, visit [the website](https://oceanobservatories.org/). To explore OOI data including fields calculated using these ion functions, visit the [OOI Data Explorer](https://dataexplorer.oceanobservatories.org/). The source code for the Ion Functions module is available on [GitHub](https://github.com/oceanobservatories/ion-functions), and is linked directly throughout the documentation. + +The Ion Functions package houses functions to generate various calculated parameters from OOI data parameters. These calculated parameters are calculated at request time by the OOI infrastructure and are delivered to users alongside the rest of the measured parameters for each instrument. + + +## Project layout + * `ion_functions`: top level package + - `data`: contains many modules for each of the different instruments requiring calculated parameters/ + - `qc`: contains various quality controls tests and datasets + - `test`: contains unit tests for the modules in `data` + +## Project documentation + +### Reference documentation for each of the ion functions modules. + * [ADCP](adcp_functions.md) + * [CTD](ctd_functions.md) + * [CO2](co2_functions.md) + * [DOSTA](do2_functions.md) + * [Fluorometer](flo_functions.md) + * [Hydrophone](hyd_functions.md) + * [Optical Backscatter](obs_functions.md) + * [Met](met_functions.md) + * [Disolved Gas](msp_functions.md) + * [Disolved Nitrogen](nit_functions.md) + * [Seismometer](obs_functions.md) + * [OPTAA](opt_functions.md) + * [pH](ph_functions.md) + * [Seafloor Pressure](prs_functions.md) + * [Seafloor Hydrothermal Vent](sfl_functions.md) + * [Velocity](vel_functions.md) + * [WAVSS](wav_functions.md) +### Quality Control and Testing + * [QC information](qc-tests.md) diff --git a/docs/met_functions.md b/docs/met_functions.md new file mode 100644 index 0000000..7c886c0 --- /dev/null +++ b/docs/met_functions.md @@ -0,0 +1,3 @@ +# Met Functions Reference + +::: ion_functions.data.met_functions \ No newline at end of file diff --git a/docs/msp_functions.md b/docs/msp_functions.md new file mode 100644 index 0000000..4ebf110 --- /dev/null +++ b/docs/msp_functions.md @@ -0,0 +1,3 @@ +# Dissolved Gas Concentrations Functions Reference + +::: ion_functions.data.msp_functions \ No newline at end of file diff --git a/docs/nit_functions.md b/docs/nit_functions.md new file mode 100644 index 0000000..7dc4d8c --- /dev/null +++ b/docs/nit_functions.md @@ -0,0 +1,3 @@ +# Dissolved Nitrate Concentration Functions Reference + +::: ion_functions.data.nit_functions \ No newline at end of file diff --git a/docs/obs_functions.md b/docs/obs_functions.md new file mode 100644 index 0000000..58ac956 --- /dev/null +++ b/docs/obs_functions.md @@ -0,0 +1,3 @@ +# Ocean Bottom Seismometer Functions Reference + +::: ion_functions.data.obs_functions \ No newline at end of file diff --git a/docs/opt_functions.md b/docs/opt_functions.md new file mode 100644 index 0000000..6ca00b3 --- /dev/null +++ b/docs/opt_functions.md @@ -0,0 +1,7 @@ +# OPTAA Functions Reference + +::: ion_functions.data.opt_functions + +## OPTAA Temperature and Salinity corrections + +::: ion_functions.data.opt_functions_tscor \ No newline at end of file diff --git a/docs/ph_functions.md b/docs/ph_functions.md new file mode 100644 index 0000000..9173fd9 --- /dev/null +++ b/docs/ph_functions.md @@ -0,0 +1,3 @@ +# pH Functions Reference + +::: ion_functions.data.ph_functions \ No newline at end of file diff --git a/docs/polycals.md b/docs/polycals.md new file mode 100644 index 0000000..0c1a192 --- /dev/null +++ b/docs/polycals.md @@ -0,0 +1,5 @@ + + + \ No newline at end of file diff --git a/docs/prs_functions.md b/docs/prs_functions.md new file mode 100644 index 0000000..764b1eb --- /dev/null +++ b/docs/prs_functions.md @@ -0,0 +1,6 @@ +# Seafloor Pressure Functions Reference + +::: ion_functions.data.prs_functions + +## OTTILT-CCMP correction coefficients +::: ion_functions.data.prs_functions_ccmp \ No newline at end of file diff --git a/docs/qc-tests.md b/docs/qc-tests.md new file mode 100644 index 0000000..ecfad73 --- /dev/null +++ b/docs/qc-tests.md @@ -0,0 +1,9 @@ +# Information on the Quality Controls and Testing for the Ion Functions module + +## QC procedures +Stuff and things + +## Tests +Run the unit tests with `python -m pytest .`. + +Other tests... \ No newline at end of file diff --git a/docs/sfl_functions.md b/docs/sfl_functions.md new file mode 100644 index 0000000..04db912 --- /dev/null +++ b/docs/sfl_functions.md @@ -0,0 +1,6 @@ +# Hydrothermal Vent Fluid In-situ Chemistry Functions Reference + +::: ion_functions.data.sfl_functions + +## SFL Calibration Parameters +::: ion_functions.data.sfl_functions_surface \ No newline at end of file diff --git a/docs/utility_functions.md b/docs/utility_functions.md new file mode 100644 index 0000000..c3d7199 --- /dev/null +++ b/docs/utility_functions.md @@ -0,0 +1,5 @@ +# Utility Functions Reference + +::: ion_functions.data.generic_functions + +::: ion_functions.data.interpolation \ No newline at end of file diff --git a/docs/vel_functions.md b/docs/vel_functions.md new file mode 100644 index 0000000..11bb358 --- /dev/null +++ b/docs/vel_functions.md @@ -0,0 +1,3 @@ +# Velocity Functions Reference + +::: ion_functions.data.vel_functions \ No newline at end of file diff --git a/docs/wav_functions.md b/docs/wav_functions.md new file mode 100644 index 0000000..44d1a1d --- /dev/null +++ b/docs/wav_functions.md @@ -0,0 +1,3 @@ +# Surface Wave Spectra Functions Reference + +::: ion_functions.data.wav_functions \ No newline at end of file diff --git a/ion_functions/data/adcp_functions.py b/ion_functions/data/adcp_functions.py index 225e081..632b79e 100755 --- a/ion_functions/data/adcp_functions.py +++ b/ion_functions/data/adcp_functions.py @@ -1,128 +1,140 @@ #!/usr/bin/env python + +# @package ion_functions.data.adcp_functions +# @file ion_functions/data/adcp_functions.py +# @author Christopher Wingard, Russell Desiderio, Craig Risien +# @brief Module containing ADCP related data-calculations. + """ -@package ion_functions.data.adcp_functions -@file ion_functions/data/adcp_functions.py -@author Christopher Wingard, Russell Desiderio, Craig Risien -@brief Module containing ADCP related data-calculations. +Module containing ADCP related data-calculations. +This module implements the algorithms for calculating ADCP velocity profiles +and echo intensity from ADCP beam coordinate transformed velocity profiles. +This module also implements the algorithms for calculating ADCP velocity bin +depths for the pd0 and pd8 output formats. This module is used by the OOI +Cyberinfrastructure to calculate the L1 and L2 data products from the L0 data +products for the ADCP family of instruments. + +## Overview of functions +### For instruments programmed in beam coordinates: + (ADCPS-I,K; ADCPT-B,D,E) + +* adcp_beam_eastward -- calculates VELPROF-VLE_L1 +* adcp_beam_northward -- calculates VELPROF-VLN_L1 +* adcp_beam_vertical -- calculates VELPROF-VLU_L1 +* adcp_beam_error -- calculates VELPROF-ERR_L1 + +### For instruments programmed in earth coordinates: + (ADCPA; ADCPS-J,L,N; ADCPT-C,F,G,M) + +* adcp_earth_eastward -- calculates VELPROF-VLE_L1 +* adcp_earth_northward -- calculates VELPROF-VLN_L1 +* adcp_earth_vertical -- calculates VELPROF-VLU_L1 +* adcp_earth_error -- calculates VELPROF-ERR_L1 + +### For the VADCP programmed in beam coordinates: +* vadcp_beam_eastward -- calculates VELTURB-VLE_L1 +* vadcp_beam_northward -- calculates VELTURB-VLN_L1 +* vadcp_beam_vertical_true -- calculates VELTURB-VLU-5BM_L1 +* vadcp_beam_vertical_est -- calculates VELTURB-VLU-4BM_L1 +* vadcp_beam_error -- calculates VELTURB-ERR_L1 + +### For all tRDI ADCP instruments: +* adcp_backscatter -- calculates ECHOINT-B1_L1, ECHOINT-B2_L1, ECHOINT-B3_L1, ECHOINT-B4_L1. + +### Base functions used by above functions +* adcp_beam2ins -- applies the beam to instrument transform using either a 4 + or 3 beam solution for instruments programmed in beam coordinates +* adcp_ins2earth -- applies the instrument to Earth transform for all + instruments originally programmed in beam coordinates. +* magnetic_correction -- corrects horizontal velocities for the magnetic + variation (declination) at the measurement location. + +### Supplementary functions to calculate velocity bin depths: +* adcp_bin_depths -- calculates bin depths for the pd0 output format + (virtually all tRDI ADCPs deployed by OOI); uses + TEOS-10 functions p_from_z and enthalpy_SSO_0_p. +* adcp_bin_depths_pd8 -- calculates bin depths for the pd8 output format, + assuming that (1) the ADCP operator recorded the + necessary input variables and (2) these are somehow + entered into the CI system. """ + import numpy as np from ion_functions import deprecated -from ion_functions.data.generic_functions import magnetic_declination -from ion_functions.data.generic_functions import replace_fill_with_nan +from ion_functions.data.generic_functions import ( + magnetic_declination, + replace_fill_with_nan, +) # instrument fill value unprocessed by CI # (bad beam velocity sentinel output by tRDI ADCP instruments) ADCP_FILLVALUE = -32768 -""" - **** For instruments programmed in beam coordinates: - (ADCPS-I,K; ADCPT-B,D,E) - adcp_beam_eastward -- calculates VELPROF-VLE_L1 - adcp_beam_northward -- calculates VELPROF-VLN_L1 - adcp_beam_vertical -- calculates VELPROF-VLU_L1 - adcp_beam_error -- calculates VELPROF-ERR_L1 - - **** For instruments programmed in earth coordinates: - (ADCPA; ADCPS-J,L,N; ADCPT-C,F,G,M) - adcp_earth_eastward -- calculates VELPROF-VLE_L1 - adcp_earth_northward -- calculates VELPROF-VLN_L1 - adcp_earth_vertical -- calculates VELPROF-VLU_L1 - adcp_earth_error -- calculates VELPROF-ERR_L1 - - **** For the VADCP programmed in beam coordinates: - vadcp_beam_eastward -- calculates VELTURB-VLE_L1 - vadcp_beam_northward -- calculates VELTURB-VLN_L1 - vadcp_beam_vertical_true -- calculates VELTURB-VLU-5BM_L1 - vadcp_beam_vertical_est -- calculates VELTURB-VLU-4BM_L1 - vadcp_beam_error -- calculates VELTURB-ERR_L1 - - **** For all tRDI ADCP instruments: - adcp_backscatter -- calculates ECHOINT-B1_L1, - calculates ECHOINT-B2_L1, - calculates ECHOINT-B3_L1, - calculates ECHOINT-B4_L1. - - **** Base functions used by above functions - adcp_beam2ins -- applies the beam to instrument transform using either a 4 - or 3 beam solution for instruments programmed in beam coordinates - adcp_ins2earth -- applies the instrument to Earth transform for all - instruments originally programmed in beam coordinates. - magnetic_correction -- corrects horizontal velocities for the magnetic - variation (declination) at the measurement location. - - **** Supplementary functions to calculate velocity bin depths: - adcp_bin_depths -- calculates bin depths for the pd0 output format - (virtually all tRDI ADCPs deployed by OOI); uses - TEOS-10 functions p_from_z and enthalpy_SSO_0_p. - adcp_bin_depths_pd8 -- calculates bin depths for the pd8 output format, - assuming that (1) the ADCP operator recorded the - necessary input variables and (2) these are somehow - entered into the CI system. - -""" - def adcp_beam_velocity(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt): """ - Description: - - Compute Earth referenced velocity data from beam coordinate transformed velocity profiles as defined in the - Data Product Specification for Velocity Profile and Echo Intensity - DCN 1341-00750. - - Implemented by: - - 2013-04-10: Christopher Wingard. Initial code. - 2014-02-03: Christopher Wingard. Formatting and adjusting to use magnetic declination values calculated using - WMM 2010. - 2014-04-04: Russell Desiderio. Optimized code performance by replacing the for loops previously used to - calculate 2D and 3D vectorized coordinate transformations with calls to np.einsum (numpy Einstein - summation function). - 2014-06-25: Christopher Wingard. Edited to account for units of heading, pitch, roll and depth - 2015-06-10: Russell Desiderio. - (a) moved the conditioning of input beam velocities to adcp_beam2inst. - (b) moved the conditioning of compass readings to adcp_inst2earth. - (c) removed the depth dependence from the magnetic declination. - 2019-03-11: Christopher Wingard. Removed multiple wrapper functions and set this single function to stand-alone - returning all velocity components. Function can also be used for all VADCP processing with the - vertical velocity component representing an estimate of the vertical velocity. - 2023-08-15: Samuel Dahlberg. Brought over from original Pyseas code to bring in compatibility with CGSN. - - Usage: - - u, v, w, e = adcp_beam_velocity(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt) - - where - - u = east velocity profiles in Earth coordinates corrected for the magnetic declination [m s-1] - v = north velocity profiles in Earth coordinates corrected for the magnetic declination [m s-1] - w = vertical velocity profiles in Earth coordinates [m s-1] - e = error velocity profiles in Earth coordinates [m s-1] - - b1 = "beam 1" velocity profiles in beam coordinates [mm s-1] - b2 = "beam 2" velocity profiles in beam coordinates [mm s-1] - b3 = "beam 3" velocity profiles in beam coordinates [mm s-1] - b4 = "beam 4" velocity profiles in beam coordinates [mm s-1] - pg1 = percent good estimate for beam 1 [percent] - pg2 = percent good estimate for beam 2 [percent] - pg3 = percent good estimate for beam 3 [percent] - pg4 = percent good estimate for beam 4 [percent] - h = instrument's uncorrected magnetic heading [cdegrees] - p = instrument pitch [cdegrees] - r = instrument roll [cdegrees] - vf = instrument's vertical orientation (0 = downward looking and 1 = upward looking) - lat = instrument's deployment latitude [decimal degrees] - lon = instrument's deployment longitude [decimal degrees] - dt = sample date and time value [seconds since 1970-01-01] (Unix Time Format) - - References: - - OOI (2012). Data Product Specification for Velocity Profile and Echo Intensity. Document Control Number - 1341-00750. https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI >> Cyberinfrastructure >> - Data Product Specifications >> 1341-00750_Data_Product_SPEC_VELPROF_ECHOINT_OOI.pdf) - - OOI (2013). Data Product Specification for Turbulent Velocity Profile and Echo Intensity. Document Control - Number 1341-00760. https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI >> - Cyberinfrastructure >> Data Product Specifications >> 1341-00760_Data_Product_VELTURB_ECHOINT.pdf) + Compute Earth referenced velocity data from beam coordinate transformed velocity profiles. + + This function returns all velocity components in Earth coordinates, corrected for magnetic declination. + It can be used for all VADCP processing, with the vertical velocity component representing an estimate + of the vertical velocity. + + Parameters + ---------- + b1 : array_like + "beam 1" velocity profiles in beam coordinates [mm s-1]. + b2 : array_like + "beam 2" velocity profiles in beam coordinates [mm s-1]. + b3 : array_like + "beam 3" velocity profiles in beam coordinates [mm s-1]. + b4 : array_like + "beam 4" velocity profiles in beam coordinates [mm s-1]. + pg1 : float or array_like + Percent good estimate for beam 1 [%]. + pg2 : float or array_like + Percent good estimate for beam 2 [%]. + pg3 : float or array_like + Percent good estimate for beam 3 [%]. + pg4 : float or array_like + Percent good estimate for beam 4 [%]. + h : float or array_like + Instrument's uncorrected magnetic heading [cdegrees]. + p : float or array_like + Instrument pitch [cdegrees]. + r : float or array_like + Instrument roll [cdegrees]. + vf : int or array_like + Instrument's vertical orientation (0 = downward looking, 1 = upward looking). + lat : float or array_like + Instrument's deployment latitude [decimal degrees]. + lon : float or array_like + Instrument's deployment longitude [decimal degrees]. + dt : float or array_like + Sample date and time value [seconds since 1970-01-01] (Unix Time Format). + + Returns + ------- + u : ndarray + East velocity profiles in Earth coordinates, corrected for magnetic declination [m s-1]. + v : ndarray + North velocity profiles in Earth coordinates, corrected for magnetic declination [m s-1]. + w : ndarray + Vertical velocity profiles in Earth coordinates [m s-1]. + e : ndarray + Error velocity profiles in Earth coordinates [m s-1]. + + Examples + -------- + >>> u, v, w, e = adcp_beam_velocity(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt) + + Notes + ----- + Relies on the base functions [adcp_beam2ins][ion_functions.data.adcp_functions.adcp_beam2ins], [adcp_ins2earth][ion_functions.data.adcp_functions.adcp_ins2earth], and [magnetic_correction][ion_functions.data.adcp_functions.magnetic_correction]. + + References + ---------- + .. [1] OOI (2012). Data Product Specification for Velocity Profile and Echo Intensity. Document Control Number 1341-00750. + .. [2] OOI (2013). Data Product Specification for Turbulent Velocity Profile and Echo Intensity. Document Control Number 1341-00760. """ # force shapes of inputs to arrays of the correct dimensions lat = np.atleast_1d(lat) @@ -155,61 +167,52 @@ def adcp_beam_velocity(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon # programmed in beam coordinates by RSN (ADCPS-I,K and ADCPT-B,D,E) def adcp_beam_eastward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt): """ - Description: - - Wrapper function to compute the Eastward Velocity Profile (VELPROF-VLE) - from beam coordinate transformed velocity profiles as defined in the - Data Product Specification for Velocity Profile and Echo Intensity - - DCN 1341-00750. - - Implemented by: - - 2013-04-10: Christopher Wingard. Initial code. - 2014-02-03: Christopher Wingard. Formatting and adjusting to use - magnetic declination values calculated use the WMM 2010. - 2014-04-04: Russell Desiderio. Optimized code performance by replacing - the for loops previously used to calculate 2D and 3D - vectorized coordinate transformations with calls to - np.einsum (numpy Einstein summation function). - 2014-06-25: Christopher Wingard. Edited to account for units of - heading, pitch, roll and depth - 2015-06-10: Russell Desiderio. - (a) moved the conditioning of input beam velocities to adcp_beam2inst. - (b) moved the conditioning of compass readings to adcp_inst2earth. - (c) removed the depth dependence from the magnetic declination. - 2019-08-13: Christopher Wingard. Adds functionality to compute a 3-beam solution - and cleans up syntax used in the function. - 2023-08-15: Samuel Dahlberg. - (a) Moved all adcp velocity processing to new adcp_beam_velocity function, turning - adcp_beam_eastward into a wrapper function that calls adcp_beam_velocity. - (b) converts inputted ntp epoch timestamp into unix epoch timestamp for compatibility with - adcp_beam_velocity. - - Usage: - - u_cor = adcp_beam_eastward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt) - - where - - u_cor = eastward velocity profiles in Earth coordinates corrected for the - magnetic declination (VELPROF-VLE_L1) [m s-1] - - b1 = beam 1 velocity profiles in beam coordinates (VELPROF-B1_L0) [mm s-1] - b2 = beam 2 velocity profiles in beam coordinates (VELPROF-B2_L0) [mm s-1] - b3 = beam 3 velocity profiles in beam coordinates (VELPROF-B3_L0) [mm s-1] - b4 = beam 4 velocity profiles in beam coordinates (VELPROF-B4_L0) [mm s-1] - pg1 = percent good estimate for beam 1 [percent] - pg2 = percent good estimate for beam 2 [percent] - pg3 = percent good estimate for beam 3 [percent] - pg4 = percent good estimate for beam 4 [percent] - h = instrument's uncorrected magnetic heading [cdegrees] - p = instrument pitch [cdegrees] - r = instrument roll [cdegrees] - vf = instrument's vertical orientation (0 = downward looking and - 1 = upward looking) - lat = instrument's deployment latitude [decimal degrees] - lon = instrument's deployment longitude [decimal degrees] - dt = sample date and time value [seconds since 1900-01-01] (NTP Time Format) + Wrapper function to compute the Eastward Velocity Profile (VELPROF-VLE) + from beam coordinate transformed velocity profiles. + + Parameters + ---------- + b1 : array_like + "beam 1" velocity profiles in beam coordinates (VELPROF-B1_L0) [mm s-1]. + b2 : array_like + "beam 2" velocity profiles in beam coordinates (VELPROF-B2_L0) [mm s-1]. + b3 : array_like + "beam 3" velocity profiles in beam coordinates (VELPROF-B3_L0) [mm s-1]. + b4 : array_like + "beam 4" velocity profiles in beam coordinates (VELPROF-B4_L0) [mm s-1]. + pg1 : float or array_like + Percent good estimate for beam 1 [%]. + pg2 : float or array_like + Percent good estimate for beam 2 [%]. + pg3 : float or array_like + Percent good estimate for beam 3 [%]. + pg4 : float or array_like + Percent good estimate for beam 4 [%]. + h : float or array_like + Instrument's uncorrected magnetic heading [cdegrees] + p : float or array_like + Instrument pitch [cdegrees] + r : float or array_like + Instrument roll [cdegrees] + vf : int or array_like + Instrument's vertical orientation (0 = downward looking, 1 = upward looking) + lat : float or array_like + Instrument's deployment latitude [decimal degrees] + lon : float or array_like + Instrument's deployment longitude [decimal degrees] + dt : float or array_like + Sample date and time value [seconds since 1900-01-01] (NTP Time Format) + + Notes + ----- + Uses the [adcp_beam_velocity][ion_functions.data.adcp_functions.adcp_beam_velocity] + function to compute the eastward velocity component. + + Returns + ------- + u_cor : array_like + Eastward velocity profiles in Earth coordinates corrected for the + magnetic declination (VELPROF-VLE_L1) [m s-1] """ # Convert the given ntp epoch timestamp in unix epoch timestamp. @@ -224,62 +227,52 @@ def adcp_beam_eastward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon def adcp_beam_northward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt): """ - Description: - - Wrapper function to compute the Northward Velocity Profile (VELPROF-VLN) - from beam coordinate transformed velocity profiles as defined in the - Data Product Specification for Velocity Profile and Echo Intensity - - DCN 1341-00750. - - Implemented by: - - 2013-04-10: Christopher Wingard. Initial code. - 2014-02-03: Christopher Wingard. Formatting and adjusting to use - magnetic declination values calculated use the WMM 2010. - 2014-03-28: Russell Desiderio. Corrected documentation only. - 2014-04-04: Russell Desiderio. Optimized code performance by replacing - the for loops previously used to calculate 2D and 3D - vectorized coordinate transformations with calls to - np.einsum (numpy Einstein summation function). - 2014-06-25: Christopher Wingard. Edited to account for units of - heading, pitch, roll and depth - 2015-06-10: Russell Desiderio. - (a) moved the conditioning of input beam velocities to adcp_beam2inst. - (b) moved the conditioning of compass readings to adcp_inst2earth. - (c) removed the depth dependence from the magnetic declination. - 2019-08-13: Christopher Wingard. Adds functionality to compute a 3-beam solution - and cleans up syntax used in the function. - 2023-08-15: Samuel Dahlberg. - (a) Moved all adcp velocity processing to new adcp_beam_velocity function, turning - adcp_beam_northward into a wrapper function that calls adcp_beam_velocity. - (b) converts inputted ntp epoch timestamp into unix epoch timestamp for compatibility with - adcp_beam_velocity. - - Usage: - - v_cor = adcp_beam_northward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt) - - where - - v_cor = northward velocity profiles in Earth coordinates corrected for the - magnetic declination (VELPROF-VLN_L1) [m s-1] - - b1 = beam 1 velocity profiles in beam coordinates (VELPROF-B1_L0) [mm s-1] - b2 = beam 2 velocity profiles in beam coordinates (VELPROF-B2_L0) [mm s-1] - b3 = beam 3 velocity profiles in beam coordinates (VELPROF-B3_L0) [mm s-1] - b4 = beam 4 velocity profiles in beam coordinates (VELPROF-B4_L0) [mm s-1] - pg1 = percent good estimate for beam 1 [percent] - pg2 = percent good estimate for beam 2 [percent] - pg3 = percent good estimate for beam 3 [percent] - pg4 = percent good estimate for beam 4 [percent] - h = instrument's uncorrected magnetic heading [cdegrees] - p = instrument pitch [cdegrees] - r = instrument roll [cdegrees] - vf = instrument's vertical orientation (0 = downward looking and - 1 = upward looking) - lat = instrument's deployment latitude [decimal degrees] - lon = instrument's deployment longitude [decimal degrees] - dt = sample date and time value [seconds since 1900-01-01] (NTP Time Format) + Wrapper function to compute the Northward Velocity Profile (VELPROF-VLN) + from beam coordinate transformed velocity profiles. + + Parameters + ---------- + b1 : array_like + "beam 1" velocity profiles in beam coordinates (VELPROF-B1_L0) [mm s-1]. + b2 : array_like + "beam 2" velocity profiles in beam coordinates (VELPROF-B2_L0) [mm s-1]. + b3 : array_like + "beam 3" velocity profiles in beam coordinates (VELPROF-B3_L0) [mm s-1]. + b4 : array_like + "beam 4" velocity profiles in beam coordinates (VELPROF-B4_L0) [mm s-1]. + pg1 : float or array_like + Percent good estimate for beam 1 [%]. + pg2 : float or array_like + Percent good estimate for beam 2 [%]. + pg3 : float or array_like + Percent good estimate for beam 3 [%]. + pg4 : float or array_like + Percent good estimate for beam 4 [%]. + h : float or array_like + Instrument's uncorrected magnetic heading [cdegrees] + p : float or array_like + Instrument pitch [cdegrees] + r : float or array_like + Instrument roll [cdegrees] + vf : int or array_like + Instrument's vertical orientation (0 = downward looking, 1 = upward looking) + lat : float or array_like + Instrument's deployment latitude [decimal degrees] + lon : float or array_like + Instrument's deployment longitude [decimal degrees] + dt : float or array_like + Sample date and time value [seconds since 1900-01-01] (NTP Time Format) + + Notes + ----- + Uses the [adcp_beam_velocity][ion_functions.data.adcp_functions.adcp_beam_velocity] + function to compute the northward velocity component. + + Returns + ------- + v_cor : array_like + Northward velocity profiles in Earth coordinates corrected for the + magnetic declination (VELPROF-VLN_L1) [m s-1] """ # Convert the given ntp epoch timestamp in unix epoch timestamp. @@ -294,51 +287,40 @@ def adcp_beam_northward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lo def adcp_beam_vertical(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf): """ - Description: - - Wrapper function to compute the Upward Velocity Profile (VELPROF-VLU) - from beam coordinate transformed velocity profiles as defined in the - Data Product Specification for Velocity Profile and Echo Intensity - - DCN 1341-00750. - - Implemented by: - - 2013-04-10: Christopher Wingard. Initial code. - 2014-02-03: Christopher Wingard. Formatting and adjusting to use - magnetic declination values calculated using the WMM 2010. - 2014-04-04: Russell Desiderio. Optimized code performance by replacing - the for loops previously used to calculate 2D and 3D - vectorized coordinate transformations with calls to - np.einsum (numpy Einstein summation function). - 2014-06-25: Christopher Wingard. Edited to account for units of - heading, pitch, roll and depth - 2015-06-10: Russell Desiderio. - (a) moved the conditioning of input beam velocities to adcp_beam2inst. - (b) moved the conditioning of compass readings to adcp_inst2earth. - 2019-08-13: Christopher Wingard. Adds functionality to compute a 3-beam solution - and cleans up syntax used in the function. - - Usage: - - w = adcp_beam_vertical(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf) - - where - - w = vertical velocity profiles (VELPROF-VLU_L1) [m s-1] - - b1 = beam 1 velocity profiles in beam coordinates (VELPROF-B1_L0) [mm s-1] - b2 = beam 2 velocity profiles in beam coordinates (VELPROF-B2_L0) [mm s-1] - b3 = beam 3 velocity profiles in beam coordinates (VELPROF-B3_L0) [mm s-1] - b4 = beam 4 velocity profiles in beam coordinates (VELPROF-B4_L0) [mm s-1] - pg1 = percent good estimate for beam 1 [percent] - pg2 = percent good estimate for beam 2 [percent] - pg3 = percent good estimate for beam 3 [percent] - pg4 = percent good estimate for beam 4 [percent] - h = instrument's uncorrected magnetic heading [cdegrees] - p = instrument pitch [cdegrees] - r = instrument roll [cdegrees] - vf = instrument's vertical orientation (0 = downward looking and - 1 = upward looking) + Wrapper function to compute the Upward Velocity Profile (VELPROF-VLU) + from beam coordinate transformed velocity profiles. + + Parameters + ---------- + b1 : array_like + "beam 1" velocity profiles in beam coordinates (VELPROF-B1_L0) [mm s-1]. + b2 : array_like + "beam 2" velocity profiles in beam coordinates (VELPROF-B2_L0) [mm s-1]. + b3 : array_like + "beam 3" velocity profiles in beam coordinates (VELPROF-B3_L0) [mm s-1]. + b4 : array_like + "beam 4" velocity profiles in beam coordinates (VELPROF-B4_L0) [mm s-1]. + pg1 : float or array_like + Percent good estimate for beam 1 [%]. + pg2 : float or array_like + Percent good estimate for beam 2 [%]. + pg3 : float or array_like + Percent good estimate for beam 3 [%]. + pg4 : float or array_like + Percent good estimate for beam 4 [%]. + h : float or array_like + Instrument's uncorrected magnetic heading [cdegrees] + p : float or array_like + Instrument pitch [cdegrees] + r : float or array_like + Instrument roll [cdegrees] + vf : int or array_like + Instrument's vertical orientation (0 = downward looking, 1 = upward looking) + + Returns + ------- + w : array_like + Vertical velocity profiles (VELPROF-VLU_L1) [m s-1] """ # compute the beam to instrument transform x, y, z, _ = adcp_beam2ins(b1, b2, b3, b4, pg1, pg2, pg3, pg4) @@ -355,37 +337,32 @@ def adcp_beam_vertical(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf): def adcp_beam_error(b1, b2, b3, b4, pg1, pg2, pg3, pg4): """ - Description: - - Wrapper function to compute the Error Velocity Profile (VELPROF-ERR) - from beam coordinate transformed velocity profiles as defined in the - Data Product Specification for Velocity Profile and Echo Intensity - - DCN 1341-00750. - - Implemented by: - - 2013-04-10: Christopher Wingard. Initial code. - 2015-06-10: Russell Desiderio. - Moved the conditioning of input beam velocities to adcp_beam2inst. - 2019-08-13: Christopher Wingard. Adds functionality to compute a 3-beam solution - and cleans up syntax used in the function. - - Usage: + Wrapper function to compute the Error Velocity Profile (VELPROF-ERR) + from beam coordinate transformed velocity profiles. - e = adcp_beam_error(b1, b2, b3, b4, pg1, pg2, pg3, pg4) - - where - - e = error velocity profiles (VELPROF-ERR_L1) [m s-1] + Parameters + ---------- + b1 : array_like + beam 1 velocity profiles in beam coordinates (VELPROF-B1_L0) [mm s-1]. + b2 : array_like + beam 2 velocity profiles in beam coordinates (VELPROF-B2_L0) [mm s-1]. + b3 : array_like + beam 3 velocity profiles in beam coordinates (VELPROF-B3_L0) [mm s-1]. + b4 : array_like + beam 4 velocity profiles in beam coordinates (VELPROF-B4_L0) [mm s-1]. + pg1 : float or array_like + Percent good estimate for beam 1 [%]. + pg2 : float or array_like + Percent good estimate for beam 2 [%]. + pg3 : float or array_like + Percent good estimate for beam 3 [%]. + pg4 : float or array_like + Percent good estimate for beam 4 [%]. - b1 = beam 1 velocity profiles in beam coordinates (VELPROF-B1_L0) [mm s-1] - b2 = beam 2 velocity profiles in beam coordinates (VELPROF-B2_L0) [mm s-1] - b3 = beam 3 velocity profiles in beam coordinates (VELPROF-B3_L0) [mm s-1] - b4 = beam 4 velocity profiles in beam coordinates (VELPROF-B4_L0) [mm s-1] - pg1 = percent good estimate for beam 1 [percent] - pg2 = percent good estimate for beam 2 [percent] - pg3 = percent good estimate for beam 3 [percent] - pg4 = percent good estimate for beam 4 [percent] + Returns + ------- + e : array_like + Error velocity profiles (VELPROF-ERR_L1) [m s-1] """ # compute the beam to instrument transform _, _, _, e = adcp_beam2ins(b1, b2, b3, b4, pg1, pg2, pg3, pg4) @@ -402,43 +379,29 @@ def adcp_beam_error(b1, b2, b3, b4, pg1, pg2, pg3, pg4): # ADCPS-J,L,N and ADCPT-C,F,G,M) def adcp_earth_eastward(u, v, z, lat, lon, dt): """ - Description: - - Wrapper function to compute the Eastward Velocity Profile (VELPROF-VLE) - from Earth coordinate transformed velocity profiles as defined in the - Data Product Specification for Velocity Profile and Echo Intensity - - DCN 1341-00750. - - Implemented by: - - 2013-04-10: Christopher Wingard. Initial code. - 2014-02-03: Christopher Wingard. Formatting and adjusting to use - magnetic declination values calculated use the WMM 2010. - 2014-04-04: Russell Desiderio. Optimized code performance by replacing - the for loops previously used to calculate 2D and 3D - vectorized coordinate transformations with calls to - np.einsum (numpy Einstein summation function). - 2014-06-25: Christopher Wingard. Edited to account for units of - heading, pitch, roll and depth - 2015-06-10: Russell Desiderio. - Removed the depth dependence from the magnetic declination. - 2015-06-25: Russell Desiderio. Incorporated int fillvalue -> Nan. - - Usage: - - uu_cor = adcp_earth_eastward(u, v, z, lat, lon, dt) - - where - - uu_cor = eastward velocity profiles in Earth coordinates corrected for - the magnetic declination (VELPROF-VLE_L1) [m s-1] - - u = Eastward velocity profiles (VELPROF-VLE_L0) [mm s-1] - v = Northward velocity profiles (VELPROF-VLN_L0) [mm s-1] - z = instrument's pressure sensor reading (depth) [daPa] - lat = instrument's deployment latitude [decimal degrees] - lon = instrument's deployment longitude [decimal degrees] - dt = sample date and time value [seconds since 1900-01-01] + Wrapper function to compute the Eastward Velocity Profile (VELPROF-VLE) + from Earth coordinate transformed velocity profiles. + + Parameters + ---------- + u : array_like + Eastward velocity profiles (VELPROF-VLE_L0) [mm s-1] + v : array_like + Northward velocity profiles (VELPROF-VLN_L0) [mm s-1] + z : array_like + Instrument's pressure sensor reading (depth) [daPa] + lat : float or array_like + Instrument's deployment latitude [decimal degrees] + lon : float or array_like + Instrument's deployment longitude [decimal degrees] + dt : float or array_like + Sample date and time value [seconds since 1900-01-01] + + Returns + ------- + uu_cor : array_like + Eastward velocity profiles in Earth coordinates corrected for the + magnetic declination (VELPROF-VLE_L1) [m s-1] """ # force shapes of inputs to arrays u = np.atleast_2d(u) @@ -468,43 +431,29 @@ def adcp_earth_eastward(u, v, z, lat, lon, dt): def adcp_earth_northward(u, v, z, lat, lon, dt): """ - Description: - - Wrapper function to compute the Northward Velocity Profile (VELPROF-VLN) - from Earth coordinate transformed velocity profiles as defined in the - Data Product Specification for Velocity Profile and Echo Intensity - - DCN 1341-00750. - - Implemented by: - - 2013-04-10: Christopher Wingard. Initial code. - 2014-02-03: Christopher Wingard. Formatting and adjusting to use - magnetic declination values calculated use the WMM 2010. - 2014-04-04: Russell Desiderio. Optimized code performance by replacing - the for loops previously used to calculate 2D and 3D - vectorized coordinate transformations with calls to - np.einsum (numpy Einstein summation function). - 2014-06-25: Christopher Wingard. Edited to account for units of - heading, pitch, roll and depth - 2015-06-10: Russell Desiderio. - Removed the depth dependence from the magnetic declination. - 2015-06-25: Russell Desiderio. Incorporated int fillvalue -> Nan. - - Usage: - - vv_cor = adcp_earth_northward(u, v, z, lat, lon, dt) - - where - - vv_cor = northward velocity profiles in Earth coordinates corrected for - the magnetic declination (VELPROF-VLN_L1) [m s-1] - - u = Eastward velocity profiles (VELPROF-VLE_L0) [mm s-1] - v = Northward velocity profiles (VELPROF-VLN_L0) [mm s-1] - z = instrument's pressure sensor reading (depth) [daPa] - lat = instrument's deployment latitude [decimal degrees] - lon = instrument's deployment longitude [decimal degrees] - dt = sample date and time value [seconds since 1900-01-01] + Wrapper function to compute the Northward Velocity Profile (VELPROF-VLN) + from Earth coordinate transformed velocity profiles. + + Parameters + ---------- + u : array_like + Eastward velocity profiles (VELPROF-VLE_L0) [mm s-1] + v : array_like + Northward velocity profiles (VELPROF-VLN_L0) [mm s-1] + z : array_like + Instrument's pressure sensor reading (depth) [daPa] + lat : float or array_like + Instrument's deployment latitude [decimal degrees] + lon : float or array_like + Instrument's deployment longitude [decimal degrees] + dt : float or array_like + Sample date and time value [seconds since 1900-01-01] + + Returns + ------- + vv_cor : array_like + Northward velocity profiles in Earth coordinates corrected for the + magnetic declination (VELPROF-VLN_L1) [m s-1] """ # force shapes of inputs to arrays u = np.atleast_2d(u) @@ -534,28 +483,18 @@ def adcp_earth_northward(u, v, z, lat, lon, dt): def adcp_earth_vertical(w): """ - Description: + Wrapper function to compute the Upward Velocity Profile (VELPROF-VLU) + from Earth coordinate transformed velocity profiles. - Wrapper function to compute the Upward Velocity Profile (VELPROF-VLU) - from Earth coordinate transformed velocity profiles as defined in the - Data Product Specification for Velocity Profile and Echo Intensity - - DCN 1341-00750. - - Implemented by: - - 2014-06-25: Christopher Wingard. Initial code. - 2015-06-25: Russell Desiderio. Incorporated int fillvalue -> Nan. - - Usage: - - w_scl = adcp_earth_vertical(w) - - where - - w_scl = scaled upward velocity profiles in Earth coordinates - (VELPROF-VLN_L1) [m s-1] + Parameters + ---------- + w : array_like + Upward velocity profiles (VELPROF-VLU_L0) [mm s-1] - w = upward velocity profiles (VELPROF-VLU_L0) [mm s-1] + Returns + ------- + w_scl : array_like + Scaled upward velocity profiles in Earth coordinates (VELPROF-VLN_L1) [m s-1] """ w = replace_fill_with_nan(ADCP_FILLVALUE, w) @@ -568,28 +507,18 @@ def adcp_earth_vertical(w): def adcp_earth_error(e): """ - Description: - - Wrapper function to compute the Error Velocity Profile (VELPROF-ERR) - from Earth coordinate transformed velocity profiles as defined in the - Data Product Specification for Velocity Profile and Echo Intensity - - DCN 1341-00750. - - Implemented by: - - 2014-06-25: Christopher Wingard. Initial code. - 2015-06-25: Russell Desiderio. Incorporated int fillvalue -> Nan. - - Usage: + Wrapper function to compute the Error Velocity Profile (VELPROF-ERR) + from Earth coordinate transformed velocity profiles. - e_scl = adcp_earth_vertical(w) - - where - - e_scl = scaled error velocity profiles in Earth coordinates - (VELPROF-ERR_L1) [m s-1] + Parameters + ---------- + e : array_like + Error velocity profiles (VELPROF-ERR_L0) [mm s-1] - e = error velocity profiles (VELPROF-ERR_L0) [mm s-1] + Returns + ------- + e_scl : array_like + Scaled error velocity profiles in Earth coordinates (VELPROF-ERR_L1) [m s-1] """ e = replace_fill_with_nan(ADCP_FILLVALUE, e) @@ -604,48 +533,59 @@ def adcp_earth_error(e): @deprecated def vadcp_beam_eastward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt): """ - Description: - - Wrapper function to compute the Eastward Velocity Profile (VELTURB-VLE) - from beam coordinate transformed velocity profiles as defined in the - Data Product Specification for Turbulent Velocity Profile and Echo Intensity - - DCN 1341-00760. - - Implemented by: - - 2014-06-25: Christopher Wingard. Initial code, based on existing ADCP - 2015-06-10: Russell Desiderio. - (a) moved the conditioning of input beam velocities to adcp_beam2inst. - (b) moved the conditioning of compass readings to adcp_inst2earth. - (c) removed the depth dependence from the magnetic declination. - 2019-08-13: Christopher Wingard. Adds functionality to compute a 3-beam solution - and cleans up syntax used in the function. - - Usage: - - u_cor = vadcp_beam_eastward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt) - - where - - u_cor = eastward velocity profiles in Earth coordinates corrected for the - magnetic declination (VELTURB-VLE_L1) [m s-1] - - b1 = beam 1 velocity profiles in beam coordinates (VELTURB-B1_L0) [mm s-1] - b2 = beam 2 velocity profiles in beam coordinates (VELTURB-B2_L0) [mm s-1] - b3 = beam 3 velocity profiles in beam coordinates (VELTURB-B3_L0) [mm s-1] - b4 = beam 4 velocity profiles in beam coordinates (VELTURB-B4_L0) [mm s-1] - pg1 = percent good estimate for beam 1 [percent] - pg2 = percent good estimate for beam 2 [percent] - pg3 = percent good estimate for beam 3 [percent] - pg4 = percent good estimate for beam 4 [percent] - h = instrument's uncorrected magnetic heading [cdegrees] - p = instrument pitch [cdegrees] - r = instrument roll [cdegrees] - vf = instrument's vertical orientation (0 = downward looking and - 1 = upward looking) - lat = instrument's deployment latitude [decimal degrees] - lon = instrument's deployment longitude [decimal degrees] - dt = sample date and time value [seconds since 1900-01-01] + Wrapper function to compute the Eastward Velocity Profile (VELTURB-VLE) + from beam coordinate transformed velocity profiles. + + Parameters + ---------- + b1 : array_like + Beam 1 velocity profiles in beam coordinates (VELTURB-B1_L0) [mm s-1]. + b2 : array_like + Beam 2 velocity profiles in beam coordinates (VELTURB-B2_L0) [mm s-1]. + b3 : array_like + Beam 3 velocity profiles in beam coordinates (VELTURB-B3_L0) [mm s-1]. + b4 : array_like + Beam 4 velocity profiles in beam coordinates (VELTURB-B4_L0) [mm s-1]. + pg1 : array_like + Percent good estimate for beam 1 [percent]. + pg2 : array_like + Percent good estimate for beam 2 [percent]. + pg3 : array_like + Percent good estimate for beam 3 [percent]. + pg4 : array_like + Percent good estimate for beam 4 [percent]. + h : array_like + Instrument's uncorrected magnetic heading [cdegrees]. + p : array_like + Instrument pitch [cdegrees]. + r : array_like + Instrument roll [cdegrees]. + vf : array_like or int + Instrument's vertical orientation (0 = downward looking, 1 = upward looking). + lat : array_like + Instrument's deployment latitude [decimal degrees]. + lon : array_like + Instrument's deployment longitude [decimal degrees]. + dt : array_like + Sample date and time value [seconds since 1900-01-01]. + + Returns + ------- + u_cor : ndarray + Eastward velocity profiles in Earth coordinates corrected for the + magnetic declination (VELTURB-VLE_L1) [m s-1]. + + Notes + ----- + - Input velocities are expected in mm/s and output is in m/s. + + References + ---------- + - Data Product Specification for Turbulent Velocity Profile and Echo Intensity - DCN 1341-00760. + + Examples + -------- + >>> u_cor = vadcp_beam_eastward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt) """ # force shapes of some inputs to arrays of the correct dimensions lat = np.atleast_1d(lat) @@ -674,48 +614,58 @@ def vadcp_beam_eastward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lo @deprecated def vadcp_beam_northward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt): """ - Description: - - Wrapper function to compute the Northward Velocity Profile - (VELTURB-VLN) from beam coordinate transformed velocity profiles as - defined in the Data Product Specification for Turbulent Velocity - Profile and Echo Intensity - DCN 1341-00760. - - Implemented by: - - 2014-06-25: Christopher Wingard. Initial code, based on existing ADCP - 2015-06-10: Russell Desiderio. - (a) moved the conditioning of input beam velocities to adcp_beam2inst. - (b) moved the conditioning of compass readings to adcp_inst2earth. - (c) removed the depth dependence from the magnetic declination. - 2019-08-13: Christopher Wingard. Adds functionality to compute a 3-beam solution - and cleans up syntax used in the function. - - Usage: - - v_cor = vadcp_beam_northward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt) - - where - - v_cor = northward velocity profiles in Earth coordinates corrected for the - magnetic declination (VELTURB-VLN_L1) [m s-1] - - b1 = beam 1 velocity profiles in beam coordinates (VELTURB-B1_L0) [mm s-1] - b2 = beam 2 velocity profiles in beam coordinates (VELTURB-B2_L0) [mm s-1] - b3 = beam 3 velocity profiles in beam coordinates (VELTURB-B3_L0) [mm s-1] - b4 = beam 4 velocity profiles in beam coordinates (VELTURB-B4_L0) [mm s-1] - pg1 = percent good estimate for beam 1 [percent] - pg2 = percent good estimate for beam 2 [percent] - pg3 = percent good estimate for beam 3 [percent] - pg4 = percent good estimate for beam 4 [percent] - h = instrument's uncorrected magnetic heading [cdegrees] - p = instrument pitch [cdegrees] - r = instrument roll [cdegrees] - vf = instrument's vertical orientation (0 = downward looking and - 1 = upward looking) - lat = instrument's deployment latitude [decimal degrees] - lon = instrument's deployment longitude [decimal degrees] - dt = sample date and time value [seconds since 1900-01-01] + Wrapper function to compute the Northward Velocity Profile (VELTURB-VLN) + from beam coordinate transformed velocity profiles. + + Parameters + ---------- + b1 : array_like + Beam 1 velocity profiles in beam coordinates (VELTURB-B1_L0) [mm s-1]. + b2 : array_like + Beam 2 velocity profiles in beam coordinates (VELTURB-B2_L0) [mm s-1]. + b3 : array_like + Beam 3 velocity profiles in beam coordinates (VELTURB-B3_L0) [mm s-1]. + b4 : array_like + Beam 4 velocity profiles in beam coordinates (VELTURB-B4_L0) [mm s-1]. + pg1 : array_like + Percent good estimate for beam 1 [percent]. + pg2 : array_like + Percent good estimate for beam 2 [percent]. + pg3 : array_like + Percent good estimate for beam 3 [percent]. + pg4 : array_like + Percent good estimate for beam 4 [percent]. + h : array_like + Instrument's uncorrected magnetic heading [cdegrees]. + p : array_like + Instrument pitch [cdegrees]. + r : array_like + Instrument roll [cdegrees]. + vf : array_like or int + Instrument's vertical orientation (0 = downward looking, 1 = upward looking). + lat : array_like + Instrument's deployment latitude [decimal degrees]. + lon : array_like + Instrument's deployment longitude [decimal degrees]. + dt : array_like + Sample date and time value [seconds since 1900-01-01]. + + Returns + ------- + v_cor : ndarray + Northward velocity profiles in Earth coordinates corrected for the magnetic declination (VELTURB-VLN_L1) [m s-1]. + + Notes + ----- + - Input velocities are expected in mm/s and output is in m/s. + + References + ---------- + - Data Product Specification for Turbulent Velocity Profile and Echo Intensity - DCN 1341-00760. + + Examples + -------- + >>> v_cor = vadcp_beam_northward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, lon, dt) """ # force shapes of some inputs to arrays of the correct dimensions lat = np.atleast_1d(lat) @@ -743,48 +693,50 @@ def vadcp_beam_northward(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf, lat, l def vadcp_beam_vertical_est(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf): """ - Description: - - Wrapper function to compute the "estimated" Upward Velocity Profile - (VELTURB-VLU-4BM) from the beam coordinate transformed velocity profiles as - defined in the Data Product Specification for Turbulent Velocity - Profile and Echo Intensity - DCN 1341-00760. This provides the - traditional estimate of the vertical velocity component from a 4 or 3 beam - solution, where each beam is facing outward at an angle (20 degrees) - relative to the vertical. - - Implemented by: - - 2014-06-25: Christopher Wingard. Initial code, based on existing ADCP - 2015-06-10: Russell Desiderio. - (a) moved the conditioning of input beam velocities to adcp_beam2inst. - (b) moved the conditioning of compass readings to adcp_inst2earth. - 2015-06-22: Russell Desiderio. Renamed this data product. - 2019-08-13: Christopher Wingard. Adds functionality to compute a 3-beam solution - and cleans up syntax used in the function. - - Usage: - - w = vadcp_beam_vertical_est(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf) - - where - - w = estimated vertical velocity profiles in Earth coordinates - (VELTURB-VLU-4BM_L1) [m s-1] - - b1 = beam 1 velocity profiles in beam coordinates (VELTURB-B1_L0) [mm s-1] - b2 = beam 2 velocity profiles in beam coordinates (VELTURB-B2_L0) [mm s-1] - b3 = beam 3 velocity profiles in beam coordinates (VELTURB-B3_L0) [mm s-1] - b4 = beam 4 velocity profiles in beam coordinates (VELTURB-B4_L0) [mm s-1] - pg1 = percent good estimate for beam 1 [percent] - pg2 = percent good estimate for beam 2 [percent] - pg3 = percent good estimate for beam 3 [percent] - pg4 = percent good estimate for beam 4 [percent] - h = instrument's uncorrected magnetic heading [cdegrees] - p = instrument pitch [cdegrees] - r = instrument roll [cdegrees] - vf = instrument's vertical orientation (0 = downward looking and - 1 = upward looking) + Wrapper function to compute the estimated upward velocity profile + (VELTURB-VLU-4BM) from beam coordinate transformed velocity profiles + using a 4- or 3-beam solution, where each beam is oriented facing outward + at 20 degrees relative to vertical. + + Parameters + ---------- + b1 : array_like + Beam 1 velocity profiles in beam coordinates (VELTURB-B1_L0) [mm s-1]. + b2 : array_like + Beam 2 velocity profiles in beam coordinates (VELTURB-B2_L0) [mm s-1]. + b3 : array_like + Beam 3 velocity profiles in beam coordinates (VELTURB-B3_L0) [mm s-1]. + b4 : array_like + Beam 4 velocity profiles in beam coordinates (VELTURB-B4_L0) [mm s-1]. + pg1 : array_like + Percent good estimate for beam 1 [percent]. + pg2 : array_like + Percent good estimate for beam 2 [percent]. + pg3 : array_like + Percent good estimate for beam 3 [percent]. + pg4 : array_like + Percent good estimate for beam 4 [percent]. + h : array_like + Instrument's uncorrected magnetic heading [cdegrees]. + p : array_like + Instrument pitch [cdegrees]. + r : array_like + Instrument roll [cdegrees]. + vf : array_like or int + Instrument's vertical orientation (0 = downward looking, 1 = upward looking). + + Returns + ------- + w : ndarray + Estimated vertical velocity profiles in Earth coordinates (VELTURB-VLU-4BM_L1) [m s-1]. + + Notes + ----- + - Input velocities are expected in mm/s and output is in m/s. + + References + ---------- + Data Product Specification for Turbulent Velocity Profile and Echo Intensity - DCN 1341-00760. """ # compute the beam to instrument transform x, y, z, _ = adcp_beam2ins(b1, b2, b3, b4, pg1, pg2, pg3, pg4) @@ -800,49 +752,52 @@ def vadcp_beam_vertical_est(b1, b2, b3, b4, pg1, pg2, pg3, pg4, h, p, r, vf): def vadcp_beam_vertical_true(b1, b2, b3, b4, b5, pg1, pg2, pg3, pg4, pg5, h, p, r, vf): - """ - Description: - - Computes the "true" Upward Velocity Profile (VELTURB-VLU-5BM) from the beam - coordinate transformed velocity profiles as defined in the Data Product - Specification for Turbulent Velocity Profile and Echo Intensity - DCN 1341-00760. - This is assumed to provide a better estimate of the true vertical velocity component, - since beam 5 is pointing directly up. - - Implemented by: - - 2014-06-25: Christopher Wingard. Initial code, based on existing ADCP - 2015-06-10: Russell Desiderio. - (a) moved the conditioning of input beam velocities to adcp_beam2inst. - (b) moved the conditioning of compass readings to adcp_inst2earth. - 2015-06-22: Russell Desiderio. Renamed this data product. - 2015-06-25: Russell Desiderio. Incorporated b5 int fillvalue -> Nan. - 2019-08-13: Christopher Wingard. Adds functionality to compute a 3-beam solution - and cleans up syntax used in the function. - - Usage: - - w = vadcp_beam_vertical_true(b1, b2, b3, b4, b5, pg1, pg2, pg3, pg4, pg5, h, p, r, vf) - - where - - w = true vertical velocity profiles in Earth coordinates (VELTURB-VLU-5BM_L1) [m s-1] - - b1 = beam 1 velocity profiles in beam coordinates (VELTURB-B1_L0) [mm s-1] - b2 = beam 2 velocity profiles in beam coordinates (VELTURB-B2_L0) [mm s-1] - b3 = beam 3 velocity profiles in beam coordinates (VELTURB-B3_L0) [mm s-1] - b4 = beam 4 velocity profiles in beam coordinates (VELTURB-B4_L0) [mm s-1] - b5 = beam 5 velocity profiles in beam coordinates (VELTURB-B5_L0) [mm s-1] - pg1 = percent good estimate for beam 1 [percent] - pg2 = percent good estimate for beam 2 [percent] - pg3 = percent good estimate for beam 3 [percent] - pg4 = percent good estimate for beam 4 [percent] - pg5 = percent good estimate for beam 5 [percent] - h = instrument's uncorrected magnetic heading [cdegrees] - p = instrument pitch [cdegrees] - r = instrument roll [cdegrees] - vf = instrument's vertical orientation (0 = downward looking and - 1 = upward looking) + """Computes the "true" Upward Velocity Profile (VELTURB-VLU-5BM) from the + beam coordinate transformed velocity profiles. + This provides a better vertical velocity estimate since beam 5 is oriented vertically. + + Parameters + ---------- + b1 : array_like + Beam 1 velocity profiles in beam coordinates (VELTURB-B1_L0) [mm s-1]. + b2 : array_like + Beam 2 velocity profiles in beam coordinates (VELTURB-B2_L0) [mm s-1]. + b3 : array_like + Beam 3 velocity profiles in beam coordinates (VELTURB-B3_L0) [mm s-1]. + b4 : array_like + Beam 4 velocity profiles in beam coordinates (VELTURB-B4_L0) [mm s-1]. + b5 : array_like + Beam 5 velocity profiles in beam coordinates (VELTURB-B5_L0) [mm s-1]. + pg1 : array_like + Percent good estimate for beam 1 [percent]. + pg2 : array_like + Percent good estimate for beam 2 [percent]. + pg3 : array_like + Percent good estimate for beam 3 [percent]. + pg4 : array_like + Percent good estimate for beam 4 [percent]. + pg5 : array_like + Percent good estimate for beam 5 [percent]. + h : array_like + Instrument's uncorrected magnetic heading [cdegrees]. + p : array_like + Instrument pitch [cdegrees]. + r : array_like + Instrument roll [cdegrees]. + vf : array_like or int + Instrument's vertical orientation (0 = downward looking, 1 = upward looking). + Returns + ------- + w : ndarray + True vertical velocity profiles in Earth coordinates (VELTURB-VLU-5BM_L1) [m s-1]. + + Notes + ----- + - Input velocities are expected in mm/s and output is in m/s. + + References + ---------- + - Data Product Specification for Turbulent Velocity Profile and Echo Intensity - DCN 1341-00760. """ # compute the beam to instrument transform x, y, _, _ = adcp_beam2ins(b1, b2, b3, b4, pg1, pg2, pg3, pg4) @@ -866,37 +821,36 @@ def vadcp_beam_vertical_true(b1, b2, b3, b4, b5, pg1, pg2, pg3, pg4, pg5, h, p, @deprecated def vadcp_beam_error(b1, b2, b3, b4, pg1, pg2, pg3, pg4): """ - Description: - - Wrapper function to compute the Error Velocity Profile (VELTURB-ERR) - from the beam coordinate transformed velocity profiles as defined in - the Data Product Specification for Turbulent Velocity Profile and Echo - Intensity - DCN 1341-00760. - - Implemented by: - - 2014-06-25: Christopher Wingard. Initial code, based on existing ADCP - 2015-06-10: Russell Desiderio. - Moved the conditioning of input beam velocities to adcp_beam2inst. - 2019-08-13: Christopher Wingard. Adds functionality to compute a 3-beam solution - and cleans up syntax used in the function. + Wrapper function to compute the Error Velocity Profile (VELTURB-ERR) + from the beam coordinate transformed velocity profiles. - Usage: - - e = vadcp_beam_error(b1, b2, b3, b4, pg1, pg2, pg3, pg4) - - where + Parameters + ---------- + b1 : array_like + Beam 1 velocity profiles in beam coordinates (VELTURB-B1_L0) [mm s-1]. + b2 : array_like + Beam 2 velocity profiles in beam coordinates (VELTURB-B2_L0) [mm s-1]. + b3 : array_like + Beam 3 velocity profiles in beam coordinates (VELTURB-B3_L0) [mm s-1]. + b4 : array_like + Beam 4 velocity profiles in beam coordinates (VELTURB-B4_L0) [mm s-1]. + pg1 : array_like + Percent good estimate for beam 1 [%]. + pg2 : array_like + Percent good estimate for beam 2 [%]. + pg3 : array_like + Percent good estimate for beam 3 [%]. + pg4 : array_like + Percent good estimate for beam 4 [%]. - e = error velocity profiles (VELTURB-ERR_L1) [m s-1] + Returns + ------- + e : ndarray + Error velocity profiles (VELTURB-ERR_L1) [m s-1]. - b1 = "beam 1" velocity profiles in beam coordinates (VELTURB-B1_L0) [mm s-1] - b2 = "beam 2" velocity profiles in beam coordinates (VELTURB-B2_L0) [mm s-1] - b3 = "beam 3" velocity profiles in beam coordinates (VELTURB-B3_L0) [mm s-1] - b4 = "beam 4" velocity profiles in beam coordinates (VELTURB-B4_L0) [mm s-1] - pg1 = percent good estimate for beam 1 [percent] - pg2 = percent good estimate for beam 2 [percent] - pg3 = percent good estimate for beam 3 [percent] - pg4 = percent good estimate for beam 4 [percent] + Examples + -------- + >>> e = vadcp_beam_error(b1, b2, b3, b4, pg1, pg2, pg3, pg4) """ # compute the beam to instrument transform _, _, _, e = adcp_beam2ins(b1, b2, b3, b4, pg1, pg2, pg3, pg4) @@ -911,43 +865,34 @@ def vadcp_beam_error(b1, b2, b3, b4, pg1, pg2, pg3, pg4): # Calculates ECHOINT_L1 for all tRDI ADCPs def adcp_backscatter(raw, sfactor=0.45): """ - Description: - - Converts the echo intensity data from counts to dB using a factory - specified scale factor (nominally 0.45 dB/count for the Workhorse - family of ADCPs and 0.61 dB/count for the ExplorerDVL family). As - defined in the Data Product Specification for Velocity Profile and Echo - Intensity - DCN 1341-00750. - - Implemented by: - - 2014-04-21: Christopher Wingard. Initial code. - 2015-06-25: Russell Desiderio. Incorporated int fillvalue -> Nan. - 2023-08-15: Samuel Dahlberg. Added default value to sfactor. + Converts the echo intensity data from counts to dB using a factory + specified scale factor. - Usage: - - dB = adcp_backscatter(raw, sfactor) - - where - - dB = Relative Echo Intensity (ECHOINT_L1) [dB] - - raw = raw echo intensity (ECHOINT_L0) [count] - sfactor = factory supplied scale factor, instrument and beam specific [dB/count] - - Notes: + Parameters + ---------- + raw : array_like + Raw echo intensity (ECHOINT_L0) [count]. + sfactor : float or array_like, optional + Factory supplied scale factor, instrument and beam specific [dB/count]. + Default is 0.45. - The ADCP outputs the raw echo intensity as a 1-byte integer, so the ADCP_FILLVALUE - cannot apply (requires 2 bytes). + Returns + ------- + dB : array_like + Relative Echo Intensity (ECHOINT_L1) [dB]. - References: + Notes + ----- + * The ADCP outputs the raw echo intensity as a 1-byte integer, so the ADCP_FILLVALUE + cannot apply (requires 2 bytes). + * The default scale factor is nominally 0.45 dB/count for the Workhorse + family of ADCPs and 0.61 dB/count for the ExplorerDVL family. - OOI (2012). Data Product Specification for Velocity Profile and Echo - Intensity. Document Control Number 1341-00750. - https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI - >> Controlled >> 1000 System Level >> - 1341-00050_Data_Product_SPEC_VELPROF_OOI.pdf) + References + ---------- + OOI (2012). Data Product Specification for Velocity Profile and Echo Intensity. + Document Control Number 1341-00750. + https://alfresco.oceanobservatories.org/ """ if np.isscalar(sfactor) is False: sfactor = sfactor.reshape(sfactor.shape[0], 1) @@ -962,52 +907,45 @@ def adcp_backscatter(raw, sfactor=0.45): ##### ADCP Beam to Earth Transforms and Magnetic Variation Corrections def adcp_beam2ins(b1, b2, b3, b4, pg1, pg2, pg3, pg4): """ - Description: - - This function converts the Beam Coordinate transformed velocity - profiles to the instrument coordinate system. The calculations are - defined in the Data Product Specification for Velocity Profile and Echo - Intensity - DCN 1341-00750. - - Implemented by: - - 2013-04-10: Christopher Wingard. Initial code. - 2015-06-24: Russell Desiderio. Incorporated int fillvalue -> Nan. - 2019-08-13: Christopher Wingard. Adds functionality to compute a 3-beam solution - and cleans up syntax used in the function. - - Usage: - - x, y, z, e = adcp_beam2ins(b1, b2, b3, b4, pg1, pg2, pg3, pg4) - - where + Converts the Beam Coordinate transformed velocity profiles to the instrument coordinate system. - x = x axis velocity profiles in instrument coordinates [mm s-1] - y = y axis velocity profiles in instrument coordinates [mm s-1] - z = z axis velocity profiles in instrument coordinates [mm s-1] - e = error velocity profiles [mm s-1] - - b1 = beam 1 velocity profiles in beam coordinates [mm s-1] - b2 = beam 2 velocity profiles in beam coordinates [mm s-1] - b3 = beam 3 velocity profiles in beam coordinates [mm s-1] - b4 = beam 4 velocity profiles in beam coordinates [mm s-1] - pg1 = percent good estimate for beam 1 [percent] - pg2 = percent good estimate for beam 2 [percent] - pg3 = percent good estimate for beam 3 [percent] - pg4 = percent good estimate for beam 4 [percent] - - - References: - - OOI (2012). Data Product Specification for Velocity Profile and Echo Intensity. Document Control Number - 1341-00750. https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI >> Cyberinfrastructure >> - Data Product Specifications >> 1341-00750_Data_Product_SPEC_VELPROF_ECHOINT_OOI.pdf) + Parameters + ---------- + b1 : array_like + Beam 1 velocity profiles in beam coordinates (VELTURB-B1_L0) [mm s-1]. + b2 : array_like + Beam 2 velocity profiles in beam coordinates (VELTURB-B2_L0) [mm s-1]. + b3 : array_like + Beam 3 velocity profiles in beam coordinates (VELTURB-B3_L0) [mm s-1]. + b4 : array_like + Beam 4 velocity profiles in beam coordinates (VELTURB-B4_L0) [mm s-1]. + pg1 : array_like + Percent good estimate for beam 1 [%]. + pg2 : array_like + Percent good estimate for beam 2 [%]. + pg3 : array_like + Percent good estimate for beam 3 [%]. + pg4 : array_like + Percent good estimate for beam 4 [%]. - OOI (2013). Data Product Specification for Turbulent Velocity Profile and Echo Intensity. Document Control - Number 1341-00760. https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI >> - Cyberinfrastructure >> Data Product Specifications >> 1341-00760_Data_Product_VELTURB_ECHOINT.pdf) + Returns + ------- + x : array_like + x axis velocity profiles in instrument coordinates [mm s-1]. + y : array_like + y axis velocity profiles in instrument coordinates [mm s-1]. + z : array_like + z axis velocity profiles in instrument coordinates [mm s-1]. + e : array_like + Error velocity profiles [mm s-1]. - Teledyne RD Instruments (2008). ADCP Coordinate Transformation, Formulas and Calculations. + References + ---------- + OOI (2012). Data Product Specification for Velocity Profile and Echo Intensity. Document Control Number + 1341-00750. https://alfresco.oceanobservatories.org/ + OOI (2013). Data Product Specification for Turbulent Velocity Profile and Echo Intensity. Document Control + Number 1341-00760. https://alfresco.oceanobservatories.org/ + Teledyne RD Instruments (2008). ADCP Coordinate Transformation, Formulas and Calculations. """ # raw beam velocities, set to correct shape b1 = np.atleast_2d(b1) @@ -1061,52 +999,38 @@ def adcp_beam2ins(b1, b2, b3, b4, pg1, pg2, pg3, pg4): def adcp_ins2earth(u, v, w, heading, pitch, roll, vertical): """ - Description: - - This function converts the Instrument Coordinate transformed velocity - profiles to the Earth coordinate system. The calculation is defined in - the Data Product Specification for Velocity Profile and Echo Intensity - - DCN 1341-00750. - - Implemented by: - - 2013-04-10: Christopher Wingard. Initial code. - 2014-04-04: Russell Desiderio. Optimized code performance by replacing the for - loops previously used to calculate vectorized matrix multiplication - products with calls to np.einsum (numpy Einstein summation function). - 2015-06-24: Russell Desiderio. Changed implementation of 'vertical' in the roll - calculation so that if these values are equal to the CI fill value - (-999999999), when these fill values are replaced with nans, the nans - will propagate through to the data product output. - 2015-06-24: Russell Desiderio. Incorporated int fillvalue -> Nan. - 2023-08-15: Samuel Dahlberg. Changed local variable names to follow naming convention. - - Usage: - - uu, vu, ww = adcp_ins2earth(u, v, w, heading, pitch, roll, vertical) - - where - - uu = "east" velocity profiles in earth coordinates [mm s-1] - vv = "north" velocity profiles in earth coordinates [mm s-1] - ww = "vertical" velocity profiles in earth coordinates [mm s-1] - - u = east velocity profiles in instrument coordinates [mm s-1] - v = north velocity profiles in instrument coordinates [mm s-1] - w = vertical velocity profiles in instrument coordinates [mm s-1] - heading = instrument's uncorrected magnetic heading [centidegrees] - pitch = instrument pitch [centidegrees] - roll = instrument roll [centidegrees] - vertical = instrument's vertical orientation (0 = downward looking and - 1 = upward looking) - - References: - - OOI (2012). Data Product Specification for Velocity Profile and Echo - Intensity. Document Control Number 1341-00750. - https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI - >> Controlled >> 1000 System Level >> - 1341-00050_Data_Product_SPEC_VELPROF_OOI.pdf) + Converts the Instrument Coordinate transformed velocity profiles to the Earth coordinate system. + + Parameters + ---------- + u : array_like + East velocity profiles in instrument coordinates [mm s-1] + v : array_like + North velocity profiles in instrument coordinates [mm s-1] + w : array_like + Vertical velocity profiles in instrument coordinates [mm s-1] + heading : float or array_like + Instrument's uncorrected magnetic heading [centidegrees] + pitch : float or array_like + Instrument pitch [centidegrees] + roll : float or array_like + Instrument roll [centidegrees] + vertical : int or array_like + Instrument's vertical orientation (0 = downward looking, 1 = upward looking) + + Returns + ------- + uu : array_like + "East" velocity profiles in earth coordinates [mm s-1] + vv : array_like + "North" velocity profiles in earth coordinates [mm s-1] + ww : array_like + "Vertical" velocity profiles in earth coordinates [mm s-1] + + References + ---------- + OOI (2012). Data Product Specification for Velocity Profile and Echo Intensity. Document Control Number + 1341-00750. https://alfresco.oceanobservatories.org/ """ ### the input beam data for adcp_ins2earth are always called using the output ### of adcp_beam2ins, so the following lines are not needed. @@ -1200,59 +1124,46 @@ def adcp_ins2earth(u, v, w, heading, pitch, roll, vertical): def magnetic_correction(theta, u, v): + """ - Description: - - This function corrects velocity profiles for the magnetic variation - (declination) at the measurement location. The magnetic declination - is obtained from the 2010 World Magnetic Model (WMM2010) provided by - NOAA (see wmm_declination). - - This version handles 'vectorized' input variables without using for - loops. It was specifically written to handle the case of a 1D array of - theta values, theta=f(i), with corresponding sets of 'u' and 'v' values - such that u=f(i,j) and v=f(i,j), where there are j 'u' and 'v' values - for each theta(i). - - Implemented by: - - 2014-04-04: Russell Desiderio. Initial code. This function is used to - calculate magnetic corrections by the functions contained - in this module instead of the function magnetic_correction - found in ion_functions.data.generic_functions. - 2015-04-10: Russell Desiderio. Corrected a typo: - uv = np.atleast_2d(u) -> u = np.atleast_2d(u) - 2023-08-15: Samuel Dahlberg. Changed local variable names to follow naming convention. - - Usage: - - u_cor, v_cor = magnetic_correction(theta, u, v) - - where - - u_cor = eastward velocity profiles, in earth coordinates, with - the correction for magnetic variation applied. - v_cor = northward velocity profiles, in earth coordinates, - with the correction for magnetic variation applied. - - theta = magnetic variation based on location (latitude, longitude and - altitude) and date; units of theta are [degrees] - u = uncorrected eastward velocity profiles in earth coordinates - v = uncorrected northward velocity profiles in earth coordinates - - References: - - OOI (2012). Data Product Specification for Velocity Profile and Echo - Intensity. Document Control Number 1341-00750. - https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI - >> Controlled >> 1000 System Level >> - 1341-00750_Data_Product_SPEC_VELPROF_OOI.pdf) - - OOI (2013). Data Product Specification for Turbulent Velocity Profile - and Echo Intensity. Document Control Number 1341-00760. - https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI - >> Controlled >> 1000 System Level >> - 1341-00760_Data_Product_SPEC_VELPROF_OOI.pdf) + Corrects velocity profiles for the magnetic variation (declination) at the + measurement location. + The magnetic declination is obtained from the 2010 World Magnetic Model + (WMM2010) provided by NOAA (see wmm_declination). + + Parameters + ---------- + theta : float or array_like + Magnetic variation based on location (latitude, longitude, altitude) + and date [degrees] + u : array_like + Uncorrected eastward velocity profiles in earth coordinates + v : array_like + Uncorrected northward velocity profiles in earth coordinates + + Returns + ------- + u_cor : array_like + Eastward velocity profiles, in earth coordinates, with the correction + for magnetic variation applied. + v_cor : array_like + Northward velocity profiles, in earth coordinates, with the correction + for magnetic variation applied. + + Notes + ----- + This version handles 'vectorized' input variables without using for + loops. It was specifically written to handle the case of a 1D array of + theta values, theta=f(i), with corresponding sets of 'u' and 'v' values + such that u=f(i,j) and v=f(i,j), where there are j 'u' and 'v' values + for each theta(i). + + References + ---------- + OOI (2012). Data Product Specification for Velocity Profile and Echo Intensity. Document Control Number + 1341-00750. https://alfresco.oceanobservatories.org/ + OOI (2013). Data Product Specification for Turbulent Velocity Profile and Echo Intensity. Document Control + Number 1341-00760. https://alfresco.oceanobservatories.org/ """ # force shapes of inputs to arrays theta = np.atleast_1d(theta) @@ -1292,43 +1203,32 @@ def magnetic_correction(theta, u, v): def adcp_bin_depths_bar(dist_first_bin, bin_size, num_bins, pressure, adcp_orientation, latitude): """ - Description: - - Calculates the center bin depths for PD0 and PD12 ADCP data. As defined - in the Data Product Specification for Velocity Profile and Echo - Intensity - DCN 1341-00750. - - Implemented by: - - 2015-01-29: Craig Risien. Initial code. - 2015-06-26: Russell Desiderio. Fixed the handling of the pressure variables. - Time-vectorized the code by finessing the conditional. - 2015-06-30: Russell Desiderio. Incorporated int fillvalue -> Nan. - - - Usage: - - bin_depths = adcp_bin_depths(dist_first_bin, bin_size, num_bins, pressure, - adcp_orientation, latitude) + Calculates the center bin depths for PD0 and PD12 ADCP data. - where - - bin_depths = [meters] - - dist_first_bin = distance to the first ADCP bin [centimeters] - bin_size = depth of each ADCP bin [centimeters] - num_bins = number of ADCP bins [unitless] - pressure = pressure at the sensor head [bar] - adcp_orientation = 1=upward looking or 0=downward looking [unitless] - latitude = latitude of the instrument [degrees] + Parameters + ---------- + dist_first_bin : float or array_like + Distance to the first ADCP bin [centimeters] + bin_size : float or array_like + Depth of each ADCP bin [centimeters] + num_bins : int or array_like + Number of ADCP bins [unitless] + pressure : float or array_like + Pressure at the sensor head [bar] + adcp_orientation : int or array_like + 1=upward looking or 0=downward looking [unitless] + latitude : float or array_like + Latitude of the instrument [degrees] - References: + Returns + ------- + bin_depths : array_like + Bin depths [meters] - OOI (2012). Data Product Specification for Velocity Profile and Echo - Intensity. Document Control Number 1341-00750. - https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI - >> Controlled >> 1000 System Level >> - 1341-00050_Data_Product_SPEC_VELPROF_OOI.pdf) + References + ---------- + OOI (2012). Data Product Specification for Velocity Profile and Echo Intensity. Document Control Number + 1341-00750. https://alfresco.oceanobservatories.org/ """ # check for CI fill values. pressure = replace_fill_with_nan(None, pressure) @@ -1345,43 +1245,32 @@ def adcp_bin_depths_bar(dist_first_bin, bin_size, num_bins, pressure, adcp_orien def adcp_bin_depths_dapa(dist_first_bin, bin_size, num_bins, pressure, adcp_orientation, latitude): """ - Description: - - Calculates the center bin depths for PD0 and PD12 ADCP data. As defined - in the Data Product Specification for Velocity Profile and Echo - Intensity - DCN 1341-00750. + Calculates the center bin depths for PD0 and PD12 ADCP data. - Implemented by: - - 2015-01-29: Craig Risien. Initial code. - 2015-06-26: Russell Desiderio. Fixed the handling of the pressure variables. - Time-vectorized the code by finessing the conditional. - 2015-06-30: Russell Desiderio. Incorporated int fillvalue -> Nan. - - - Usage: - - bin_depths = adcp_bin_depths(dist_first_bin, bin_size, num_bins, pressure, - adcp_orientation, latitude) - - where - - bin_depths = [meters] - - dist_first_bin = distance to the first ADCP bin [centimeters] - bin_size = depth of each ADCP bin [centimeters] - num_bins = number of ADCP bins [unitless] - pressure = pressure at the sensor head [daPa] - adcp_orientation = 1=upward looking or 0=downward looking [unitless] - latitude = latitude of the instrument [degrees] + Parameters + ---------- + dist_first_bin : float or array_like + Distance to the first ADCP bin [centimeters] + bin_size : float or array_like + Depth of each ADCP bin [centimeters] + num_bins : int or array_like + Number of ADCP bins [unitless] + pressure : float or array_like + Pressure at the sensor head [daPa] + adcp_orientation : int or array_like + 1=upward looking or 0=downward looking [unitless] + latitude : float or array_like + Latitude of the instrument [degrees] - References: + Returns + ------- + bin_depths : array_like + Bin depths [meters] - OOI (2012). Data Product Specification for Velocity Profile and Echo - Intensity. Document Control Number 1341-00750. - https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI - >> Controlled >> 1000 System Level >> - 1341-00050_Data_Product_SPEC_VELPROF_OOI.pdf) + References + ---------- + OOI (2012). Data Product Specification for Velocity Profile and Echo Intensity. Document Control Number + 1341-00750. https://alfresco.oceanobservatories.org/ """ # check for CI fill values. pressure = replace_fill_with_nan(None, pressure) @@ -1398,40 +1287,30 @@ def adcp_bin_depths_dapa(dist_first_bin, bin_size, num_bins, pressure, adcp_orie def adcp_bin_depths(blanking_distance, bin_size, number_bins, orientation, depth): """ - Description: - - Calculates the center bin depths for ADCP data as defined in the Data Product Specification for Velocity - Profile and Echo Intensity - DCN 1341-00750. - - Implemented by: - - 2015-01-29: Craig Risien. Initial code. - 2015-06-26: Russell Desiderio. Fixed the handling of the pressure variables. Time-vectorized the code by - finessing the conditional. - 2015-06-30: Russell Desiderio. Incorporated int fillvalue -> Nan. - 2019-03-11: Christopher Wingard. Removed older OOI CI constraints and made ADCP data type agnostic, requiring - depth in meters as an input. - 2023-08-15: Samuel Dahlberg. Brought over from original Pyseas code to bring in compatibility with CGSN. - - Usage: - - bin_depths = adcp_bin_depths(blanking_distance, bin_size, number_bins, orientation, depth, latitude) - - where + Calculates the center bin depths for ADCP data. - bin_depths = [meters] - - blanking_distance = distance to the first ADCP bin [centimeters] - bin_size = size, or cell length, of each ADCP bin [centimeters] - number_bins = number of ADCP bins [unitless] - orientation = 1=upward looking or 0=downward looking [unitless] - depth = depth of the sensor head [m] + Parameters + ---------- + blanking_distance : float or array_like + Distance to the first ADCP bin [centimeters] + bin_size : float or array_like + Size, or cell length, of each ADCP bin [centimeters] + number_bins : int or array_like + Number of ADCP bins [unitless] + orientation : int or array_like + 1=upward looking or 0=downward looking [unitless] + depth : float or array_like + Depth of the sensor head [m] - References: + Returns + ------- + bin_depths : array_like + Bin depths [meters] - OOI (2012). Data Product Specification for Velocity Profile and Echo Intensity. Document Control Number - 1341-00750. https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI >> Cyberinfrastructure >> - Data Product Specifications >> 1341-00750_Data_Product_SPEC_VELPROF_ECHOINT_OOI.pdf) + References + ---------- + OOI (2012). Data Product Specification for Velocity Profile and Echo Intensity. Document Control Number + 1341-00750. https://alfresco.oceanobservatories.org/ """ # Convert from cm to meters blanking_distance = blanking_distance / 100.0 @@ -1454,79 +1333,50 @@ def adcp_bin_depths(blanking_distance, bin_size, number_bins, orientation, depth def z_from_p(p, lat, geo_strf_dyn_height=0, sea_surface_geopotential=0): - """Calculates height from sea pressure using the computationally-efficient - 75-term expression for density in terms of SA, CT and p (Roquet et al., - 2015). Dynamic height anomaly, geo_strf_dyn_height, if provided, must be - computed with its p_ref=0 (the surface). Also if provided, sea_surface_geopotental - is the geopotential at zero sea pressure. - - Calls a function which calculates enthalpy assuming standard ocean salinity - and 0 degrees celsius. + """ + Calculates height from sea pressure using the computationally-efficient + 75-term expression for density. Parameters ---------- - p : pressure [dbar] - lat : latitude in decimal degrees north [-90..+90] - geo_strf_dyn_height : dynamic height anomaly [m^2/s^2] - sea_surface_geopotential : geopotential at zero sea pressure [ m^2/s^2 ] + p : float or array_like + Pressure [dbar] + lat : float or array_like + Latitude in decimal degrees north [-90..+90] + geo_strf_dyn_height : float, optional + Dynamic height anomaly [m^2/s^2] + sea_surface_geopotential : float, optional + Geopotential at zero sea pressure [m^2/s^2] Returns ------- - z : TEOS-10 height [m] : height is returned as a negative number; its - absolute value is the depth below the sea surface. + z : array_like + TEOS-10 height [m] (negative below sea surface) - ################################################################# - # Check values from TEOS-10 version 3.05 (matlab code): # - # from http://www.teos-10.org/pubs/gsw/html/gsw_z_from_p.html # - ################################################################# + Notes + ----- + - Dynamic height anomaly, geo_strf_dyn_height, if provided, must be + computed with its p_ref=0 (the surface). + - Calls a function which calculates enthalpy assuming standard ocean salinity + and 0 degrees celsius. - p = [10, 50, 125, 250, 600, 1000] - lat = 4 + Examples + -------- - z_from_p(p, lat) = + >>> p = [10, 50, 125, 250, 600, 1000] + >>> lat = 4 + >>> z_from_p(p, lat) = [ -9.9445834469453, -49.7180897012550, -124.2726219409978, -248.4700576548589, -595.8253480356214, -992.0919060719987] - Notes - ----- - At sea level z = 0, and since z (HEIGHT) is defined to be positive upwards, - it follows that while z is positive in the atmosphere, it is NEGATIVE in - the ocean. - References ---------- - IOC, SCOR and IAPSO, 2010: The international thermodynamic equation of - seawater - 2010: Calculation and use of thermodynamic properties. - Intergovernmental Oceanographic Commission, Manuals and Guides No. 56, - UNESCO (English), 196 pp. Available from the TEOS-10 web site. - - McDougall, T.J., D.R. Jackett, D.G. Wright and R. Feistel, 2003: - Accurate and computationally efficient algorithms for potential - temperature and density of seawater. J. Atmosph. Ocean. Tech., 20, - pp. 730-741. - + IOC, SCOR and IAPSO, 2010: The international thermodynamic equation of seawater - 2010. + McDougall, T.J., et al., 2003: Accurate and computationally efficient algorithms for potential temperature and density of seawater.J. Atmosph. Ocean. Tech., 20, pp. 730-741. Moritz, 2000: Goedetic reference system 1980. J. Geodesy, 74, 128-133. - - Roquet, F., G. Madec, T.J. McDougall, P.M. Barker, 2015: Accurate - polynomial expressions for the density and specifc volume of seawater - using the TEOS-10 standard. Ocean Modelling. - - Saunders, P. M., 1981: Practical conversion of pressure to depth. - Journal of Physical Oceanography, 11, 573-574. - - IMPLEMENTATION NOTES: - - Russell Desiderio. 2015_07_01 - versions 3.04 and 3.05 of the main function z_from_p are identical. - - z_from_p calls the subroutine enthalpy_SSO_0_p; this subroutine - has been updated from ver 3.04 to 3.05. - - the check values above for z_from_p have been updated to incorporate - this change using enthalpy_SSO_0_p ver 3.05. - + Roquet, F., et al., 2015: Accurate polynomial expressions for the density and specifc volume of seawater using the TEOS-10 standard. Ocean Modelling. + Saunders, P. M., 1981: Practical conversion of pressure to depth. Journal of Physical Oceanography, 11, 573-574. """ - x = np.sin(np.deg2rad(lat)) sin2 = x ** 2 b = 9.780327 * (1.0 + (5.2792e-3 + (2.32e-5 * sin2)) * sin2) @@ -1539,28 +1389,26 @@ def z_from_p(p, lat, geo_strf_dyn_height=0, sea_surface_geopotential=0): def enthalpy_SSO_0_p(p): """ - This documentation and code is copy\pasted from the matlab coding of this function. - - %========================================================================== - % This function calculates enthalpy at the Standard Ocean Salinity, SSO, - % and at a Conservative Temperature of zero degrees C, as a function of - % pressure, p, in dbar, using a streamlined version of the 76-term - % computationally-efficient expression for specific volume, that is, a - % streamlined version of the code "gsw_enthalpy(SA,CT,p)". - % - % VERSION NUMBER: 3.05 (27th January 2015) - % - % REFERENCES: - % Roquet, F., G. Madec, T.J. McDougall, P.M. Barker, 2015: Accurate - % polynomial expressions for the density and specifc volume of seawater - % using the TEOS-10 standard. Ocean Modelling. - % - %========================================================================== - - IMPLEMENTATION NOTES: - - Russell Desiderio. 2015_07_01. this subroutine has been updated - from ver 3.04 to 3.05. + Calculates enthalpy at the Standard Ocean Salinity, SSO, and at a Conservative Temperature of zero degrees C, as a function of pressure. + + Parameters + ---------- + p : float or array_like + Pressure [dbar] + + Returns + ------- + enthalpy_SSO_0 : array_like + Enthalpy at SSO and 0 deg C + + Notes + ----- + - The python implementation comes directly from the matlab coding of this function: + VERSION NUMBER: 3.05 (27th January 2015) + + References + ---------- + Roquet, F., et al., 2015: Accurate polynomial expressions for the density and specifc volume of seawater using the TEOS-10 standard. Ocean Modelling. """ z = p * 1e-4 @@ -1578,39 +1426,30 @@ def enthalpy_SSO_0_p(p): def adcp_bin_depths_meters(dist_first_bin, bin_size, num_bins, sensor_depth, adcp_orientation): """ - Description: - - Calculates the center bin depths for PD0, PD8 and PD12 ADCP data. As defined - in the Data Product Specification for Velocity Profile and Echo - Intensity - DCN 1341-00750. - - Implemented by: - - 2015-01-30: Craig Risien. Initial code. - 2015-06-26: Russell Desiderio. Time-vectorized the code by finessing the conditionals. - 2015-06-30: Russell Desiderio. Incorporated int fillvalue -> Nan. - - Usage: - - bin_depths_pd8 = adcp_bin_depths(dist_first_bin, bin_size, num_bins, sensor_depth, - adcp_orientation) - - where - - bin_depths_pd8 = [meters] + Calculates the center bin depths for PD0, PD8 and PD12 ADCP data. - dist_first_bin = distance to the first ADCP bin [centimeters] - bin_size = depth of each ADCP bin [centimeters] - num_bins = number of ADCP bins [unitless] - sensor_depth = estimated depth at the sensor head [meters] - adcp_orientation = 1=upward looking or 0=downward looking [unitless] - - Notes: + Parameters + ---------- + dist_first_bin : float or array_like + Distance to the first ADCP bin [centimeters] + bin_size : float or array_like + Depth of each ADCP bin [centimeters] + num_bins : int or array_like + Number of ADCP bins [unitless] + sensor_depth : float or array_like + Estimated depth at the sensor head [meters] + adcp_orientation : int or array_like + 1=upward looking or 0=downward looking [unitless] - The PD8 output format is a very sparse format. Other than num_bins, it does *not* record - any of the other input variables required by this DPA. Those must somehow be supplied "by - hand". + Returns + ------- + bin_depths_pd8 : array_like + Bin depths [meters] + Notes + ----- + The PD8 output format is a very sparse format. Other than num_bins, it does *not* record + any of the other input variables required by this DPA. Those must somehow be supplied "by hand". """ # check for CI fill values. # @@ -1657,27 +1496,21 @@ def adcp_bin_depths_meters(dist_first_bin, bin_size, num_bins, sensor_depth, adc def depth_from_pressure_dbar(pressure, latitude, pressure_scale_factor=None): """ - Description: - - Calculates depth from pressure. This function was extracted from - the adcp_bin_depths_dapa function. - - Implemented by: + Calculates depth from pressure. - 2019-06-29: Mark Steiner. Initial code. - - Usage: - - depth = depth_from_pressure_dbar(pressure, latitude, pressure_scale_factor) - - where - - depths = [meters] - - pressure = pressure [dbar] - latitude = latitude of the instrument [degrees] - pressure_scale_factor = scale factor to convert pressure to dbar [unitless] + Parameters + ---------- + pressure : float or array_like + Pressure [dbar] + latitude : float or array_like + Latitude of the instrument [degrees] + pressure_scale_factor : float, optional + Scale factor to convert pressure to dbar [unitless] + Returns + ------- + depth : array_like + Depths [meters] """ # check for CI fill values. pressure = replace_fill_with_nan(None, pressure) diff --git a/ion_functions/data/co2_functions.py b/ion_functions/data/co2_functions.py index dc7d48a..4e08208 100644 --- a/ion_functions/data/co2_functions.py +++ b/ion_functions/data/co2_functions.py @@ -1,12 +1,19 @@ #!/usr/bin/env python +# @package ion_functions.data.pco2_functions +# @file ion_functions/data/pco2_functions.py +# @author Christopher Wingard +# @brief Module containing CO2 instrument family related functions + """ -@package ion_functions.data.pco2_functions -@file ion_functions/data/pco2_functions.py -@author Christopher Wingard -@brief Module containing CO2 instrument family related functions +# Overview +Module containing CO2 instrument family related functions. +This module implements the algorithms for calculating pCO2 in seawater (PCO2WAT), +extracting absorbance ratios from light measurements, and converting raw +thermistor and battery voltage readings from the OOI L0 PCO2 data product. """ import numpy as np + from ion_functions.utils import fill_value @@ -14,33 +21,21 @@ # and process these extracted parameters to calculate pCO2 def pco2_abs434_ratio(light): """ - Description: - - Extract the absorbance ratio at 434 nm from the pCO2 instrument light - measurements. This will extract the CO2ABS1_L0 data product from the - instrument light measurement arrays. - - Implemented by: - - 2013-04-20: Christopher Wingard. Initial code. - 2014-02-19: Christopher Wingard. Updated comments. - - Usage: - - a434ratio = pco2_abs434_ratio(light) + Extract the absorbance ratio at 434 nm from the pCO2 instrument light measurements. - where + Parameters + ---------- + light : array_like + Array of light measurements. - a434ratio = optical absorbance Ratio at 434 nm (CO2ABS1_L0) [unitless] - light = array of light measurements + Returns + ------- + a434ratio : array_like + Optical absorbance Ratio at 434 nm (CO2ABS1_L0) [unitless] - References: - - OOI (2012). Data Product Specification for Partial Pressure of CO2 in - Seawater. Document Control Number 1341-00510. - https://alfresco.oceanobservatories.org/ (See: Company Home >> - OOI >> Controlled >> 1000 System Level >> - 1341-00490_Data_Product_SPEC_PCO2WAT_OOI.pdf) + References + ---------- + OOI (2012). Data Product Specification for Partial Pressure of CO2 in Seawater. Document Control Number 1341-00510. """ light = np.atleast_2d(light) a434ratio = light[:, 6] @@ -49,33 +44,21 @@ def pco2_abs434_ratio(light): def pco2_abs620_ratio(light): """ - Description: - - Extract the absorbance ratio at 620 nm from the pCO2 instrument light - measurements. This will extract the CO2ABS2_L0 data product from the - instrument light measurement arrays. - - Implemented by: - - 2013-04-20: Christopher Wingard. Initial code. - 2014-02-19: Christopher Wingard. Updated comments. - - Usage: - - a620ratio = pco2_abs620_ratio(light) - - where + Extract the absorbance ratio at 620 nm from the pCO2 instrument light measurements. - a620ratio = optical absorbance Ratio at 620 nm (CO2ABS2_L0) [unitless] - light = array of light measurements + Parameters + ---------- + light : array_like + Array of light measurements. - References: + Returns + ------- + a620ratio : array_like + Optical absorbance Ratio at 620 nm (CO2ABS2_L0) [unitless] - OOI (2012). Data Product Specification for Partial Pressure of CO2 in - Seawater. Document Control Number 1341-00510. - https://alfresco.oceanobservatories.org/ (See: Company Home >> - OOI >> Controlled >> 1000 System Level >> - 1341-00490_Data_Product_SPEC_PCO2WAT_OOI.pdf) + References + ---------- + OOI (2012). Data Product Specification for Partial Pressure of CO2 in Seawater. Document Control Number 1341-00510. """ light = np.atleast_2d(light) a620ratio = light[:, 7] @@ -84,36 +67,21 @@ def pco2_abs620_ratio(light): def pco2_blank(raw_blank): """ - Description: + Calculates the absorbance blank at 434 or 620 nm from the SAMI2-pCO2 instrument. - Calculates the absorbance blank at 434 or 620 nm from the SAMI2-pCO2 - instrument. + Parameters + ---------- + raw_blank : array_like + Raw optical absorbance blank at 434 or 620 nm [counts] - Implemented by: + Returns + ------- + blank : array_like + Optical absorbance blank at 434 or 620 nm [unitless] - 2013-04-20: Christopher Wingard. Initial code. - 2014-02-19: Christopher Wingard. Updated comments. - 2014-02-28: Christopher Wingard. Updated to except raw blank values - from a sparse array. - 2018-03-04: Christopher Wingard. Updated to correctly calculate the - blank based on new code from the vendor. - - Usage: - - blank = pco2_blank(raw_blank) - - where - - blank = optical absorbance blank at 434 or 620 nm [unitless] - raw_blank = raw optical absorbance blank at 434 or 620 nm [counts] - - References: - - OOI (2012). Data Product Specification for Partial Pressure of CO2 in - Seawater. Document Control Number 1341-00510. - https://alfresco.oceanobservatories.org/ (See: Company Home >> - OOI >> Controlled >> 1000 System Level >> - 1341-00490_Data_Product_SPEC_PCO2WAT_OOI.pdf) + References + ---------- + OOI (2012). Data Product Specification for Partial Pressure of CO2 in Seawater. Document Control Number 1341-00510. """ blank = raw_blank / 16384. return blank @@ -121,36 +89,23 @@ def pco2_blank(raw_blank): def pco2_thermistor(traw, sami_bits=12): """ - Description: - - Convert the thermistor data from counts to degrees Centigrade from the - pCO2 instrument. - - Implemented by: - - 2013-04-20: Christopher Wingard. Initial code. - 2014-02-19: Christopher Wingard. Updated comments. - 2023-01-12: Mark Steiner. Add sami_bits arg to handle hardware upgrades - 2023-08-15: Samuel Dahlberg. Renamed local variables to follow naming convention. - Replaced use of Numexpr with Numpy. - - Usage: - - therm = pco2_thermistor(traw, sami_bits) - - where - - therm = converted thermistor temperature [degC] - traw = raw thermistor temperature (CO2THRM_L0) [counts] - sami_bits = number of bits on the SAMI hardware - - References: - - OOI (2012). Data Product Specification for Partial Pressure of CO2 in - Seawater. Document Control Number 1341-00510. - https://alfresco.oceanobservatories.org/ (See: Company Home >> - OOI >> Controlled >> 1000 System Level >> - 1341-00490_Data_Product_SPEC_PCO2WAT_OOI.pdf) + Convert the thermistor data from counts to degrees Centigrade from the pCO2 instrument. + + Parameters + ---------- + traw : array_like + Raw thermistor temperature (CO2THRM_L0) [counts] + sami_bits : int or array_like, optional + Number of bits on the SAMI hardware + + Returns + ------- + therm : array_like + Converted thermistor temperature [degC] + + References + ---------- + OOI (2012). Data Product Specification for Partial Pressure of CO2 in Seawater. Document Control Number 1341-00510. """ # reset inputs to arrays traw = np.atleast_1d(traw) @@ -169,24 +124,19 @@ def pco2_thermistor(traw, sami_bits=12): def pco2_battery(braw, sami_bits): """ - Description: - - Convert the battery voltage data from counts to volts from the - pCO2 instrument. - - Implemented by: - - 2023-02-23: Mark Steiner. Initial code. - - Usage: - - volts = pco2_battery_voltage(vraw, sami_bits) - - where - - volts = converted battery voltage [degC] - braw = raw battery voltage [counts] - sami_bits = number of bits on the SAMI hardware + Convert the battery voltage data from counts to volts from the pCO2 instrument. + + Parameters + ---------- + braw : array_like + Raw battery voltage [counts] + sami_bits : int or array_like + Number of bits on the SAMI hardware + + Returns + ------- + volts : array_like + Converted battery voltage [V] """ # reset inputs to arrays braw = np.atleast_1d(braw) @@ -203,51 +153,51 @@ def pco2_battery(braw, sami_bits): def pco2_pco2wat(mtype, light, therm, ea434, eb434, ea620, eb620, calt, cala, calb, calc, a434blank, a620blank): """ - Description: - - Function to calculate the L1 PCO2WAT core data from the pCO2 instrument - if the measurement type is 4 (pCO2 measurement), otherwise it is a - blank and return a fill value. - - Implemented by: - - 2013-04-20: Christopher Wingard. Initial code. - 2014-02-19: Christopher Wingard. Updated comments. - 2014-03-19: Christopher Wingard. Optimized using feedback provided by - Chris Fortin. - 2017-04-04: Pete Cable. Updated algorithm to use thermistor/blank counts - as indicated in the DPS and the usage below. - - Usage: - - pco2 = pco2_pco2wat(mtype, light, therm, ea434, eb434, ea620, eb620, - calt, cala, calb, calc, a434blank, a620blank) - - where - - pco2 = measured pco2 in seawater (PCO2WAT_L1) [uatm] - mtype = measurement type, where 4 == actual measurement and 5 == a - blank measurement [unitless] - light = array of light measurements - therm = PCO2W thermistor temperature (CO2THRM_L0) [counts] - ea434 = Reagent specific calibration coefficient - eb434 = Reagent specific calibration coefficient - ea620 = Reagent specific calibration coefficient - eb620 = Reagent specific calibration coefficient - calt = Instrument specific calibration coefficient for temperature - cala = Instrument specific calibration coefficient for the pCO2 measurements - calb = Instrument specific calibration coefficient for the pCO2 measurements - calc = Instrument specific calibration coefficient for the pCO2 measurements - a434blank = Blank measurements at 434 nm (CO2ABS1_L0) [counts] - a620blank = Blank measurements to 620 nm (CO2ABS2_L0) [counts] - - References: - - OOI (2012). Data Product Specification for Partial Pressure of CO2 in - Seawater. Document Control Number 1341-00510. - https://alfresco.oceanobservatories.org/ (See: Company Home >> - OOI >> Controlled >> 1000 System Level >> - 1341-00490_Data_Product_SPEC_PCO2WAT_OOI.pdf) + Calculates the L1 PCO2WAT core data from the pCO2 instrument. + + Parameters + ---------- + mtype : array_like + Measurement type, where 4 indicates actual measurement and 5 indicates a blank measurement [unitless]. + light : array_like + Array of light measurements. + therm : array_like + PCO2W thermistor temperature (CO2THRM_L0) [counts]. + ea434 : array_like + Reagent specific calibration coefficient. + eb434 : array_like + Reagent specific calibration coefficient. + ea620 : array_like + Reagent specific calibration coefficient. + eb620 : array_like + Reagent specific calibration coefficient. + calt : array_like + Instrument specific calibration coefficient for temperature. + cala : array_like + Instrument specific calibration coefficient for the pCO2 measurements. + calb : array_like + Instrument specific calibration coefficient for the pCO2 measurements. + calc : array_like + Instrument specific calibration coefficient for the pCO2 measurements. + a434blank : array_like + Blank measurements at 434 nm (CO2ABS1_L0) [counts]. + a620blank : array_like + Blank measurements at 620 nm (CO2ABS2_L0) [counts]. + + Returns + ------- + pco2 : array_like + Measured pCO2 in seawater (PCO2WAT_L1) [uatm]. + + Notes + ----- + the measurement type is 4 (pCO2 measurement), otherwise it is a blank and + return a fill value. + + References + ---------- + OOI (2012). Data Product Specification for Partial Pressure of CO2 in Seawater. Document Control Number 1341-00510. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> 1341-00490_Data_Product_SPEC_PCO2WAT_OOI.pdf) """ # reset inputs to arrays # measurements @@ -282,54 +232,45 @@ def pco2_pco2wat(mtype, light, therm, ea434, eb434, ea620, eb620, def pco2_calc_pco2(light, therm, ea434, eb434, ea620, eb620, calt, cala, calb, calc, a434blank, a620blank): """ - Description: - - OOI Level 1 Partial Pressure of CO2 (pCO2) in seawater core data - product, which is calculated from the Sunburst SAMI-II CO2 instrument - (PCO2W). - - Implemented by: - - 20??-??-??: J. Newton (Sunburst Sensors, LLC). Original Matlab code. - 2013-04-20: Christopher Wingard. Initial python code. - 2014-02-19: Christopher Wingard. Updated comments. - 2014-03-19: Christopher Wingard. Optimized. - 2018-03-04: Christopher Wingard. Updated to correctly calculate pCO2 using - newly formulated code provided by the vendor. Original vendor code - incorrectly calculated the blank correction. Applies additional - corrections to calculations to avoid errors thrown when running a - blank measurement. - 2023-01-12: Mark Steiner. Arg therm in degrees C instead of counts - 2023-08-15: Samuel Dahlberg. Changed local variable names to follow naming convention. - - Usage: - - pco2 = pco2_pco2wat(light, therm, ea434, eb434, ea620, eb620, - calt, cala, calb, calc, a434blank, a620blank) - - where - - pco2 = measured pco2 in seawater (PCO2WAT_L1) [uatm] - light = array of light measurements - therm = PCO2W thermistor temperature (CO2THRM_L1) [degrees C] - ea434 = Reagent specific calibration coefficient - eb434 = Reagent specific calibration coefficient - ea620 = Reagent specific calibration coefficient - eb620 = Reagent specific calibration coefficient - calt = Instrument specific calibration coefficient for temperature - cala = Instrument specific calibration coefficient for the pCO2 measurements - calb = Instrument specific calibration coefficient for the pCO2 measurements - calc = Instrument specific calibration coefficient for the pCO2 measurements - a434blank = Blank measurements at 434 nm (CO2ABS1_L0) [counts] - a620blank = Blank measurements to 620 nm (CO2ABS2_L0) [counts] - - References: - - OOI (2012). Data Product Specification for Partial Pressure of CO2 in - Seawater. Document Control Number 1341-00510. - https://alfresco.oceanobservatories.org/ (See: Company Home >> - OOI >> Controlled >> 1000 System Level >> - 1341-00490_Data_Product_SPEC_PCO2WAT_OOI.pdf) + Calculates the Level 1 Partial Pressure of CO2 (pCO2) in seawater from + Sunburst SAMI-II CO2 instrument (PCO2W) measurements. + + Parameters + ---------- + light : array_like + Array of light measurements. + therm : array_like + PCO2W thermistor temperature (CO2THRM_L1) [degrees C] + ea434 : array_like + Reagent specific calibration coefficient. + eb434 : array_like + Reagent specific calibration coefficient. + ea620 : array_like + Reagent specific calibration coefficient. + eb620 : array_like + Reagent specific calibration coefficient. + calt : array_like + Instrument specific calibration coefficient for temperature. + cala : array_like + Instrument specific calibration coefficient for the pCO2 measurements. + calb : array_like + Instrument specific calibration coefficient for the pCO2 measurements. + calc : array_like + Instrument specific calibration coefficient for the pCO2 measurements. + a434blank : array_like + Blank measurements at 434 nm (CO2ABS1_L0) [counts]. + a620blank : array_like + Blank measurements at 620 nm (CO2ABS2_L0) [counts]. + + Returns + ------- + pco2 : array_like + Measured pCO2 in seawater (PCO2WAT_L1) [uatm]. + + References + ---------- + OOI (2012). Data Product Specification for Partial Pressure of CO2 in Seawater. Document Control Number 1341-00510. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> 1341-00490_Data_Product_SPEC_PCO2WAT_OOI.pdf) """ # set constants -- original vendor formulation, reset below # ea434 = ea434 - 29.3 * calt @@ -376,40 +317,31 @@ def pco2_calc_pco2(light, therm, ea434, eb434, ea620, eb620, def pco2_ppressure(xco2, p, std=1013.25): """ - Description: - - OOI Level 1 Partial Pressure of CO2 in Air (PCO2ATM) or Surface - Seawater (PCO2SSW) core date product is computed by using an - equation that incorporates the Gas Stream Pressure (PRESAIR) and the - CO2 Mole Fraction in Air or Surface Seawater (XCO2ATM or XCO2SSW, - respectively). It is computed using data from the pCO2 air-sea (PCO2A) - family of instruments. - - Implemented by: - - 2014-10-27: Christopher Wingard. Initial python code. - 2023-08-15: Samuel Dahlberg. Removed use of Numexpr. - - Usage: - - ppres = pco2_ppressure(xco2, p, std) - - where - - ppres = partial pressure of CO2 in air or surface seawater [uatm] - (PCO2ATM_L1 or PCO2SSW_L1) - xco2 = CO2 mole fraction in air or surface seawater [ppm] (XCO2ATM_LO - or XCO2SSW_L0) - p = gas stream pressure [mbar] (PRESAIR_L0) - std = standard atmospheric pressure set to default of 1013.25 [mbar/atm] - - References: - - OOI (2012). Data Product Specification for Partial Pressure of CO2 in - Air and Surface Seawater. Document Control Number 1341-00260. - https://alfresco.oceanobservatories.org/ (See: Company Home >> - OOI >> Controlled >> 1000 System Level >> - 1341-00260_Data_Product_SPEC_PCO2ATM_PCO2SSW_OOI.pdf) + Calculate the partial pressure of CO2 in air or surface seawater. + This function computes the OOI Level 1 Partial Pressure of CO2 in Air + (PCO2ATM) or Surface Seawater (PCO2SSW) core data product using data from + the pCO2 air-sea (PCO2A) family of instruments. The calculation incorporates + the Gas Stream Pressure (PRESAIR) and the CO2 Mole Fraction in Air or Surface + Seawater (XCO2ATM or XCO2SSW, respectively). + + Parameters + ---------- + xco2 : float or array-like + CO2 mole fraction in air or surface seawater [ppm] (XCO2ATM_LO or XCO2SSW_L0). + p : float or array-like + Gas stream pressure [mbar] (PRESAIR_L0). + std : float, optional + Standard atmospheric pressure [mbar/atm], default is 1013.25. + + Returns + ------- + ppres : float or array-like + Partial pressure of CO2 in air or surface seawater [uatm] (PCO2ATM_L1 or PCO2SSW_L1). + + References + ---------- + OOI (2012). Data Product Specification for Partial Pressure of CO2 in Air and Surface Seawater. Document Control Number 1341-00260. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> 1341-00260_Data_Product_SPEC_PCO2ATM_PCO2SSW_OOI.pdf) """ ppres = xco2 * p / std return ppres @@ -417,39 +349,34 @@ def pco2_ppressure(xco2, p, std=1013.25): def pco2_co2flux(pco2w, pco2a, u10, t, s): """ - Description: - - OOI Level 2 core date product CO2FLUX is an estimate of the CO2 flux - from the ocean to the atmosphere. It is computed using data from the - pCO2 air-sea (PCO2A) and bulk meteorology (METBK) families of - instruments. - - Implemented by: - - 2012-03-28: Mathias Lankhorst. Original Matlab code. - 2013-04-20: Christopher Wingard. Initial python code. - - Usage: - - flux = pco2_co2flux(pco2w, pco2a, u10, t, s) - - where - - flux = estimated flux of CO2 from the ocean to atmosphere [mol m-2 s-1] - (CO2FLUX_L2) - pco2w = partial pressure of CO2 in sea water [uatm] (PCO2SSW_L1) - pco2a = partial pressure of CO2 in air [uatm] (PCO2ATM_L1) - u10 = normalized wind speed at 10 m height from METBK [m s-1] (WIND10M_L2) - t = sea surface temperature from METBK [deg_C] (TEMPSRF_L1) - s = sea surface salinity from METBK [psu] (SALSURF_L2) - - References: - - OOI (2012). Data Product Specification for Flux of CO2 into the - Atmosphere. Document Control Number 1341-00270. - https://alfresco.oceanobservatories.org/ (See: Company Home >> - OOI >> Controlled >> 1000 System Level >> - 1341-00270_Data_Product_SPEC_CO2FLUX_OOI.pdf) + Estimates the CO2 flux from the ocean to the atmosphere (CO2FLUX_L2) using data from the + pCO2 air-sea (PCO2A) and bulk meteorology (METBK) families of instruments. + + Parameters + ---------- + pco2w : array_like + Partial pressure of CO2 in sea water [uatm] (PCO2SSW_L1). + pco2a : array_like + Partial pressure of CO2 in air [uatm] (PCO2ATM_L1). + u10 : array_like + Normalized wind speed at 10 m height [m s-1] (WIND10M_L2). + t : array_like + Sea surface temperature [deg_C] (TEMPSRF_L1). + s : array_like + Sea surface salinity [psu] (SALSURF_L2). + + Returns + ------- + flux : array_like + Estimated flux of CO2 from the ocean to atmosphere [mol m-2 s-1] (CO2FLUX_L2). + + References + ---------- + OOI (2012). Data Product Specification for Flux of CO2 into the Atmosphere. + Document Control Number 1341-00270. + https://alfresco.oceanobservatories.org/ (See: Company Home >> + OOI >> Controlled >> 1000 System Level >> + 1341-00270_Data_Product_SPEC_CO2FLUX_OOI.pdf) """ # convert micro-atm to atm pco2a = pco2a / 1.0e6 diff --git a/ion_functions/data/ctd_functions.py b/ion_functions/data/ctd_functions.py index 37e1f00..46b64de 100644 --- a/ion_functions/data/ctd_functions.py +++ b/ion_functions/data/ctd_functions.py @@ -1,53 +1,145 @@ #!/usr/bin/env python -""" -@package ion_functions.data.ctd_functions -@file ion_functions/data/ctd_functions.py -@author Christopher Wingard -@brief Module containing CTD related data-calculations. -""" - -# Import Numpy and the GSW library -import numpy as np -import gsw - -def ctd_sbe16plus_tempwat(t0, a0, a1, a2, a3): - """ - Description: - - OOI Level 1 Water Temperature data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - This data product is derived from SBE 16Plus instruments and applies to - CTDBP instruments, all series, and CTDPF instruments, series A and B. +# @package ion_functions.data.ctd_functions +# @file ion_functions/data/ctd_functions.py +# @author Christopher Wingard +# @brief Module containing CTD related data-calculations. - Implemented by: - - 2013-04-12: Luke Campbell. Initial Code - 2013-04-12: Christopher Wingard. Minor edits - 2013-05-10: Christopher Wingard. Minor edits to comments. - 2014-01-31: Russell Desiderio. Standardized comment format. - 2023-08-15: Samuel Dahlberg. Removed use of numexpr +""" +# Outline +The CTD instruments measure temperature, conductivity, and pressure (depth), +density, and practical salinity of the water column. The data products derived +from these measurements are: + + * \\(\\text{TEMPWAT_L1}\\): Water Temperature + * \\(\\text{PRESWAT_L1}\\): Pressure (Depth) + * \\(\\text{CONDWAT_L1}\\): Conductivity + * \\(\\text{PRACSAL_L2}\\): Practical Salinity + * \\(\\text{DENSITY_L2}\\): Density + +General theoretical background for each is provided in the Theory section, while +algorithm implementation specifics for each data product are provided in the +corresponding function docstring. + + +# Theory + +## Pressure +Absolute pressure is one of the variables directly measured by CTD instruments +and is calculated from the raw hexadecimal data provided by the instrument. +The \\(\\text{SBE 16plusV2}\\) model will output "raw frequencies and voltages in hexadecimal" +as it is referred to in the Sea-Bird manuals. The \\(\\text{37IM}\\) model will output +"engineering units in Hex". This requires that the L0 pressure data product, +which is a hexadecimal string, be converted to decimal and scaled according to +the CTD manual (different for each CTD make/model). Conversion and scaling +(described herein) results in sea pressure in decibars (dbar). +Note that the data product is named Pressure (Depth) because, though depth is +not calculated, 1 dbar in pressure is approximately equal to one meter in depth. + +It is worth noting that sea pressure is not exactly the same as the hydrostatic +pressure of the water column. The CTD's internal pressure sensor measures +absolute pressure: the pressure of the water column (hydrostatic pressure) +plus the current atmospheric pressure at the sea surface. Sea pressure is +calculated by the CTD's internal software by subtracting one standard +atmosphere from the measured absolute pressure. Because the actual atmospheric +pressure is not necessarily exactly one standard atmosphere, sea pressure is +not necessarily identical to the hydrostatic pressure. +Also, Sea-Bird uses a slightly different constant for one atmosphere: +according to their manuals, the CTDs internal software converts absolute +pressure to sea pressure by subtracting +\\(14.7 \\text{psi} * 0.689476 \\text{dbar}/\\text{psi} = 10.1352972 \\text{dbar}\\). +This is different from the TEOS-10 standard atmospheric pressure of +\\(101325 \\text{Pa}\\) or \\(10.1325 \\text{dbar}\\). +Sea pressure is the pressure measurement that is provided by the CTD (in hex +and with some scaling) when the output format is set to deliver the data in +"engineering units", as it is for the 37 IM CTDs. Therefore to back calculate +absolute pressure in psia from dbar for the 37 IM data, use the +Sea-Bird-specified conversion: +$$ + \\text{P37IM} (\\text{psia}) = \\frac{\\text{P37IM} (\\text{dbar})}{0.689476} + 14.7 +$$ +The conversion between \\text{psia}\\ and \\text{dbar}\\ for the \\text{P16plusV2}\\ +follows the TEOS-10 conventions using a "standard atmosphere": +$$ + \\text{P16plusV2} (\\text{dbar}) = 0.689475729 * \\text{P16plusV2} (\\text{psia}) - 10.1325 +$$ +Note that the raw data from the GPCTD make/model—the CTDs on board the gliders +and autonomous underwater vehicles (AUVs)—are processed onboard the vehicles +with proprietary software from the vehicle vendors. These data are presented +already in decimal format in appropriate units (\\(\\text{°C}, \\text{Siemens/meter}, \\text{decibars}\\)), +therefore processing raw hexadecimal data from the CTDGP is not included in the +algorithm described in this document. + + +## Conductivity + +Water conductivity is one of the variables directly measured by CTD instruments and is calculated +from the raw hexadecimal data provided by the instrument. The \\(\\text{SBE 16plusV2}\\) model outputs +raw frequencies and voltages in hexadecimal. The \\(\\text{37IM}\\) model outputs engineering units in Hex. +This requires that the \\(\\text{L0}\\) conductivity data +product output from the CTD driver be converted from hexadecimal string to decimal +and scaled according to the CTD manual (different for each CTD make/model). Conversion and +scaling (described below) results in conductivity in \\(\\text{S/m}\\) based on factory calibration of +conductivity. Note that conductivity calibration scales with pressure and are handled in the +Conductivity Compensation DPS (DCN 1341-10030). See Sea-Bird App Note 10 (2008) for more +details. This is because conductivity cells measure the conductance of a specific geometry of +seawater within the conductivity cell and the ratio of the length of the cell to the cross sectional +area will be deformed slightly with changes to the ambient pressure surrounding the cell. + +### Mathematical Theory +The CTD is received by OOI calibrated from Sea-Bird before its initial deployment. Post-initial +deployment calibration checks and/or recalibrations will be performed at Sea-Bird. The factory-calibrated +conductivity is converted to a hexadecimal string aboard the CTD instrument. +This hexadecimal string, after it is separated from the rest of the data stream by the +CTD driver, is the L0 conductivity data product. The parsing instructions for the instrument +hexadecimal string can be found in Appendix A. +The L1 conductivity data product algorithm takes the L0 conductivity data product and converts it +into Siemens per meter \\(\\text{S/m}\\). Once the hexadecimal conductivity string is converted to decimal, +several simple calculations are necessary to produce the correct decimal floating representation +of the data in Siemens per meter \\(\\text{S/m}\\). The conversion differs by CTD make/model. +""" - Usage: - t = ctd_sbe16plus_tempwat(t0, a0, a1, a2, a3) - where +import gsw - t = sea water temperature (TEMPWAT_L1) [deg_C] - t0 = raw temperature (TEMPWAT_L0) [counts] - a0 = temperature calibration coefficients - a1 = temperature calibration coefficients - a2 = temperature calibration coefficients - a3 = temperature calibration coefficients +# Import Numpy and the GSW library +import numpy as np - References: - OOI (2012). Data Product Specification for Water Temperature. Document - Control Number 1341-00010. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00010_Data_Product_SPEC_TEMPWAT_OOI.pdf) +def ctd_sbe16plus_tempwat(t0, a0, a1, a2, a3): + """ + Calculates the OOI Level 1 Water Temperature data product using data from Sea-Bird Electronics CTD instruments. + + This function is for SBE 16Plus instruments and applies to CTDBP instruments (all series) and CTDPF instruments (series A and B). + + Parameters + ---------- + t0 : float + Raw temperature (TEMPWAT_L0) [counts]. + a0 : float + Temperature calibration coefficient. + a1 : float + Temperature calibration coefficient. + a2 : float + Temperature calibration coefficient. + a3 : float + Temperature calibration coefficient. + + Returns + ------- + float + Sea water temperature (TEMPWAT_L1) [deg_C]. + + Examples + -------- + >>> ctd_sbe16plus_tempwat(123456, 1.0, 2.0, 3.0, 4.0) + 0.123456 + + Historical References + --------------------- + [1] OOI (2012). Data Product Specification for Water Temperature. Document + Control Number 1341-00010. """ mv = (t0 - 524288) / 1.6e7 @@ -57,43 +149,33 @@ def ctd_sbe16plus_tempwat(t0, a0, a1, a2, a3): def ctd_sbe37im_tempwat_instrument_recovered(t0, a0, a1, a2, a3): + """Calculates the OOI Level 1 Water Temperature data product from SBE 37IM + CTD instrument data. This function computes the sea water temperature using + raw temperature data recovered directly from the CTD instrument. + + Parameters + ---------- + t0 : array_like or float + Raw temperature (TEMPWAT_L0) [counts] as recovered from the CTD itself. + a0 : float + Temperature calibration coefficient. + a1 : float + Temperature calibration coefficient. + a2 : float + Temperature calibration coefficient. + a3 : float + Temperature calibration coefficient. + + Returns + ------- + t : ndarray or float + Sea water temperature (TEMPWAT_L1) in degrees Celsius. + + Notes + ----- + - Implemented for SBE 37IM instruments, all series. """ - Description: - - OOI Level 1 Water Temperature data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - This data product is derived from SBE 37IM instruments, all series, and - specifically processes data recovered directly from the CTD itself. - - Implemented by: - - 2016-06-16: Russell Desiderio. Initial Code - 2023-08-15: Samuel Dahlberg. Removed use of numexpr - - Usage: - - t = ctd_sbe37im_tempwat_instrument_recovered(t0, a0, a1, a2, a3) - - where - - t = sea water temperature (TEMPWAT_L1) [deg_C] - t0 = raw temperature (TEMPWAT_L0) [counts] as recovered from the CTD itself - a0 = temperature calibration coefficient - a1 = temperature calibration coefficient - a2 = temperature calibration coefficient - a3 = temperature calibration coefficient - - References: - - As of June 2016 the following DPS does not contain this specification. - - OOI (2012). Data Product Specification for Water Temperature. Document - Control Number 1341-00010. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00010_Data_Product_SPEC_TEMPWAT_OOI.pdf) - """ t = 1 / (a0 + a1 * np.log(t0) + a2 * np.log(t0)**2 + a3 * np.log(t0)**3) - 273.15 return t @@ -101,35 +183,24 @@ def ctd_sbe37im_tempwat_instrument_recovered(t0, a0, a1, a2, a3): def ctd_sbe37im_tempwat(t0): """ - Description: - - OOI Level 1 Water Temperature data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - - This data product is derived from SBE 37IM instruments and applies to - CTDMO instruments, all series, and specifically processes telemetered and - recovered_host (not recovered_instrument) data. - - Implemented by: - - 2014-02-05: Russell Desiderio. Initial Code - - Usage: - - t = ctd_sbe37im_tempwat(t0) - - where - - t = sea water temperature (TEMPWAT_L1) [deg_C] - t0 = raw temperature (TEMPWAT_L0) [counts] - - References: - - OOI (2012). Data Product Specification for Water Temperature. Document - Control Number 1341-00010. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00010_Data_Product_SPEC_TEMPWAT_OOI.pdf) + Calculates the OOI Level 1 Water Temperature data product using data from Sea-Bird Electronics SBE 37IM CTD instruments. + + Parameters + ---------- + t0 : float or array_like + Raw temperature (TEMPWAT_L0) [counts]. + + Returns + ------- + float or ndarray + Sea water temperature (TEMPWAT_L1) [deg_C]. + + Historical References + --------------------- + OOI (2012). Data Product Specification for Water Temperature. Document + Control Number 1341-00010. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> + 1341-00010_Data_Product_SPEC_TEMPWAT_OOI.pdf) """ t = t0 / 10000.0 - 10.0 @@ -138,93 +209,88 @@ def ctd_sbe37im_tempwat(t0): def ctd_sbe52mp_tempwat(t0): """ - Description: - - OOI Level 1 Water Temperature data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - - This data product is derived from SBE 52MP instruments and applies to - CTDPF instruments, C,K,L series. - - Implemented by: - - 2014-02-17: Russell Desiderio. Initial Code - - Usage: - - t = ctd_sbe52mp_tempwat(t0) - - where - - t = sea water temperature (TEMPWAT_L1) [deg_C] - t0 = raw temperature (TEMPWAT_L0) [counts] - - References: - - OOI (2012). Data Product Specification for Water Temperature. Document - Control Number 1341-00010. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00010_Data_Product_SPEC_TEMPWAT_OOI.pdf) + Calculate sea water temperature from raw SBE 52MP CTD instrument counts + for CTDPF instruments, C,K,L series. + + Parameters + ---------- + t0 : array_like or float + Raw temperature counts from the SBE 52MP CTD instrument (TEMPWAT_L0). + + Returns + ------- + t : ndarray or float + Sea water temperature in degrees Celsius (TEMPWAT_L1). + + Notes + ----- + This function implements the OOI Level 1 Water Temperature data product + calculation for SBE 52MP CTD instruments (CTDPF, C/K/L series). + + Historical References + --------------------- + OOI (2012). Data Product Specification for Water Temperature. + Document Control Number 1341-00010. """ t = t0 / 10000.0 - 5.0 return t -def ctd_sbe16plus_preswat(p0, t0, ptempa0, ptempa1, ptempa2, - ptca0, ptca1, ptca2, ptcb0, ptcb1, ptcb2, - pa0, pa1, pa2, offset=0): +def ctd_sbe16plus_preswat(p0, t0, ptempa0, ptempa1, ptempa2,ptca0, ptca1, ptca2, ptcb0, ptcb1, ptcb2, + pa0, pa1, pa2, offset=0): """ - Description: - - OOI Level 1 Pressure (Depth) data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - - This data product is derived from SBE 16Plus instruments outfitted with - a strain gauge pressure sensor. This is the default for most of the CTDBP - instruments (the exceptions are series N and O) and for CTDPF instruments, - series A and B. - - Implemented by: - - 2013-04-12: Chris Wingard. Initial Code. - 2013-05-10: Christopher Wingard. Minor edits to comments. - 2014-01-31: Russell Desiderio. Standardized comment format. - 2017-03-31: Dan Mergens. Update to correct adjust for Druck offset. - - Usage: - - p = ctd_sbe16plus_preswat(p0, t0, ptempa0, ptempa1, ptempa2, - ptca0, ptca1, ptca2, ptcb0, ptcb1, ptcb2, - pa0, pa1, pa2, offset) - - where - - p = sea water pressure (PRESWAT_L1) [dbar] - p0 = raw pressure (PRESWAT_L0) [counts] - t0 = raw temperature from pressure sensor thermistor [counts] - ptempa0 = strain gauge pressure calibration coefficients - ptempa1 = strain gauge pressure calibration coefficients - ptempa2 = strain gauge pressure calibration coefficients - ptca0 = strain gauge pressure calibration coefficients - ptca1 = strain gauge pressure calibration coefficients - ptca2 = strain gauge pressure calibration coefficients - ptcb0 = strain gauge pressure calibration coefficients - ptcb1 = strain gauge pressure calibration coefficients - ptcb2 = strain gauge pressure calibration coefficients - pa0 = strain gauge pressure calibration coefficients - pa1 = strain gauge pressure calibration coefficients - pa2 = strain gauge pressure calibration coefficients - offset = correction for Druck error [dbar] - - References: - - OOI (2012). Data Product Specification for Pressure (Depth). Document - Control Number 1341-00020. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00020_Data_Product_SPEC_PRESWAT_OOI.pdf) + Calculates the OOI Level 1 Pressure (Depth) data product from raw sensor counts + and calibration coefficients for Sea-Bird Electronics SBE 16Plus CTD instruments + with a strain gauge pressure sensor. + + Parameters + ---------- + p0 : float or array-like + Raw pressure (PRESWAT_L0) [counts]. + t0 : float or array-like + Raw temperature from pressure sensor thermistor [counts]. + ptempa0 : float + Strain gauge pressure calibration coefficient. + ptempa1 : float + Strain gauge pressure calibration coefficient. + ptempa2 : float + Strain gauge pressure calibration coefficient. + ptca0 : float + Strain gauge pressure calibration coefficient. + ptca1 : float + Strain gauge pressure calibration coefficient. + ptca2 : float + Strain gauge pressure calibration coefficient. + ptcb0 : float + Strain gauge pressure calibration coefficient. + ptcb1 : float + Strain gauge pressure calibration coefficient. + ptcb2 : float + Strain gauge pressure calibration coefficient. + pa0 : float + Strain gauge pressure calibration coefficient. + pa1 : float + Strain gauge pressure calibration coefficient. + pa2 : float + Strain gauge pressure calibration coefficient. + offset : float, optional + Correction for Druck error [dbar]. Default is 0. + + Returns + ------- + p : float or array-like + Sea water pressure (PRESWAT_L1) [dbar]. + Notes + ----- + - This data product is derived from SBE 16Plus instruments outfitted with + a strain gauge pressure sensor. This is the default for most of the CTDBP + instruments (the exceptions are series N and O) and for CTDPF instruments, + series A and B. + + Historical References + --------------------- + OOI (2012). Data Product Specification for Pressure (Depth). Document Control Number 1341-00020. """ # compute calibration parameters tv = t0 / 13107.0 @@ -240,56 +306,49 @@ def ctd_sbe16plus_preswat(p0, t0, ptempa0, ptempa1, ptempa2, def ctd_sbe16digi_preswat(p0, t0, C1, C2, C3, D1, D2, T1, T2, T3, T4, T5): """ - Description: - - OOI Level 1 Pressure (Depth) data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - - This data product is derived from SBE 16Plus instruments outfitted with - a digiquartz pressure sensor. This applies to the CTDBP-N,O instruments - only. - - Implemented by: - - 2013-05-10: Christopher Wingard. Initial Code. - 2013-05-10: Christopher Wingard. Minor edits to comments. - 2014-01-31: Russell Desiderio. Standardized comment format. - 2014-01-31: Russell Desiderio. Modified algorithm to use pressure [Hz] (pf) - to calculate pressure period instead of pressure [counts] (p0). - See SeaBird 16Plus V2 User Manual (reference (2)), page 57, item 5. - - Usage: - - p = ctd_sbe16digi_preswat(p0,t0,C1,C2,C3,D1,D2,T1,T2,T3,T4,T5) - - where - - p = sea water pressure (PRESWAT_L1) [dbar] - p0 = raw pressure (PRESWAT_L0) [counts] - t0 = raw temperature from pressure sensor thermistor [counts] - C1 = digiquartz pressure calibration coefficients - C2 = digiquartz pressure calibration coefficients - C3 = digiquartz pressure calibration coefficients - D1 = digiquartz pressure calibration coefficients - D2 = digiquartz pressure calibration coefficients - T1 = digiquartz pressure calibration coefficients - T2 = digiquartz pressure calibration coefficients - T3 = digiquartz pressure calibration coefficients - T4 = digiquartz pressure calibration coefficients - T5 = digiquartz pressure calibration coefficients - - References: - - OOI (2012). Data Product Specification for Pressure (Depth). Document - Control Number 1341-00020. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00020_Data_Product_SPEC_PRESWAT_OOI.pdf) - - OOI (2011). SeaBird 16Plus V2 User Manual. 1341-00020_PRESWAT Artifact. - https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI >> - >> REFERENCE >> Data Product Specification Artifacts >> 1341-00020_PRESWAT >> - PRESWAT_SeaBird_16PlusV2_2009.pdf) + Calculates the OOI Level 1 Pressure (Depth) data product for SBE 16Plus instruments + outfitted with a digiquartz pressure sensor (CTDBP-N,O instruments only). + + Parameters + ---------- + p0 : float or array_like + Raw pressure (PRESWAT_L0) [counts]. + t0 : float or array_like + Raw temperature from pressure sensor thermistor [counts]. + C1 : float + Digiquartz pressure calibration coefficient. + C2 : float + Digiquartz pressure calibration coefficient. + C3 : float + Digiquartz pressure calibration coefficient. + D1 : float + Digiquartz pressure calibration coefficient. + D2 : float + Digiquartz pressure calibration coefficient. + T1 : float + Digiquartz pressure calibration coefficient. + T2 : float + Digiquartz pressure calibration coefficient. + T3 : float + Digiquartz pressure calibration coefficient. + T4 : float + Digiquartz pressure calibration coefficient. + T5 : float + Digiquartz pressure calibration coefficient. + + Returns + ------- + float or ndarray + Sea water pressure (PRESWAT_L1) [dbar]. + + Notes + ----- + - Applies to CTDBP-N,O instruments only. + + Historical References + --------------------- + OOI (2012). Data Product Specification for Pressure (Depth). Document Control Number 1341-00020. + OOI (2011). SeaBird 16Plus V2 User Manual. 1341-00020_PRESWAT Artifact. """ # Convert raw pressure input to frequency [Hz] pf = p0 / 256.0 @@ -318,51 +377,51 @@ def ctd_sbe37im_preswat_instrument_recovered(p0, pt0, ptempa0, ptempa1, ptempa2, ptca0, ptca1, ptca2, ptcb0, ptcb1, ptcb2, pa0, pa1, pa2): """ - Description: - - OOI Level 1 Pressure (Depth) data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - - This data product is derived from SBE 37IM instruments, all series, and - specifically processes data recovered directly from the CTD itself. - - Implemented by: - - 2016-06-16: Russell Desiderio. Initial Code - - Usage: - - p = ctd_sbe37im_preswat_instrument_recovered(p0, pt0, ptempa0, ptempa1, ptempa2, - ptca0, ptca1, ptca2, ptcb0, ptcb1, ptcb2, - pa0, pa1, pa2) - - where - - p = sea water pressure (PRESWAT_L1) [dbar] - p0 = raw pressure (PRESWAT_L0) [counts] as recovered from the CTD itself - pt0 = raw temperature from pressure sensor thermistor [counts] - ptempa0 = strain gauge pressure calibration coefficients - ptempa1 = strain gauge pressure calibration coefficients - ptempa2 = strain gauge pressure calibration coefficients - ptca0 = strain gauge pressure calibration coefficients - ptca1 = strain gauge pressure calibration coefficients - ptca2 = strain gauge pressure calibration coefficients - ptcb0 = strain gauge pressure calibration coefficients - ptcb1 = strain gauge pressure calibration coefficients - ptcb2 = strain gauge pressure calibration coefficients - pa0 = strain gauge pressure calibration coefficients - pa1 = strain gauge pressure calibration coefficients - pa2 = strain gauge pressure calibration coefficients - - References: - - As of June 2016 the following DPS does not contain this specification. - - OOI (2012). Data Product Specification for Pressure (Depth). Document - Control Number 1341-00020. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00020_Data_Product_SPEC_PRESWAT_OOI.pdf) + Calculates the OOI Level 1 Pressure (Depth) data product from SBE 37IM instrument data + recovered directly from the CTD itself. + + Parameters + ---------- + p0 : float or array_like + Raw pressure (PRESWAT_L0) [counts] as recovered from the CTD itself. + pt0 : float or array_like + Raw temperature from pressure sensor thermistor [counts]. + ptempa0 : float + Strain gauge pressure calibration coefficient. + ptempa1 : float + Strain gauge pressure calibration coefficient. + ptempa2 : float + Strain gauge pressure calibration coefficient. + ptca0 : float + Strain gauge pressure calibration coefficient. + ptca1 : float + Strain gauge pressure calibration coefficient. + ptca2 : float + Strain gauge pressure calibration coefficient. + ptcb0 : float + Strain gauge pressure calibration coefficient. + ptcb1 : float + Strain gauge pressure calibration coefficient. + ptcb2 : float + Strain gauge pressure calibration coefficient. + pa0 : float + Strain gauge pressure calibration coefficient. + pa1 : float + Strain gauge pressure calibration coefficient. + pa2 : float + Strain gauge pressure calibration coefficient. + + Returns + ------- + p_dbar : float or ndarray + Sea water pressure (PRESWAT_L1) [dbar]. + + Historical References + --------------------- + OOI (2012). Data Product Specification for Pressure (Depth). Document + Control Number 1341-00020. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> + 1341-00020_Data_Product_SPEC_PRESWAT_OOI.pdf) """ # compute calibration parameters t = ptempa0 + ptempa1 * pt0 + ptempa2 * pt0**2 @@ -377,36 +436,25 @@ def ctd_sbe37im_preswat_instrument_recovered(p0, pt0, ptempa0, ptempa1, ptempa2, def ctd_sbe37im_preswat(p0, p_range_psia): """ - Description: - - OOI Level 1 Pressure (Depth) data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - - This data product is derived from SBE 37IM instruments and applies to - CTDMO instruments, all series, and specifically processes telemetered and - recovered_host (not recovered_instrument) data. - - Implemented by: - - 2014-02-05: Russell Desiderio. Initial Code - - Usage: - - p = ctd_sbe37im_preswat(p0, p_range_psia) - - where - - p = sea water pressure (PRESWAT_L1) [dbar] - p0 = raw pressure (PRESWAT_L0) [counts] - p_range_psia = pressure range calibration coefficient [psia] - - References: - - OOI (2012). Data Product Specification for Pressure (Depth). Document - Control Number 1341-00020. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00020_Data_Product_SPEC_PRESWAT_OOI.pdf) + Calculates the OOI Level 1 Pressure (Depth) data product using data from Sea-Bird Electronics SBE 37IM CTD instruments. + + Parameters + ---------- + p0 : float or array_like + Raw pressure (PRESWAT_L0) [counts]. + p_range_psia : float + Pressure range calibration coefficient [psia]. + + Returns + ------- + float or ndarray + Sea water pressure (PRESWAT_L1) [dbar]. + + Historical References + --------------------- + OOI (2012). Data Product Specification for Pressure (Depth). Document Control Number 1341-00020. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> + 1341-00020_Data_Product_SPEC_PRESWAT_OOI.pdf) """ # compute pressure range in units of dbar p_range_dbar = (p_range_psia - 14.7) * 0.6894757 @@ -418,35 +466,24 @@ def ctd_sbe37im_preswat(p0, p_range_psia): def ctd_glider_preswat(pr_bar): """ - Description: - - OOI Level 1 Pressure (Depth) data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - - This data product is derived from Seabird CTDs installed on gliders and - applies to CTDGV instruments. - - Implemented by: - - 2015-10-28: Russell Desiderio. Initial Code - - Usage: - - pr_dbar = ctd_glider_preswat(pr_bar) - - where - - pr_dbar = sea water pressure (PRESWAT_L1) [dbar] - pr_bar = sea water pressure value from glider [bar] - - References: - - OOI (2015). Data Product Specification for Coastal Glider Data Products - (version 1-03). Document Control Number 1341-00020. - https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-20001_Data_Product_SPEC_CSGLIDR_OOI.docx) + Calculates the OOI Level 1 Pressure (Depth) data product for Seabird CTDs installed on gliders (CTDGV instruments). + + Parameters + ---------- + pr_bar : float or array_like + Sea water pressure value from glider [bar]. + + Returns + ------- + pr_dbar : float or ndarray + Sea water pressure (PRESWAT_L1) [dbar]. + + Historical References + --------------------- + OOI (2015). Data Product Specification for Coastal Glider Data Products (version 1-03). + Document Control Number 1341-00020. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> + 1341-20001_Data_Product_SPEC_CSGLIDR_OOI.docx) """ pr_dbar = pr_bar * 10.0 @@ -455,34 +492,27 @@ def ctd_glider_preswat(pr_bar): def ctd_sbe52mp_preswat(p0): """ - Description: - - OOI Level 1 Pressure (Depth) data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - - This data product is derived from SBE 52MP instruments and applies to - CTDPF instruments, C,K,L series. - - Implemented by: - - 2014-02-17: Russell Desiderio. Initial Code - - Usage: - - p = ctd_sbe52mp_preswat(p0) - - where - - p = sea water pressure (PRESWAT_L1) [dbar] - p0 = raw pressure (PRESWAT_L0) [counts] - - References: - - OOI (2012). Data Product Specification for Pressure (Depth). Document - Control Number 1341-00020. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00020_Data_Product_SPEC_PRESWAT_OOI.pdf) + Calculates the OOI Level 1 Pressure (Depth) data product using data from Sea-Bird Electronics SBE 52MP CTD instruments. + + Parameters + ---------- + p0 : float or array_like + Raw pressure (PRESWAT_L0) [counts]. + + Returns + ------- + p_dbar : float or ndarray + Sea water pressure (PRESWAT_L1) [dbar]. + + Notes + ----- + - This data product is derived from SBE 52MP instruments and applies to CTDPF instruments, C/K/L series. + + Historical References + --------------------- + OOI (2012). Data Product Specification for Pressure (Depth). Document Control Number 1341-00020. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> + 1341-00020_Data_Product_SPEC_PRESWAT_OOI.pdf) """ p_dbar = p0 / 100.0 - 10.0 @@ -491,44 +521,43 @@ def ctd_sbe52mp_preswat(p0): def ctd_sbe16plus_condwat(c0, t1, p1, g, h, i, j, cpcor, ctcor): """ - Description: - - OOI Level 1 Conductivity core data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - - This data product is derived from SBE 16Plus instruments and applies to - CTDBP instruments, all series, and CTDPF instruments, series A and B. - - Implemented by: - - 2013-04-12: Christopher Wingard. Initial Code - 2013-05-10: Christopher Wingard. Minor edits to comments. - 2014-01-31: Russell Desiderio. Standardized comment format. - - Usage: - - c = ctd_sbe16plus_condwat(c0, t1, p1, g, h, i, j, cpcor, ctcor) - - where - - c = sea water conductivity (CONDWAT_L1) [S m-1] - c0 = sea water conductivity (CONDWAT_L0) [counts] - t1 = sea water temperature (TEMPWAT_L1) [deg_C] - p1 = sea water pressure (PRESWAT_L1) [dbar] - g = conductivity calibration coefficients - h = conductivity calibration coefficients - i = conductivity calibration coefficients - j = conductivity calibration coefficients - cpcor = conductivity calibration coefficients - ctcor = conductivity calibration coefficients - - References: - - OOI (2012). Data Product Specification for Conductivity. Document - Control Number 1341-00030. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00030_Data_Product_SPEC_CONDWAT_OOI.pdf) + Calculates the OOI Level 1 Conductivity core data product using data from Sea-Bird Electronics SBE 16Plus CTD instruments. + + Parameters + ---------- + c0 : float or array_like + Raw conductivity (CONDWAT_L0) [counts]. + t1 : float or array_like + Sea water temperature (TEMPWAT_L1) [deg_C]. + p1 : float or array_like + Sea water pressure (PRESWAT_L1) [dbar]. + g : float + Conductivity calibration coefficient. + h : float + Conductivity calibration coefficient. + i : float + Conductivity calibration coefficient. + j : float + Conductivity calibration coefficient. + cpcor : float + Conductivity calibration coefficient. + ctcor : float + Conductivity calibration coefficient. + + Returns + ------- + c : float or ndarray + Sea water conductivity (CONDWAT_L1) [S m-1]. + + Notes + ----- + - This data product is derived from SBE 16Plus instruments and applies to CTDBP instruments (all series) and CTDPF instruments (series A and B). + + Historical References + --------------------- + OOI (2012). Data Product Specification for Conductivity. Document Control Number 1341-00030. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> + 1341-00030_Data_Product_SPEC_CONDWAT_OOI.pdf) """ # convert raw conductivity measurement to frequency f = (c0 / 256.0) / 1000.0 @@ -540,46 +569,46 @@ def ctd_sbe16plus_condwat(c0, t1, p1, g, h, i, j, cpcor, ctcor): def ctd_sbe37im_condwat_instrument_recovered(c0, t1, p1, g, h, i, j, cpcor, ctcor, wbotc): """ - Description: - - OOI Level 1 Conductivity core data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - - This data product is derived from SBE 37IM instruments, all series, and - specifically processes data recovered directly from the CTD itself. - - Implemented by: - - 2016-06-16: Russell Desiderio. Initial Code - 2023-08-15: Samuel Dahlberg. Removed use of numexpr - - Usage: - - c = ctd_sbe37im_condwat_instrument_recovered(c0, t1, p1, g, h, i, j, cpcor, ctcor, wbotc) - - where - - c = sea water conductivity (CONDWAT_L1) [S m-1] - c0 = sea water conductivity (CONDWAT_L0) [counts] as recovered from the CTD itself - t1 = sea water temperature (TEMPWAT_L1) [deg_C] - p1 = sea water pressure (PRESWAT_L1) [dbar] - g = conductivity calibration coefficients - h = conductivity calibration coefficients - i = conductivity calibration coefficients - j = conductivity calibration coefficients - cpcor = conductivity calibration coefficients - ctcor = conductivity calibration coefficients - wbotc = conductivity calibration coefficients - - References: - - As of June 2016 the following DPS does not contain this specification. - - OOI (2012). Data Product Specification for Conductivity. Document - Control Number 1341-00030. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00030_Data_Product_SPEC_CONDWAT_OOI.pdf) + Calculates the OOI Level 1 Conductivity core data product using data from Sea-Bird Electronics SBE 37IM CTD instruments. + + Parameters + ---------- + c0 : float or array_like + Raw conductivity (CONDWAT_L0) [counts] as recovered from the CTD itself. + t1 : float or array_like + Sea water temperature (TEMPWAT_L1) [deg_C]. + p1 : float or array_like + Sea water pressure (PRESWAT_L1) [dbar]. + g : float + Conductivity calibration coefficient. + h : float + Conductivity calibration coefficient. + i : float + Conductivity calibration coefficient. + j : float + Conductivity calibration coefficient. + cpcor : float + Conductivity calibration coefficient. + ctcor : float + Conductivity calibration coefficient. + wbotc : float + Conductivity calibration coefficient. + + Returns + ------- + c : float or ndarray + Sea water conductivity (CONDWAT_L1) [S m-1]. + + Notes + ----- + - This data product is derived from SBE 37IM instruments, all series, and specifically processes data recovered directly from the CTD itself. + + Historical References + --------------------- + As of June 2016 the following DPS does not contain this specification. + + OOI (2012). Data Product Specification for Conductivity. Document Control Number 1341-00030. + https://alfresco.oceanobservatories.org/ (See: Company Home >> OOI >> Controlled >> 1000 System Level >> 1341-00030_Data_Product_SPEC_CONDWAT_OOI.pdf) """ # convert raw conductivity measurement to frequency f = (c0 / 256.0) / 1000.0 * np.sqrt(1.0 + wbotc * t1) @@ -591,36 +620,26 @@ def ctd_sbe37im_condwat_instrument_recovered(c0, t1, p1, g, h, i, j, cpcor, ctco def ctd_sbe37im_condwat(c0): """ - Description: - - OOI Level 1 Conductivity core data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - - This data product is derived from SBE 37IM instruments and applies to - CTDMO instruments, all series, and specifically processes telemetered and - recovered_host (not recovered_instrument) data. - - Implemented by: - - 2014-02-05: Russell Desiderio. Initial Code - - Usage: - - c = ctd_sbe37im_condwat(c0) - - where - - c = sea water conductivity (CONDWAT_L1) [S m-1] - c0 = sea water conductivity (CONDWAT_L0) [counts] - - References: - - OOI (2012). Data Product Specification for Conductivity. Document - Control Number 1341-00030. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00030_Data_Product_SPEC_CONDWAT_OOI.pdf) - """ + Calculates the OOI Level 1 Conductivity core data product using data from Sea-Bird Electronics SBE 37IM CTD instruments. + + Parameters + ---------- + c0 : float or array_like + Raw conductivity (CONDWAT_L0) [counts]. + + Returns + ------- + c : float or ndarray + Sea water conductivity (CONDWAT_L1) [S m-1]. + + Notes + ----- + - This data product is derived from SBE 37IM instruments and applies to CTDMO instruments, all series, specifically for telemetered and recovered_host (not recovered_instrument) data. + Historical References + --------------------- + OOI (2012). Data Product Specification for Conductivity. Document Control Number 1341-00030. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> 1341-00030_Data_Product_SPEC_CONDWAT_OOI.pdf) + """ c = c0 / 100000.0 - 0.5 return c @@ -628,35 +647,27 @@ def ctd_sbe37im_condwat(c0): def ctd_sbe52mp_condwat(c0): """ - Description: - - OOI Level 1 Conductivity core data product, which is calculated using - data from the Sea-Bird Electronics conductivity, temperature and depth - (CTD) family of instruments. - - This data product is derived from SBE 52MP instruments and applies to - CTDPF instruments, C,K,L series. - - Implemented by: - - 2014-02-17: Russell Desiderio. Initial Code - - Usage: - - c = ctd_sbe52mp_condwat(c0) - - where - - c = sea water conductivity (CONDWAT_L1) [S m-1] - c0 = sea water conductivity (CONDWAT_L0) [counts] - - References: - - OOI (2012). Data Product Specification for Conductivity. Document - Control Number 1341-00030. https://alfresco.oceanobservatories.org/ - (See: Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00030_Data_Product_SPEC_CONDWAT_OOI.pdf) - """ + Calculates the OOI Level 1 Conductivity core data product using data from Sea-Bird Electronics SBE 52MP CTD instruments. + + Parameters + ---------- + c0 : float or array_like + Raw conductivity (CONDWAT_L0) [counts]. + + Returns + ------- + c_S_m : float or ndarray + Sea water conductivity (CONDWAT_L1) [S m-1]. + + Notes + ----- + - This data product is derived from SBE 52MP instruments and applies to CTDPF instruments, C/K/L series. + + References + ---------- + OOI (2012). Data Product Specification for Conductivity. Document Control Number 1341-00030. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> 1341-00030_Data_Product_SPEC_CONDWAT_OOI.pdf) + """ c_mmho_cm = c0 / 10000.0 - 0.5 c_S_m = 0.1 * c_mmho_cm @@ -665,38 +676,31 @@ def ctd_sbe52mp_condwat(c0): def ctd_pracsal(c, t, p): """ - Description: - - OOI Level 2 Practical Salinity core data product, which is calculated - using the Thermodynamic Equations of Seawater - 2010 (TEOS-10) Version - 3.0, with data from the conductivity, temperature and depth (CTD) - family of instruments. - - Implemented by: - - 2013-03-13: Christopher Wingard. Initial code. - 2013-05-10: Christopher Wingard. Minor edits to comments. - 2014-01-31: Russell Desiderio. Standardized comment format. - 2023-08-15: Samuel Dahlberg. Replaced incompatible pygsw with GSW library. - - Usage: - - SP = ctd_pracsal(c, t, p) - - where - - SP = practical salinity, PSS-78, (PRACSAL_L2) [unitless] - c = sea water conductivity (CONDWAT_L1) [S m-1] - t = sea water temperature (TEMPWAT_L1) [deg_C] - p = sea water pressure (PRESWAT_L1) [dbar] - References: - - OOI (2012). Data Product Specification for Salinty. Document Control - Number 1341-00040. https://alfresco.oceanobservatories.org/ (See: - Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00040_Data_Product_SPEC_PRACSAL_OOI.pdf) + Calculates Practical Salinity (PSS-78) from conductivity, temperature, and pressure. + This function computes the OOI Level 2 Practical Salinity core data product using the + Thermodynamic Equations of Seawater - 2010 (TEOS-10) Version 3.0, based on input from + conductivity, temperature, and depth (CTD) instruments. + + Parameters + ---------- + c : float or array-like + Sea water conductivity (CONDWAT_L1) [S m-1]. + t : float or array-like + Sea water temperature (TEMPWAT_L1) [deg_C]. + p : float or array-like + Sea water pressure (PRESWAT_L1) [dbar]. + + Returns + ------- + SP : float or array-like + Practical salinity, PSS-78, (PRACSAL_L2) unitless. + + Historical References + --------------------- + - OOI (2012). Data Product Specification for Salinity. Document Control Number 1341-00040. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> 1341-00040_Data_Product_SPEC_PRACSAL_OOI.pdf) + - Thermodynamic Equations of Seawater - 2010 (TEOS-10) Version 3.0 """ - # Convert L1 Conductivity from S/m to mS/cm C10 = c * 10.0 @@ -707,44 +711,41 @@ def ctd_pracsal(c, t, p): def ctd_density(SP, t, p, lat, lon): """ - Description: - - OOI Level 2 Density core data product, which is calculated using the - Thermodynamic Equations of Seawater - 2010 (TEOS-10) Version 3.0, with - data from the conductivity, temperature and depth (CTD) family of - instruments. - - Implemented by: - - 2013-03-11: Christopher Mueller. Initial code. - 2013-03-13: Christopher Wingard. Added commenting and moved to - ctd_functions - 2013-05-10: Christopher Wingard. Minor edits to comments. - 2014-01-31: Russell Desiderio. Standardized comment format. - 2023-08-15: Samuel Dahlberg. Replaced incompatible pygsw with GSW library. - - Usage: - - rho = ctd_density(SP, t, p, lat, lon) - - where - - rho = sea water density (DENSITY_L2) [kg m-3] - SP = practical salinity PSS-78 (PRACSAL_L2) [unitless] - t = sea water temperature (TEMPWAT_L1) [deg_C] - p = sea water pressure (PRESWAT_L1) [dbar] - lat = latitude where input data was collected [decimal degree] - lon = longitude where input data was collected [decimal degree] - - References: - - OOI (2012). Data Product Specification for Density. Document Control - Number 1341-00050. https://alfresco.oceanobservatories.org/ (See: - Company Home >> OOI >> Controlled >> 1000 System Level >> - 1341-00050_Data_Product_SPEC_DENSITY_OOI.pdf) + Calculates the OOI Level 2 Density core data product for the conductivity, + temperature and depth (CTD) family of instruments. + + Parameters + ---------- + SP : float or array_like + Practical salinity PSS-78 (PRACSAL_L2) [unitless]. + t : float or array_like + Sea water temperature (TEMPWAT_L1) [deg_C]. + p : float or array_like + Sea water pressure (PRESWAT_L1) [dbar]. + lat : float or array_like + Latitude where input data was collected [decimal degree]. + lon : float or array_like + Longitude where input data was collected [decimal degree]. + + Returns + ------- + rho : float or ndarray + Sea water density (DENSITY_L2) [kg m-3]. + + Notes + ----- + - Uses the Thermodynamic Equations of Seawater - 2010 (TEOS-10) Version 3.0. + + Historical References + --------------------- + - OOI (2012). Data Product Specification for Density. Document Control Number 1341-00050. + (See: Company Home >> OOI >> Controlled >> 1000 System Level >> 1341-00050_Data_Product_SPEC_DENSITY_OOI.pdf) + - Thermodynamic Equations of Seawater - 2010 (TEOS-10) Version 3.0. """ # Calculate the density [kg m-3] sa = gsw.SA_from_SP(SP, p, lon, lat) # absolute salinity ct = gsw.CT_from_t(sa, t, p) # conservative temperature rho = gsw.rho(sa, ct, p) # density + # rho = gsw.ctd_density(SP, t, p, lat, lon) + return rho diff --git a/ion_functions/data/do2_functions.py b/ion_functions/data/do2_functions.py index f2a42c1..1f175ef 100644 --- a/ion_functions/data/do2_functions.py +++ b/ion_functions/data/do2_functions.py @@ -1,13 +1,21 @@ #!/usr/bin/env python +# @package ion_functions.data.do2_functions +# @file ion_functions/data/do2_functions.py +# @author Stuart Pearce, Russell Desiderio +# @brief Module containing Dissolved Oxygen family functions + """ -@package ion_functions.data.do2_functions -@file ion_functions/data/do2_functions.py -@author Stuart Pearce, Russell Desiderio -@brief Module containing Dissolved Oxygen family functions +# Overview +Module containing Dissolved Oxygen instrument family related functions. +This module implements the algorithms for calculating dissolved oxygen +concentration in seawater (DOXYGEN), converting raw voltage and counts +readings from the OOI L0 DOCONCS data product, and calculating +DOSTA (Aanderaa Optode) data products. """ -import numpy as np + import gsw +import numpy as np from ion_functions.data.generic_functions import replace_fill_with_nan diff --git a/ion_functions/data/flo_functions.py b/ion_functions/data/flo_functions.py index b2f1d20..86b1723 100644 --- a/ion_functions/data/flo_functions.py +++ b/ion_functions/data/flo_functions.py @@ -1,10 +1,18 @@ #!/usr/bin/env python + +# @package ion_functions.data.flo_functions +# @file ion_functions/data/flo_functions.py +# @author Christopher Wingard, Craig Risien, Russell Desiderio +# @brief Module containing Fluorometer Three Wavelength (FLORT) and Fluorometer +# Two Wavelength (FLORD) instrument family related functions + """ -@package ion_functions.data.flo_functions -@file ion_functions/data/flo_functions.py -@author Christopher Wingard, Craig Risien, Russell Desiderio -@brief Module containing Fluorometer Three Wavelength (FLORT) and Fluorometer - Two Wavelength (FLORD) instrument family related functions +# Overview +Module containing Fluorometer Three Wavelength (FLORT) and Fluorometer +Two Wavelength (FLORD) instrument family related functions. +This module implements the algorithms for calculating the OOI Level 2 Optical +Backscatter data product (FLUBSCT_L2) from the WET Labs, Inc. ECO +fluorometer family of instruments (FLORD, FLORT, FLNTU). """ import numpy as np diff --git a/ion_functions/data/generic_functions.py b/ion_functions/data/generic_functions.py index 0793f17..e1198d8 100755 --- a/ion_functions/data/generic_functions.py +++ b/ion_functions/data/generic_functions.py @@ -1,21 +1,29 @@ #!/usr/bin/env python -""" -@package ion_functions.data.generic_functions -@file ion_functions/data/generic_functions.py -@author Christopher Wingard, Stuart Pearce, Russell Desiderio -@brief Module containing generic data-calculation functions. Primarily - used for calculating values in Parameter Functions + +# @package ion_functions.data.generic_functions +# @file ion_functions/data/generic_functions.py +# @author Christopher Wingard, Stuart Pearce, Russell Desiderio +# @brief Module containing generic data-calculation functions. Primarily +# used for calculating values in Parameter Functions + +""" Utility functions for data processing and calculations. + +This module contains utility functions that are used across various data +processing algorithms. These functions include data type conversions, magnetic +declination calculations, and interpolation methods. + """ # Common imports import datetime -import pyIGRF as igrf -import numpy as np -import numexpr as ne -import pkg_resources import time from numbers import Integral +import numexpr as ne +import numpy as np +import pkg_resources +import pyIGRF as igrf + # CyberInfrastructure fill value for all integer data types SYSTEM_FILLVALUE = -999999999 diff --git a/ion_functions/data/hyd_functions.py b/ion_functions/data/hyd_functions.py index 92c7775..9ac388e 100644 --- a/ion_functions/data/hyd_functions.py +++ b/ion_functions/data/hyd_functions.py @@ -1,9 +1,14 @@ #!/usr/bin/env python +# @package ion_functions.data.hyd_functions +# @file ion_functions/data/hyd_functions.py +# @author Christopher Wingard +# @brief Module containing Hydrophone instrument family related functions + """ -@package ion_functions.data.hyd_functions -@file ion_functions/data/hyd_functions.py -@author Christopher Wingard -@brief Module containing Hydrophone instrument family related functions +# Overview +Module containing Hydrophone instrument family related functions. +This module implements the algorithms for calculating broadband and low frequency +acoustic pressure waves from the OOI L0 HYDBB and HYDLF data products. """ import numpy as np diff --git a/ion_functions/data/interpolation.py b/ion_functions/data/interpolation.py index d3478b7..c0683c6 100644 --- a/ion_functions/data/interpolation.py +++ b/ion_functions/data/interpolation.py @@ -1,11 +1,12 @@ #!/usr/bin/env python -''' -@package ion_functions/data/interpolation.py -@brief Functions for interpolation -''' + +# @package ion_functions/data/interpolation.py +# @brief Functions for interpolation + import numpy as np + def secondary_interpolation(x, range0, range1, starts, ends): """ Description: diff --git a/ion_functions/data/met_functions.py b/ion_functions/data/met_functions.py index 651715b..29891e1 100755 --- a/ion_functions/data/met_functions.py +++ b/ion_functions/data/met_functions.py @@ -1,73 +1,80 @@ #!/usr/bin/env python +# @package ion_functions.data.met_functions +# @file ion_functions/data/met_functions.py +# @author Russell Desiderio +# @brief Module containing functions for the met family of instruments + """ -@package ion_functions.data.met_functions -@file ion_functions/data/met_functions.py -@author Russell Desiderio -@brief Module containing functions for the met family of instruments +# Overview +Module containing functions for the met family of instruments. +This module implements the algorithms for calculating bulk meteorological +data products from the OOI L0 METBK data products. """ -import numpy as np + import gsw +import numpy as np -from ion_functions.data.generic_functions import magnetic_declination, magnetic_correction - -### July 2015 -""" use_velptmn_with_metbk """ -# Until VELPT current meters are -# (1) co-located with the METBK instrumentation to measure surface currents and -# (2) without ferrous interference aliasing the VELPT compass measurements, -# VELPT current measurements should not be used to calculate relative wind speed (with -# respect to water), which is the fundamental windspeed variable used in the METBK -# calculations. Almost all of the METBK L2 data products require the relative wind speed -# as a calling argument. -# -# The DPA to calculate relative wind speed over water is currently set to return actual -# wind speed (as if the current velocities were measured to be 0) for all cases of input -# current velocity values (absent, present, nan). -# -# A subset of the Endurance moorings are the only ones that have VELPT instruments -# mounted to measure surface currents. However, their compass readings are inaccurate due -# to the mounted instruments' proximity to iron ballast in the mooring. -# -# It is anticipated that these moorings will be modified to eliminate this magnetic -# interference. To use the velptmn measurements for METBK calculations on these moorings, -# a 5th variable, use_velptmn_with_metbk, has been added to the argument list of the -# function met_relwind_speed. Implementation of the use_velptmn_with_metbk variable will -# require that it be treated as a "platform/instrument instance specific metadata parameter -# changeable in time". It has been coded to accept time-vectorized input. -# -### Further documentation is contained in the Notes to function met_relwind_speed in this module. +from ion_functions.data.generic_functions import ( + magnetic_correction, + magnetic_declination, +) -""" - METBK SENSOR HEIGHTS +"""Module containing functions for the met family of instruments - Note that the sensor heights may depend on the type of mooring: -""" -# these 4 sensor height variables were time-vectorized in the July 2015 revision. -# zwindsp = height of the wind measurement [m] -# ztmpair = height of air temperature measurement [m] -# zhumair = height of air humidity measurement [m] -# ztmpwat = depth of bulk sea surface water measurements [m] -# zvelptm = depth of surface current measurement [m]: -# this parameter is specified as metadata in the DPS; -# however, it is not used in the code. +Until VELPT current meters are + (1) co-located with the METBK instrumentation to measure surface currents and + (2) without ferrous interference aliasing the VELPT compass measurements, +VELPT current measurements should not be used to calculate relative wind speed (with +respect to water), which is the fundamental windspeed variable used in the METBK +calculations. Almost all of the METBK L2 data products require the relative wind speed +as a calling argument. -# zinvpbl = planetary boundary layer/inversion height: this is -# set to a default value of 600m in the code, as is -# used in the DPS. this variable was written to accept -# time-vectorized input in the initial METBK code. +The DPA to calculate relative wind speed over water is currently set to return actual +wind speed (as if the current velocities were measured to be 0) for all cases of input +current velocity values (absent, present, nan). + +A subset of the Endurance moorings are the only ones that have VELPT instruments +mounted to measure surface currents. However, their compass readings are inaccurate due +to the mounted instruments' proximity to iron ballast in the mooring. + +It is anticipated that these moorings will be modified to eliminate this magnetic +interference. To use the velptmn measurements for METBK calculations on these moorings, +a 5th variable, use_velptmn_with_metbk, has been added to the argument list of the +function met_relwind_speed. Implementation of the use_velptmn_with_metbk variable will +require that it be treated as a "platform/instrument instance specific metadata parameter +changeable in time". It has been coded to accept time-vectorized input. + +__ Further documentation is contained in the met_relwind_speed function documentation. __ + +## METBK SENSOR HEIGHTS + +Note that the sensor heights may depend on the type of mooring: + +these 4 sensor height variables were time-vectorized in the July 2015 revision. + zwindsp = height of the wind measurement [m] + ztmpair = height of air temperature measurement [m] + zhumair = height of air humidity measurement [m] + ztmpwat = depth of bulk sea surface water measurements [m] + + zvelptm = depth of surface current measurement [m]: + this parameter is specified as metadata in the DPS; + however, it is not used in the code. + + zinvpbl = planetary boundary layer/inversion height: this is + set to a default value of 600m in the code, as is + used in the DPS. this variable was written to accept + time-vectorized input in the initial METBK code. -""" Set algorithm switches used in METBK bulk flux calculations -""" -# The jcool and jwarm switches should be set to 1, always! + +The jcool and jwarm switches should be set to 1, always! JCOOLFL = 1 # 1=do coolskin calc JWARMFL = 1 # 1=do warmlayer calc -#JWAVEFL # only the windspeed parametrization of the charnok +JWAVEFL # only the windspeed parametrization of the charnok # variable is coded; therefore this switch is not used. -""" LISTING OF SUBROUTINES BY ORDER IN THIS MODULE Grouped by sections; alphabetical within each section. @@ -178,14 +185,6 @@ make_hourly_data warmlayer_time_keys #................................................................................... - -""" - -#################################################################################### -#################################################################################### -#################################################################################### - -""" #................................................................................... #................................................................................... Functions to compute the L1 BULKMET (METBK) data products: @@ -745,7 +744,7 @@ def met_netsirr_hourly(shortwave_down, timestamp): Calculates NETSIRR_HOURLY_L2, the OOI core data product net shortwave radiation (wavelengths between 0.3 and 3.0 um) in the downward direction, for the METBK instrument on an hourly time base. This data product does not require the - coolskin\warmlayer algorithms. + coolskin/warmlayer algorithms. Implemented by: diff --git a/ion_functions/data/msp_functions.py b/ion_functions/data/msp_functions.py index 59433e4..6e91c24 100644 --- a/ion_functions/data/msp_functions.py +++ b/ion_functions/data/msp_functions.py @@ -1,11 +1,10 @@ #!/usr/bin/env python -""" -@package ion_functions.data.msp_functions -@file ion_functions/data/msp_functions.py -@author Craig Risien -@brief Module containing MASSP instrument related functions and wrapper functions - +# @package ion_functions.data.msp_functions +# @file ion_functions/data/msp_functions.py +# @author Craig Risien +# @brief Module containing MASSP instrument related functions and wrapper functions +""" MASSP L1 Data Products Data Product Specification for Dissolved Gas Concentrations (DISSGAS) from the diff --git a/ion_functions/data/nit_functions.py b/ion_functions/data/nit_functions.py index e1e5d85..e77303a 100644 --- a/ion_functions/data/nit_functions.py +++ b/ion_functions/data/nit_functions.py @@ -1,9 +1,15 @@ #!/usr/bin/env python +# @package ion_functions.data.nit_functions +# @file ion_functions/data/nit_functions.py +# @author Craig Risien +# @brief Module containing NIT related data-calculations. + """ -@package ion_functions.data.nit_functions -@file ion_functions/data/nit_functions.py -@author Craig Risien -@brief Module containing NIT related data-calculations. +# Overview +Module containing NIT related data-calculations. +This module implements the algorithm for calculating the +Dissolved Nitrate Concentration, Temperature and Salinity Corrected (NITRTSC) +from the OOI L0 NITROPT data product. """ import numpy as np diff --git a/ion_functions/data/obs_functions.py b/ion_functions/data/obs_functions.py index 9d4064a..e94006c 100644 --- a/ion_functions/data/obs_functions.py +++ b/ion_functions/data/obs_functions.py @@ -1,12 +1,18 @@ #!/usr/bin/env python +# @package ion_functions.data.obs_functions +# @file ion_functions/data/obs_functions.py +# @author Christopher Wingard +# @brief Module containing Ocean Bottom Seismometer instrument related functions + + """ -@package ion_functions.data.obs_functions -@file ion_functions/data/obs_functions.py -@author Christopher Wingard -@brief Module containing Ocean Bottom Seismometer instrument related functions +Module containing Ocean Bottom Seismometer instrument related functions +This module implements the algorithms for calculating the +Broadband Ground Velocity (GRNDVEL), Broadband Ground Acceleration (GRNDACC), +Short Period Ground Velocity (SGRDVEL) and Short Period Ground Acceleration (SGRDACC) +from the OOI L0 OBSBB and OBSSP data products. """ - def obs_bb_ground_velocity(raw, gain=3.2, sensitivity=1500.): """ Description: diff --git a/ion_functions/data/opt_functions.py b/ion_functions/data/opt_functions.py index 83f0471..c044f63 100644 --- a/ion_functions/data/opt_functions.py +++ b/ion_functions/data/opt_functions.py @@ -1,11 +1,23 @@ #!/usr/bin/env python +# @package ion_functions.data.opt_functions +# @file ion_functions/data/opt_functions.py +# @author Christopher Wingard +# @brief Module containing OPTAA and PAR data product algorithms. + +""" +# Overview +Module containing OPTAA and PAR data product algorithms. +This module implements the algorithms for calculating the +Beam Attenuation Coefficient (OPTATTN_L2), +Optical Absorption Coefficient (OPTABSN_L2), +and the Photosynthetically Available Radiation (PAR_L2) +from the WET Labs, Inc. ACS (OPTAA) and the +Satlantic HyperOCR (PAR) data products. +These algorithms are based on the OOI L0 OPTAA and PAR data products. +This module also implements the algorithm for calculating the +Dissolved Oxygen Concentration, Temperature and Salinity Corrected (DO2TS) +from the OOI L0 DO2 data product. """ -@package ion_functions.data.opt_functions -@file ion_functions/data/opt_functions.py -@author Christopher Wingard -@brief Module containing OPTAA and PAR data product algorithms. -""" - import numpy as np # load the temperature and salinity correction coefficients table diff --git a/ion_functions/data/opt_functions_tscor.py b/ion_functions/data/opt_functions_tscor.py index 7c24be5..ad2b8b5 100755 --- a/ion_functions/data/opt_functions_tscor.py +++ b/ion_functions/data/opt_functions_tscor.py @@ -1,37 +1,35 @@ #!/usr/bin/env python -""" -@package ion_functions.data.opt_functions_tscor -@file ion_functions/data/opt_functions_tscor.py -@author Christopher Wingard -@brief Module containing OPTAA related temperature and salinity correction - coefficients. +# @package ion_functions.data.opt_functions_tscor +# @file ion_functions/data/opt_functions_tscor.py +# @author Christopher Wingard +# @brief Module containing OPTAA related temperature and salinity correction +# coefficients. +"""Returns the Temperature and Salinity (T/S) correction coefficients as a +dictionary for use in the ion_functions/data/opt_functions module. Values are +from published literature and are available in: + + WET Labs, Inc. 2009. AC Meter Protocol Document, Revision P. + +The original file is composed of 4 columns corresponding to the wavelength +(nm) and the wavelength dependent temperature correction coefficients, +salinity correction coefficients for the 'c' channel, and salinity correction +coefficients for the 'a' channel, respectively. The dictionary uses the +wavelength as the key. + +Created April 25, 2013 by Christopher Wingard from vendor provided TS4.cor +file, available in ion_functions/data/matlab_scripts/optaa. + awk '{ + printf("tscor[%4.1f] = [%.5f, %.6f, %.6f]\n", $1, $2, $3, $4) + }' TS4.cor > temp.txt + +Modified April 29, 2014 by Russell Desiderio: padded dictionary at both ends + with nan values so that acs (OPTAA) wavelength values outside of the + wavelength range of the empirically determined temperature and salinity + correction coefficients will not cause a dictionary look-up error. """ import numpy as np -# Returns the Temperature and Salinity (T/S) correction coefficients as a -# dictionary for use in the ion_functions/data/opt_functions module. Values are -# from published literature and are available in: -# -# WET Labs, Inc. 2009. AC Meter Protocol Document, Revision P. -# -# The original file is composed of 4 columns corresponding to the wavelength -# (nm) and the wavelength dependent temperature correction coefficients, -# salinity correction coefficients for the 'c' channel, and salinity correction -# coefficients for the 'a' channel, respectively. The dictionary uses the -# wavelength as the key. -# -# Created April 25, 2013 by Christopher Wingard from vendor provided TS4.cor -# file, available in ion_functions/data/matlab_scripts/optaa. -# awk '{ -# printf("tscor[%4.1f] = [%.5f, %.6f, %.6f]\n", $1, $2, $3, $4) -# }' TS4.cor > temp.txt -# -# Modified April 29, 2014 by Russell Desiderio: padded dictionary at both ends -# with nan values so that acs (OPTAA) wavelength values outside of the -# wavelength range of the empirically determined temperature and salinity -# correction coefficients will not cause a dictionary look-up error. - no_value = np.nan # initialize dictionary diff --git a/ion_functions/data/ph_functions.py b/ion_functions/data/ph_functions.py index 64a6972..527adfe 100644 --- a/ion_functions/data/ph_functions.py +++ b/ion_functions/data/ph_functions.py @@ -1,12 +1,18 @@ #!/usr/bin/env python -""" -@package ion_functions.data.ph_functions -@file ion_functions/data/ph_functions.py -@author Christopher Wingard -@brief Module containing pH family instrument related functions +# @package ion_functions.data.ph_functions +# @file ion_functions/data/ph_functions.py +# @author Christopher Wingard +# @brief Module containing pH family instrument related functions + +""" +# Overview + +Module containing pH family instrument related functions. +This module implements the algorithms for calculating the +pH of seawater (PHWATER) and extracting light intensity values +from the OOI L0 PHSEN data product. """ -# imports import numpy as np import scipy as sp diff --git a/ion_functions/data/prs_functions.py b/ion_functions/data/prs_functions.py index 100f046..74fde92 100755 --- a/ion_functions/data/prs_functions.py +++ b/ion_functions/data/prs_functions.py @@ -1,59 +1,60 @@ #!/usr/bin/env python -""" -@package ion_functions.data.prs_functions -@file ion_functions/data/prs_functions.py -@author Russell Desiderio, Chris Wingard -@brief Module containing calculations related to instruments in the Seafloor - Pressure family. -""" -import pkg_resources -import numpy as np -import scipy.io as spio -from scipy import signal +# @package ion_functions.data.prs_functions +# @file ion_functions/data/prs_functions.py +# @author Russell Desiderio, Chris Wingard +# @brief Module containing calculations related to instruments in the Seafloor +# Pressure family. """ - Listing of BOTPT functions, in order encountered. +# Overview - Functions calculating data products. +Listing of BOTPT functions, in order encountered. - BOTTILT: +Functions calculating data products. - prs_bottilt_ccmp -- computes the BOTTILT-CCMP_L1 data product - prs_bottilt_tmag -- computes the BOTTILT-TMAG_L1 data product - prs_bottilt_tdir -- computes the BOTTILT-TDIR_L1 data product + BOTTILT: - BOTSFLU: + prs_bottilt_ccmp -- computes the BOTTILT-CCMP_L1 data product + prs_bottilt_tmag -- computes the BOTTILT-TMAG_L1 data product + prs_bottilt_tdir -- computes the BOTTILT-TDIR_L1 data product - prs_botsflu_time15s -- computes the TIME15S-AUX auxiliary data product - prs_botsflu_meanpres -- computes the BOTSFLU-MEANPRES_L2 data product - prs_botsflu_predtide -- computes the BOTSFLU-PREDTIDE_L2 data product - prs_botsflu_meandepth -- computes the BOTSFLU-MEANDEPTH_L2 data product - prs_botsflu_5minrate -- computes the BOTSFLU-5MINRATE_L2 data product - prs_botsflu_10minrate -- computes the BOTSFLU-10MINRATE_L2 data product - prs_botsflu_time24h -- computes the TIME24H-AUX auxiliary data product - prs_botsflu_daydepth -- computes the BOTSFLU-DAYDEPTH_L2 data product - prs_botsflu_4wkrate -- computes the BOTSFLU-4WKRATE_L2 data product - prs_botsflu_8wkrate -- computes the BOTSFLU-8WKRATE_L2 data product + BOTSFLU: - Worker functions called by functions calculating data products. + prs_botsflu_time15s -- computes the TIME15S-AUX auxiliary data product + prs_botsflu_meanpres -- computes the BOTSFLU-MEANPRES_L2 data product + prs_botsflu_predtide -- computes the BOTSFLU-PREDTIDE_L2 data product + prs_botsflu_meandepth -- computes the BOTSFLU-MEANDEPTH_L2 data product + prs_botsflu_5minrate -- computes the BOTSFLU-5MINRATE_L2 data product + prs_botsflu_10minrate -- computes the BOTSFLU-10MINRATE_L2 data product + prs_botsflu_time24h -- computes the TIME24H-AUX auxiliary data product + prs_botsflu_daydepth -- computes the BOTSFLU-DAYDEPTH_L2 data product + prs_botsflu_4wkrate -- computes the BOTSFLU-4WKRATE_L2 data product + prs_botsflu_8wkrate -- computes the BOTSFLU-8WKRATE_L2 data product - BOTSFLU: +Worker functions called by functions calculating data products. - anchor_bin_raw_data_to_15s - anchor_bin_detided_data_to_24h - calc_meandepth_plus - calculate_sliding_means - calculate_sliding_slopes + BOTSFLU: - Functions calculating event notifications; they return either True or False. + anchor_bin_raw_data_to_15s + anchor_bin_detided_data_to_24h + calc_meandepth_plus + calculate_sliding_means + calculate_sliding_slopes - BOTSFLU: +Functions calculating event notifications; they return either True or False. - prs_tsunami_detection -- event notification specified by DPS - prs_eruption_imminent -- event notification specified by DPS - prs_eruption_occurred -- event notification specified by DPS + BOTSFLU: + + prs_tsunami_detection -- event notification specified by DPS + prs_eruption_imminent -- event notification specified by DPS + prs_eruption_occurred -- event notification specified by DPS """ +import numpy as np +import pkg_resources +import scipy.io as spio +from scipy import signal + def prs_bottilt_ccmp(scmp, sn): """ diff --git a/ion_functions/data/prs_functions_ccmp.py b/ion_functions/data/prs_functions_ccmp.py index ce35189..61df35f 100644 --- a/ion_functions/data/prs_functions_ccmp.py +++ b/ion_functions/data/prs_functions_ccmp.py @@ -1,18 +1,17 @@ #!/usr/bin/env python -""" -@package ion_functions.data.prs_functions_ccmp -@file ion_functions/data/prs_functions_ccmp.py -@author Christopher Wingard -@brief Module containing BOTTILT-CCMP correction coefficients. -""" +# @package ion_functions.data.prs_functions_ccmp +# @file ion_functions/data/prs_functions_ccmp.py +# @author Christopher Wingard +# @brief Module containing BOTTILT-CCMP correction coefficients. -# Returns the corrected compass direction based on the sensor compass direction -# and the sensor serial number. Dictionary is used in the -# ion_functions/data/prs_functions module. Values are from the DPS (DCN -# 1341-00060): -# -# Created June 10, 2013 by Christopher Wingard. +"""Module containing BOTTILT-CCMP correction coefficients. +Returns the corrected compass direction based on the sensor compass direction +and the sensor serial number. Dictionary is used in the +ion_functions/data/prs_functions module. Values are from the DPS (DCN +1341-00060): +Created June 10, 2013 by Christopher Wingard. +""" # initialize dictionary cmp_lookup = {} diff --git a/ion_functions/data/prs_functions_ccmp_lily_compass_cals.py b/ion_functions/data/prs_functions_ccmp_lily_compass_cals.py index e246bb1..d9321d3 100644 --- a/ion_functions/data/prs_functions_ccmp_lily_compass_cals.py +++ b/ion_functions/data/prs_functions_ccmp_lily_compass_cals.py @@ -1,10 +1,10 @@ #!/usr/bin/env python -""" -@package ion_functions.data.prs_functions_ccmp_lily_compass_cals -@file ion_functions/data/prs_functions_ccmp_lily_compass_cals.py -@author Russell Desiderio -@brief Module containing BOTTILT-CCMP correction coefficients. -""" + +# @package ion_functions.data.prs_functions_ccmp_lily_compass_cals +# @file ion_functions/data/prs_functions_ccmp_lily_compass_cals.py +# @author Russell Desiderio +# @brief Module containing BOTTILT-CCMP correction coefficients. + # Returns the corrected compass direction based on the sensor compass direction # and the sensor serial number. Dictionary is used in the diff --git a/ion_functions/data/sfl_functions.py b/ion_functions/data/sfl_functions.py index fa76e30..9b40499 100644 --- a/ion_functions/data/sfl_functions.py +++ b/ion_functions/data/sfl_functions.py @@ -1,17 +1,30 @@ #!/usr/bin/env python + +# @package ion_functions.data.sfl_functions +# @file ion_functions/data/sfl_functions.py +# @author Christopher Wingard, Russell Desiderio +# @brief Module containing Seafloor Properties related data-calculations. + """ -@package ion_functions.data.sfl_functions -@file ion_functions/data/sfl_functions.py -@author Christopher Wingard, Russell Desiderio -@brief Module containing Seafloor Properties related data-calculations. +#Overview +Module containing Seafloor Hydrothermal Vent Fluid In-situ Chemistry derived properties. +This module implements the algorithms for calculating the +TRHPHCC_L2 (Chloride Concentration), +THSPHHC_L2 (Hydrogen Concentration), +THSPHHS_L2 (Hydrogen Sulfide Concentration), +THSPHPH-PH_L2 (pH with chloride and AgCl reference electrode), +THSPHPH-PH-ACL_L2 (pH with AgCl reference electrode only), +THSPHPH-PH-NOREF_L2 (pH with chloride only), +THSPHPH-PH-NOREF-ACL_L2 (pH with neither chloride nor AgCl reference electrode). """ import numpy as np from scipy.interpolate import RectBivariateSpline from ion_functions.data.generic_functions import replace_fill_with_nan + # used by def sfl_trhph_chloride -from ion_functions.data.sfl_functions_surface import tdat, sdat, cdat +from ion_functions.data.sfl_functions_surface import cdat, sdat, tdat # ............................................................................. # THSPH data products: THSPHHC, THSPHHS, THSPHPH (4 PH products) .............. diff --git a/ion_functions/data/sfl_functions_surface.py b/ion_functions/data/sfl_functions_surface.py index 9080bd6..f698f39 100644 --- a/ion_functions/data/sfl_functions_surface.py +++ b/ion_functions/data/sfl_functions_surface.py @@ -1,11 +1,11 @@ #!/usr/bin/env python -""" -@package ion_functions.data.sfl_functions_surface -@file ion_functions/data/sfl_functions_surface.py -@author Christopher Wingard -@brief Module containing the temperature, conductivity and chloride calibration - surface from Larson et al 2007. -""" + +# @package ion_functions.data.sfl_functions_surface +# @file ion_functions/data/sfl_functions_surface.py +# @author Christopher Wingard +# @brief Module containing the temperature, conductivity and chloride calibration +# surface from Larson et al 2007. + import numpy as np # recreate the 3 arrays of temperature (tdat), conductivty (sdat) and chloride diff --git a/ion_functions/data/test/test_met_functions.py b/ion_functions/data/test/test_met_functions.py index ab79a55..b989eaa 100644 --- a/ion_functions/data/test/test_met_functions.py +++ b/ion_functions/data/test/test_met_functions.py @@ -6,14 +6,14 @@ @brief Unit tests for met_functions module """ -from nose.plugins.attrib import attr -from ion_functions.test.base_test import BaseUnitTestCase - -import numpy as np import datetime as dt import os +import numpy as np +from nose.plugins.attrib import attr + import ion_functions.data.met_functions as mb +from ion_functions.test.base_test import BaseUnitTestCase """ List of tests: @@ -360,7 +360,7 @@ def setUp(self): the refactored code were then incorporated as the target test values for the python code to calculate. - The coolskin\warmlayer 'xpctd' arrays are dimensioned as 4 x 3: + The coolskin/warmlayer 'xpctd' arrays are dimensioned as 4 x 3: {4 permutations of the [jwarm,jcool] switches} x {3 hourly data points} The switch assignments as a function of row are: jwarm jcool @@ -379,9 +379,9 @@ def setUp(self): 2014-12-29: Russell Desiderio. Incorporated tests on Irminger METBK data. 2015-07-13: Russell Desiderio. Incorporated tests using time-vectorized input for sensor heights and algorithm switches; tested only met_latnflx as a proxy for all - the functions using the coolskin\warmlayer algorithm. + the functions using the coolskin/warmlayer algorithm. 2015-10-26: Russell Desiderio. Expanded tests developed on 7-13 to test all data products - using the coolskin\warmlayer algorithm (fixes problem exposed in redmine ticket + using the coolskin/warmlayer algorithm (fixes problem exposed in redmine ticket #8592). Also fixed test_met_mommflx within this test module, which had been named diff --git a/ion_functions/data/vel_functions.py b/ion_functions/data/vel_functions.py index a10285c..0510c50 100644 --- a/ion_functions/data/vel_functions.py +++ b/ion_functions/data/vel_functions.py @@ -1,15 +1,24 @@ #!/usr/bin/env python + +# @package ion_functions.data.vel_functions +# @file ion_functions/data/vel_functions.py +# @author Stuart Pearce, Russell Desiderio +# @brief Module containing velocity family instrument related functions + """ -@package ion_functions.data.vel_functions -@file ion_functions/data/vel_functions.py -@author Stuart Pearce, Russell Desiderio -@brief Module containing velocity family instrument related functions +# Overview +Module containing velocity family instrument related functions. +This module implements the algorithms for calculating the horizontal +and vertical velocity components from the OOI L0 VEL3D data product. """ import numpy as np -from numpy import sin, cos, radians +from numpy import cos, radians, sin -from ion_functions.data.generic_functions import magnetic_declination, magnetic_correction +from ion_functions.data.generic_functions import ( + magnetic_correction, + magnetic_declination, +) # NOTE: # The previous version of this module had each function return an diff --git a/ion_functions/data/wav_functions.py b/ion_functions/data/wav_functions.py index 132b6af..5ed28db 100755 --- a/ion_functions/data/wav_functions.py +++ b/ion_functions/data/wav_functions.py @@ -1,10 +1,20 @@ #!/usr/bin/env python +# @package ion_functions.data.wav_functions +# @file ion_functions/data/wav_functions.py +# @author Russell Desiderio +# @brief Module containing WAVSS wave statistics data-calculations. + +""" +# Overview +Module containing WAVSS surface wave spectrum data-calculations. +This module implements the algorithms for calculating the +frequency values for directional and non-directional wave spectral bins, +the time values associated with buoy displacement measurements, and the +mean wave direction corrected for magnetic declination from the OOI L0 +WAVSTAT data product. """ -@package ion_functions.data.wav_functions -@file ion_functions/data/wav_functions.py -@author Russell Desiderio -@brief Module containing WAVSS wave statistics data-calculations. -""" + + import numpy as np from ion_functions.data.generic_functions import magnetic_declination diff --git a/meta.yaml b/meta.yaml new file mode 100644 index 0000000..a1d08b5 --- /dev/null +++ b/meta.yaml @@ -0,0 +1,35 @@ +{% set name = "ion-functions" %} +{% set version = "2.5.1" %} + +package: + name: {{ name|lower }} + version: {{ version }} + +source: + # git_url: https://github.com/oceanobservatories/{{ name }} + # git_rev: v{{ version}} + path: . + +requirements: + build: + - python <3 + - setuptools + - setuptools_cython + - cython + - numpy ==1.16 + run: + - python + - numpy ==1.16 + - numexpr + - scipy + - geomag + - pygsw + +build: + number: 0 + script: python setup.py install --single-version-externally-managed --record record.txt + +about: + home: http://oceanobservatories.org + license: apache 2.0 + summary: Functions for OOI diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..85666f1 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,61 @@ +site_name: Ocean Observatories Initiative Ion Functions +repo_url: https://github.com/joffreyp/ion-functions/tree/feature/documentation +repo_name: ion-functions +theme: + name: "material" + logo: assets/NSF-OOI-RGB.png + features: + - navigation.sections + # - navigation.expand + - navigation.path + - navigation.instant + - navigation.prune + - navigation.top + - toc.integrate + - toc.follow + - search.suggest + - search.highlight + - search.share + icon: + repo: fontawesome/brands/github + +plugins: + - mkdocstrings: + handlers: + python: + options: + docstring_style: numpy + - search + - autorefs + +nav: + - Ion Functions Overview: index.md + - Reference: + - ADCP Functions: adcp_functions.md + - CTD Functions: ctd_functions.md + - CO2 Functions: co2_functions.md + - DOSTA Functions: do2_functions.md + - Fluorometer Functions: flo_functions.md + - Hydrophone Functions: hyd_functions.md + - Optical Backscatter Functions: obs_functions.md + - Met Functions: met_functions.md + - Disolved Gas Concentration Functions: msp_functions.md + - Disolved Nitrate Functions: nit_functions.md + - Ocean Bottom Seismometer Functions: obs_functions.md + - OPTAA Functions: opt_functions.md + - pH Functions: ph_functions.md + # - Polycal Functions: polycals.md # Doesn't work with MkDocs right now! + - Seafloor Pressure Functions: prs_functions.md + - Seafloor Hydrothermal Vent Chemistry Functions: sfl_functions.md + - Velocity Functions: vel_functions.md + - Surface Wave Spectra Functions: wav_functions.md + - Utility Functions: utility_functions.md + - QC/Testing: qc-tests.md + +markdown_extensions: + - pymdownx.arithmatex: + generic: true + +extra_javascript: + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js