Readme for the MATLAB functions ESPER_LIR(…), ESPER_NN(…), and ESPER_Mixed(…)
These functions estimate seawater properties from other seawater property measurements.
How to set up: Running the ESPER estimation routines in MATLAB is a 4-step procedure:
- Extract all zipped folders.
- Add all folders onto the current working directory or the MATLAB path.* Be sure to add the downloaded folder "with subfolders." The "private" folder should not need to be added if you are adding folders individually by command line.
- Call the functions according to the instructions below. There are example calculations provided at the end of this Readme to verify your installation is correct. The full test output is provided as "TestOutput.mat."
- Please cite the CSIRO seawater toolbox and CO2SYS (which are called by ESPER) appropriately in your documentation. The included version of CO2SYS is a renamed distribution (CO2SYS_ESPER.m) of the code by van Hueven, Pierrot, Rae, Lewis, & Wallace (2011). CO2SYS code is only included because CO2SYS versions can sometimes differ locally.
*Not sure what the MATLAB path is? Check this out. An easy way get the LIR files on the path (without putting them in your working directory) is to navigate to the folder in the command window, then enter the command " addpath pwd". You may need to do this again after each MATLAB restart.
Questions and Updates: For questions not addressed by the papers or this readme file, please contact Brendan Carter, Brendan.carter@gmail.com, and he will get back to you as he is able. Suggestions, bug reports, and queries regarding code updates are welcome. We intend to continue to update algorithms as new quality controlled datasets become available. Please indicate versions if you use routines for any publications (for reproducibility). Contact the corresponding author for updates.
Versioning and documentation : ESPER_LIR is an update to LIRv2 and is sometimes called LIRv3. ESPER_NN is a neural network implementation of the LIR code that is inspired by CANYON-B (Bittig et al., 2018), but also somewhat modified. ESPER_Mixed calls both functions and averages the outputs. The algorithms are described and assessed in a manuscript in preparation for submission at Limnology and Oceanography: Methods. The initial release of ESPER_LIR will be version 3.0 and of ESPER_NN and ESPER_Mixed will be version 1.0. The first line of the comments will indicate if the version has been updated (e.g. it will say "version 3.1" and have some update notes).
LIARv1: Carter et al., 2016, doi: 10.1002/lom3.10087
LIARv2, LIPHR, LINR citation: https://doi.org/10.1002/lom3.10232
LIPR, LISIR, LIOR, first described/used: Carter et al., 2021, https://doi.org/10.1029/2020GB006623
ESPER_LIR, ESPER_NN, and ESPER_Mixed, submitted.
ESPER_NN is inspired by CANYON- , which also uses neural networks: Bittig et al. 2018: https://doi.org/10.3389/fmars.2018.00328
Notable changes from LIRv2:
- LIRv2 had separate function calls for each property. LIRv3 uses a single function call. However, the function will only estimate the desired properties, so a new required input indicates which property estimate(s) is (are) desired.
- To work with a variety of estimate types, the vector specifying which predictors are being provided was modified to use a single key (rather than a different key for each property type). The numbers for each property type have therefore changed.
- Previously if the 'Equations' optional input was not provided, the routine would try to use the provided uncertainty information with all 16 possible equations to provide a single estimate with minimal uncertainty. This proved unintuitive to some users and problematic in a few use cases, so ESPER_LIR and ESPER_NN now default to attempting to use all 16 equations in this instance and returning all estimated values.
- Potential temperature and AOU are no longer valid input predictors. The internal calculations still use these values, but the routines no longer accept them as inputs. This is to ensure that potential temperature and AOU are calculated within the routine using the same equations used for the training data.
- The OAAdjustTF flag has been removed and the calculation is now always on. If no EstDates input is provided then the routine will report all values specific to January 1st, 2002 (i.e., the date of the Canth data product used as a basis for Canth adjustments: Lauvset et al., 2016).
Function call explanation: The function calls are nearly identical for all 3 variants. Once the code is on the Matlab path a detailed explanation of the function call can be found in the code comments and viewed by typing helpESPER_NN or helpESPER_LIR or helpESPER_Mixed into the MATLAB command line and pressing enter/return.
[Estimates,Uncertainties,Coefficients]=ESPER_LIR(DesiredVariables,OutputCoordinates,PredictorMeasurements,PredictorTypes,...Optional Inputs...)
[Estimates,Uncertainties]=ESPER_NN(DesiredVariables,OutputCoordinates,PredictorMeasurements,PredictorTypes,...Optional Inputs...)
[Estimates,Uncertainties]=ESPER_Mixed(DesiredVariables,OutputCoordinates,PredictorMeasurements,PredictorTypes,...Optional Inputs...)
*************************************************************************
Locally Interpolated Regressions (LIRs) for seawater property
estimation: Estimates seawater properties and estimate uncertainty from
combinations of other parameter measurements. LIRs refers specifically
to code that uses interpolated regressions as opposed to collections of
neural networks (such as CANYON or ESPER_NN).
Updated 2020.08.19 (v3)
-Combined all LIRs
-Implemented first-principles adjustments for Ocean Acidification
-Implemented regression uncertainty quantification (vs. interpolation)
-Refit to GLODAPv2.2020 (subset)
-Implemented distance-weighting in regressions with wider windows
Documentation and citations:
LIARv1: Carter et al., 2016, doi: 10.1002/lom3.10087
LIARv2, LIPHR, LINR citation: Carter et al., 2018, https://doi.org/10.1002/lom3.10232
LIPR, LISIR, LIOR, first described/used: Carter et al., 2021, https://doi.org/10.1029/2020GB006623
ESPER_LIR and ESPER_NN, submitted.
ESPER_NN is inspired by CANYON-B, which also uses neural networks:
Bittig et al. 2018: https://doi.org/10.3389/fmars.2018.00328
This function needs the CSIRO seawater package to run if measurements
are provided in molar units or if potential temperature or AOU are
needed but not provided by the user. Scale differences from TEOS-10 are
a negligible component of alkalinity estimate error. The seawater
package is distributed freely by CSIRO (website has citation info):
http://www.cmar.csiro.au/datacentre/ext\_docs/seawater.htm
*************************************************************************
Input/Output dimensions:
.........................................................................
p: Integer number of desired property estimate types (e.g., TA, pH, NO3-)
n: Integer number of desired estimate locations
e: Integer number of equations used at each location
y: Integer number of parameter measurement types provided by the user.
n*e: Total number of estimates returned as an n by e array
*************************************************************************
Required Inputs:
DesiredVariables:
Specifies which variables will be returned, excepting unitless pH,
all outputs are in umol/kg.
-
Total Titration Seawater Alkalinity (TA)
-
Total Dissolved Inorganic Carbon (DIC)
-
in situ pH on the total scale
-
Phosphate
-
Nitrate
-
Silicate
-
Dissolved Oxygen (O2)
OutputCoordinates (required n by 3 array):
Coordinates at which estimates are desired. The first column should
be longitude (degrees E), the second column should be latitude
(degrees N), and the third column should be depth (m).
PredictorMeasurements (required n by y array):
Parameter measurements that will be used to estimate alkalinity. The
column order (y columns) is arbitrary, but specified by PredictorTypes.
Concentrations should be expressed as micromol per kg seawater unless
PerKgSwTF is set to false in which case they should be expressed as
micromol per L, temperature should be expressed as degrees C, and
salinity should be specified with the unitless convention. NaN
inputs are acceptable, but will lead to NaN estimates for any
equations that depend on that parameter.
PredictorTypes (required 1 by y vector):
Vector indicating which parameter is placed in each column of the
'PredictorMeasurements' input. Note that salinity is required for
all equations. If O2 is provided, then temperature or potential
temperature must also be provided to convert O2 to AOU. For example,
if the first three columns of 'PredictorMeasurements' contain
salinity, silicate, and temperature, then PredictorTypes should equal [1 5
7].
Input Parameter Key:
-
Salinity
-
Temperature
-
Phosphate
-
Nitrate
-
Silicate
-
O2
*************************************************************************
Optional inputs: All remaining inputs must be specified as sequential
input argument pairs (e.g. "..., 'Equations',[1:16], 'OAAdjustTF', false,
etc...")
EstDates (Semi-optional n by 1 array or 1 by 1 value, default 2002.0):
A vector of decimal dates for the estimates (e.g. July 1 2020 would
be "2020.5"). If only a single date is supplied that value is used
for all estimates. It is highly recommended that date(s) be provided
for estimates of DIC and pH. This version of the code will accept 1
by n inputs as well.
Equations (optional 1 by e vector, default []):
Vector indicating which equations will be used to estimate
alkalinity. This input also determines the order of the columns in
the 'Estimates' output. If [] is input or the input is not specified
then all 16 equations will be used and only the outputs from the
equation with the lowest uncertainty estimate will be returned.
(S=salinity, Theta=potential temperature, N=nitrate, Si=silicate,
T=temperature, O2=dissolved oxygen molecule... see
'PredictorMeasurements' for units).
...........................................................
Output Equation Key (See below for explanation of A, B, and C):
-
S, T, A, B, C
-
S, T, A, C
-
S, T, B, C
-
S, T, C
-
S, T, A, B
-
S, T, A
-
S, T, B
-
S, T
-
S, A, B, C
-
S, A, C
-
S, B, C
-
S, C
-
S, A, B
-
S, A
-
S, B
-
S
DesiredVar | A B C
_____________|_____________________________________
TA | Nitrate Oxygen Silicate
DIC | Nitrate Oxygen Silicate
pH | Nitrate Oxygen Silicate
phosphate | Nitrate Oxygen Silicate
nitrate | Phosphate Oxygen Silicate
silicate | Phosphate Oxygen Nitrate
O2 | Phosphate Nitrate Silicate
MeasUncerts (Optional n by y array or 1 by y vector, default: [0.003 S,
0.003 degrees C (T or theta), 1% P, 1% O2, 1% Si]: Array of
measurement uncertainties (see 'PredictorMeasurements' for units).
Uncertainties should be presented in order indicated by PredictorTypes.
Providing these estimates will improve ESPERestimate
uncertainties in 'UncertaintyEstimates'. Measurement uncertainties
are a small part of ESPER estimate uncertainties for WOCE-quality
measurements. However, estimate uncertainty scales with measurement
uncertainty, so it is recommended that measurement uncertainties be
specified for sensor measurements. If this optional input argument
is not provided, the default WOCE-quality uncertainty is assumed. If
a 1 by y array is provided then the uncertainty estimates are assumed
to apply uniformly to all input parameter measurements.
pHCalcTF (Optional boolean, default false):
If set to true, LIPHR will recalculate the pH to be a better estimate
of what the seawater pH value would be if calculated from TA and DIC
instead of measured with purified m-cresol dye. This is arguably also
a better estimate of the pH that would be obtained from pre-2011
measurements with impure dyes. See the LIPHR paper for details
PerKgSwTF (Optional boolean, default true):
Many sensors provide measurements in micromol per L (molarity)
instead of micromol per kg seawater. Indicate false if provided
measurements are expressed in molar units (concentrations must be
micromol per L if so). Outputs will remain in molal units
regardless.
VerboseTF (Optional boolean, default true):
Setting this to false will make ESPER_LIR stop printing updates to
the command line. This behavior can also be permanently disabled
below. Warnings and errors, if any, will be given regardless.
*************************************************************************
Outputs:
OutputEstimates:
A n by e array of ESPER_LIR estimates specific to the coordinates and
parameter measurements provided as inputs. Units are micromoles per
kg (equivalent to the deprecated microeq per kg seawater).
UncertaintyEstimates:
A n by e array of uncertainty estimates specific to the coordinates,
parameter measurements, and parameter uncertainties provided.
CoefficientsUsed: (ESPER_LIR only)
A n by 6 by e array of ESPER_LIR coefficients specific to the
coordinates and provided as inputs. Units are those of the property
being predicted divided by the property doing the prediction (often
micromol per kg for both) and are provided in the order indicated in
the Output Equation Key above, with NaNs for predictors that are not
used. The first constant is multiplied by 1 in the prediction
equations (i.e., is just an added coefficient).
*************************************************************************
Missing data: should be indicated with a NaN. A NaN coordinate will
yield NaN estimates for all equations at that coordinate. A NaN
parameter value will yield NaN estimates for all equations that require
that parameter.
*************************************************************************
Please send questions or related requests to brendan.carter@gmail.com.
*************************************************************************
Example call:
The following call can be input into the command line to test your installation of the ESPER code. This call requests estimates of all properties (1 through 7) at 3 locations (100 m depth at 0°N and 0°E, 1000 m depth at the same location, and 100 m depth at 150°W, or -150°E, and 0°N) and provides identical predictor properties for all locations: salinity (35), phosphate (0.5 µmol kg₋1), temperature (5°C), nitrate (10 µmol kg₋1), silicate (20 µmol kg₋1), and oxygen (200 µmol kg₋1). The 4th input tells the code the order of the input property measurements, and it appears slightly out of order because phosphate was given before temperature. The next 2 input argument pairs (4 inputs) are optional. The first limits the output to the three indicated equations and tells the code to give the outputs for equation 16 2nd after equation 1 and before equation 8. The last pair specifies the dates of the requested output estimates. In this case the last estimate is specific to 2030. The code assumes an exponential increase in Canth and is not trustworthy for estimates much beyond 2030… this is just an example calculation.
[a,b]=ESPER_Mixed([1 2 3 4 5 6 7],[0 0 100;0 0 1000;-150 0 100],[35 0.5 5 10 20 200;35 0.5 5 10 20 200;32 0.5 5 10 20 200],[1 3 2 4 5 6],'Equations',[1 16 8],'EstDates',[1980;2002;2030]);
The full expected output is provided within ESPER_files.zip as TestOutput.m. For a quick check, enter the code above and then follow it up with:
a.pH(2,2)
…. and you should get the response:
ans =
7.8809
… getting different values? Please contact me so I can verify that this Readme is up to date.