Skip to content

Latest commit

 

History

History
73 lines (56 loc) · 7.37 KB

MANUAL.md

File metadata and controls

73 lines (56 loc) · 7.37 KB
Raw

'ScarFace' Manual

Prerequisites

ScarFace requires a base R installation (recommended with an installation of RStudio) and installed packages of 'shiny', 'shinydashboard', 'shinyFiles', 'seacarb', 'readr', and 'dplyr'. You may install them all at once with

install.packages(c("shiny", "shinydashboard", "shinyFiles", "seacarb", "readr", "dplyr"))

or separately with

install.packages("name of the package")

Run the app

Either open 'app.R' in RStudio and push the button "Run App" or call the function

runApp("~/app.R")

Alternatively, the app may be launched by opening a terminal or console window and executed with

R -e "shiny::runApp('~/app.R')"

In both cases, '~/app.R' must be completed with the full path to the location of 'app.R'.

Bjerrum plot

The Bjerrum plot displays the relative concentrations of carbonate species, with respect to DIC, as a function of pH, when the solution is at equilibrium. The grey lines represent the speciation at T=25 °C, S=35, and P=0 bar (at sea surface). By using the sliders or manual inputs, the effects of temperature, salinity and pressure on the dissociation constants pK1 and pK2 of carbonic acid can be visualized. The graph is interactive, i.e. it can be zoomed in or data can be read on mouse over.

Working Directory

The working directory, i.e. the path to where the input files are stored and where output files should be saved, can be defined here by pushing 'Choose' and selecting the destination folder from the dialog window.

Carbonate chemistry

manual input

First the input parameters must be entered in the upper left box by choosing the pair of known carbonate system parameters, and defining the values of those, which are in µmol/kg (except for pH and pCO2). In addition, define temperature, salinity and pressure. In the upper right box, additional choices can be made, including:

  • Silicate and phosphate concentrations: leave at 0 when unknown.
  • Constants for K1 and K2: when 'Auto' is chosen, the Lueker et al. (2000) constants are used, except if T is outside the range 2--35 °C and/or S is outside the range 19--43. In these cases, the constants of Waters et al. (2014) are used.
  • INPUT pCO2: used to indicate the convention for INPUT pCO2, i.e., when it is an input variable (flags 21 to 25): "insitu" indicates it is referenced to in situ pressure and in situ temperature; "potential" indicates it is referenced to 1 atm pressure and potential temperature; and "standard" indicates it is referenced to 1 atm pressure and in situ temperature. All three options should give identical results at surface pressure. This option is not used when pCO2 is not an input variable (flags 1 to 15). The default is "potential".
  • Total Boron concentration: default is Lee et al. (2010).
  • pH scale: in addition to 'total scale', 'seawater scale' and 'free scale' from the original 'seacarb' package, 'NBS scale' can be chosen as well. Default is 'total scale'.

Once the desired choices were selected, the output values in the following table can be collected in an extra table. This facilitates the comparison of computed values from different input variables. There you can delete single or multiple rows by mouse selection and pressing 'Delete selected rows'. The content of 'Collected output data' can be saved to the destination path as a csv file.

batch input

The input data can also be read from an uploaded csv file (here you may choose between comma-, semicolon- or tab-separation). An example is given with 'Batch_example_comma.csv'. In the box 'Carbonate system parameters [INPUT]', define the pair of known carbonate system variables. Then define the input parameters by choosing the corresponding columns of the source table from the dropdown menu or by entering generic values. For the pressure, use the radio buttons to select whether pressure or water depth is given in the source data.

The usage of 'Additional choices' is equivalent to the 'manual input' (see above).

The calculated variables are shown in the table 'Carbonate system parameters [OUTPUT]'. Before continuing, it might be helpful to include additional columns from the source table (e.g. sample name, age, etc.). This can be done by using the checkboxes in the box 'Include additional columns [optional]'.

Once all information is included in the output table, it can be saved to the destination path as a csv file, or proceed with 'Error propagation'.

Error propagation

If propagated errors for the calculated carbonate system parameters should be calculated, define the uncertainties of the input parameters either by using the dropdown menus (if individual errors are given in the source table) or by manually entering general uncertainties. NOTE that manual inputs will override the source table uncertainties.

In addition, uncertainties can be given for:

  • Silicate and phosphate uncertainties: leave at 0 when unknown.
  • Uncertainties in equilibrium constants: you can either neglect uncertainties of the dissociation constants or choose 'Default'. Then the pre-defined uncertainties from the 'seacarb' package are used (see its documentation for details):
epK=c(0.002, 0.0075, 0.015, 0.01, 0.01, 0.02, 0.02)
  • Total Boron uncertainty: given as a fractional error (i.e. 0.02 means 2% error). Default is 0.02.

The method of error propagation can be specified in the lower part of the box:

  • Error propagation method:
    • The Gaussian method is the standard technique for estimating a computed variable’s (z) second moment (its variance or standard deviation) based on a first-order approximation to z. More precisely, we use here the basic 1st order, 2nd moment uncertainty analysis (a type of Taylor expansion), assuming no covariance between input variables. This is the approach used by Dickson and Riley (1978). It is the default method.
    • The Method of Moments is a more general form of the Gaussian method. But in addition, it also accounts for covariance between input variables. In this case, the ’errors’ routine allows the user to specify a value of the correlation coefficient ’r’, having a value between -1.0 and 1.0, to indicate the correlation between standard uncertainties of the input pair of carbonate system variables. That correlation is used to compute the covariance. But by default, it is assumed that there is no covariance (r=0.0).
    • The Monte Carlo method is a brute-force approach relying on repeated random sampling of input errors, adding those to each input variables, calculating the corresponding output variables for each sample, and finally assessing the standard deviation in each output variables.
  • Correlation coefficient: correlation coefficient between standard uncertainties of var1 and var2 (only useful with 'Method of Moments', i.e., ignored for the 2 other methods, the default is r=0.0.
  • Monte Carlo repetitions: Number of random samples, onyl applied when 'Monte Carlo' method is chosen. The default is 10000.

The calculated propagated errors are displayed in the table 'Standard uncertainties of carbonate system parameters [OUTPUT]'. To combine all data (i.e. the output data from 'batch input' plus calculated errors), this can be achieved by checking the box left of the save button. The entire table can then be saved to the destination path as a csv file.