Help for package equil2

Title:

Calculate Urinary Saturation with the EQUIL2 Algorithm

Version:

1.1.0

Description:

Saturation of ionic substances in urine is calculated based on sodium, potassium, calcium, magnesium, ammonia, chloride, phosphate, sulfate, oxalate, citrate, ph, and urate. This program is intended for research use, only. The code within is translated from EQUIL2 Visual Basic code based on Werness, et al (1985) "EQUIL2: a BASIC computer program for the calculation of urinary saturation" <doi:10.1016/s0022-5347(17)47703-2> to R. The Visual Basic code was kindly provided by Dr. John Lieske of the Mayo Clinic.

Imports:

units

Suggests:

covr, knitr, rmarkdown, spelling, testthat (≥ 3.0.0)

License:

MIT + file LICENSE

Encoding:

UTF-8

Config/testthat/edition:

URL:

https://billdenney.github.io/equil2/

VignetteBuilder:

knitr

Language:

en-US

Config/roxygen2/version:

8.0.0

NeedsCompilation:

Packaged:

2026-06-11 11:19:58 UTC; bill

Author:

Bill Denney

[aut, cre, cph], John Lieske

[cph]

Maintainer:

Bill Denney <wdenney@humanpredictions.com>

Repository:

CRAN

Date/Publication:

2026-06-11 11:40:13 UTC

Add units to support unit conversion for calculations

Description

Units are added to support molecular weight and mEq/L conversions. Units are named with the unit, an underscore, and the chemical species in lower case. Examples are "g_ammonia", "mol_ammonia", and "Eq_ammonia". Species with units are all species inputs for the equil2() function.

Usage

add_units()

Value

NULL, the function is used for its side-effects

Calculate urine saturation with the EQUIL-2 algorithm

Description

Calculate urine saturation with the EQUIL-2 algorithm

Usage

equil2(
  sodium_mEq_L,
  potassium_mEq_L,
  calcium_mg_dL,
  magnesium_mg_dL,
  ammonia_mEq_L,
  chloride_mEq_L,
  phosphate_mg_dL,
  sulfate_mg_dL,
  oxalate_mg_dL,
  citrate_mg_dL,
  pH,
  urate_mg_dL
)

Arguments

sodium_mEq_L, potassium_mEq_L, ammonia_mEq_L, chloride_mEq_L

Concentration of the given species in mEq/L (or a unit value that can be converted to mEq/L)

calcium_mg_dL, magnesium_mg_dL, phosphate_mg_dL, sulfate_mg_dL, oxalate_mg_dL, citrate_mg_dL, urate_mg_dL

Concentration of the given species in mg/dL (or a unit value that can be converted to mg/dL)

pH

The urine pH

Details

This program is intended for research use, only. The code within is translated from Visual Basic code based on Werness, et al 1985 to R. The Visual Basic code was kindly provided by Dr. John Lieske of the Mayo Clinic.

phosphate_mg_dL is the mass of phosphate (PO4, 94.97 g/mol) per dL, and sulfate_mg_dL is the mass of sulfate (SO4, 96.07 g/mol) per dL. U.S. clinical labs typically report "phosphate" and "sulfate" as the mass of the inorganic element (P or S), so a value of 100 mg/dL on a clinical report corresponds to ~32.3 mmol/L of phosphate (P MW 30.97) or ~31.2 mmol/L of sulfate (S MW 32.06). Supplying inputs in mmol/L (or any molar unit) avoids ambiguity.

Value

A data.frame with three columns:

"species" indicating the chemical species
"super_saturation" is the supersaturation ratio. This is SS as defined in Werness 1985.
"neg_delta_Gibbs" which is the negative of the change in Gibbs free energy of transfer from a supersaturated to a saturated solution (the value is negative for under-saturated solutions, zero for solutions at the solubility product, and positive for supersaturated solutions). This is DG as defined in Werness 1985.

References

Werness PG, Brown CM, Smith LH, Finlayson B. Equil2: A Basic Computer Program for the Calculation of Urinary Saturation. Journal of Urology. 1985;134(6):1242-1244. doi:10.1016/S0022-5347(17)47703-2

Examples

# Example values from https://files.labcorp.com/testmenu-d8/sample_reports/306266.pdf
# Phosphate and sulfate inputs are given in mmol/L so the meaning is
# unambiguous: clinical labs often report "phosphate (mg/dL)" as mass of
# inorganic phosphorus (P), but the `mg_phosphate/dL` unit in this package
# is mass of the PO4 ion. See vignette("original-source") for details.
equil2(
  sodium_mEq_L=units::set_units(45, "mmol_sodium/L"),
  potassium_mEq_L=units::set_units(55, "mmol_potassium/L"),
  calcium_mg_dL=units::set_units(15, "mg_calcium/dL"),
  magnesium_mg_dL=units::set_units(15, "mg_magnesium/dL"),
  ammonia_mEq_L=units::set_units(10, "ug_ammonia/dL"),
  chloride_mEq_L=units::set_units(75, "mmol_chloride/L"),
  phosphate_mg_dL=units::set_units(32.285, "mmol_phosphate/L"),
  sulfate_mg_dL=units::set_units(10, "mmol_sulfate/L"),
  oxalate_mg_dL=units::set_units(10, "mg_oxalate/L"),
  citrate_mg_dL=units::set_units(400, "mg_citrate/L"),
  pH=5.5,
  urate_mg_dL=units::set_units(50, "mg_urate/dL")
)

Calculate urine saturation with the EQUIL-2 V1 algorithm

Description

This is a port of the original Mayo Clinic class-based VBA module clsEquil2 ("V1") that predates the form-based BASIC source ported in equil2(). V1 accepts mmol/L (or any molar-convertible unit) inputs, models CO2/bicarbonate chemistry, TRIS buffer, and several ion-pair complexes that V5 omits, and (when chloride is omitted) auto-fills chloride from electroneutrality.

Usage

equil2_v1(
  pH,
  calcium_mmol_L = 0,
  phosphate_mmol_L = 0,
  oxalate_mmol_L = 0,
  sodium_mmol_L = 0,
  potassium_mmol_L = 0,
  magnesium_mmol_L = 0,
  ammonia_mmol_L = 0,
  citrate_mmol_L = 0,
  sulfate_mmol_L = 0,
  urate_mmol_L = 0,
  chloride_mmol_L = NA,
  CO2_mmol_L = 0,
  pyrophosphate_mmol_L = 0,
  TRIS_mmol_L = 0,
  tolerance = 1e-04,
  max_iterations = 500
)

Arguments

pH

The urine pH (unitless).

calcium_mmol_L, phosphate_mmol_L, oxalate_mmol_L, sodium_mmol_L, potassium_mmol_L, magnesium_mmol_L, ammonia_mmol_L, citrate_mmol_L, sulfate_mmol_L, urate_mmol_L

Concentration of each species in mmol/L (or any unit value the units package can convert to mmol/L, e.g. set_units(100, "mg_phosphate/dL")). Defaults to zero.

chloride_mmol_L

Chloride concentration in mmol/L. If NA (the default) chloride is auto-computed via electroneutrality, matching V1's ⁠If TCl = 0 Then ...⁠ block.

CO2_mmol_L

Total CO2 (CO2 + H2CO3 + HCO3- + CO3^2- + carbonate complexes) in mmol/L.

pyrophosphate_mmol_L, TRIS_mmol_L

Total pyrophosphate and TRIS buffer in mmol/L. Note: the V1 source unconditionally sets TPP = 0 after reading the input, so the pyrophosphate chemistry is effectively disabled in V1 (this port preserves that behavior). TRIS is fully supported.

tolerance, max_iterations

Convergence tolerance and iteration cap. Defaults match V1 (1e-4 on the relative change in Ca/Mg/PO4/Ox/Cit/CO2, 500 max iterations).

Details

The V1 algorithm computes mass balance over a wider set of species than V5 (carbonate chemistry, TRIS buffer, struvite in the Mg/NH4 balance, urate-cation complexes in the Na/K/NH4 balance). The output reports activity products and relative saturation ratios (RSRs) for the four crystalline phases V1 itself reports — Calcium Oxalate, Brushite (CaHPO4·2H2O), Struvite (MgNH4PO4), and Uric Acid. For Hydroxyapatite, Sodium Urate, and Ammonium Urate supersaturations (which V1 does not output but V5 does), call equil2() instead.

Inputs are accepted in mmol/L. Supplying mass-based unit values via units::set_units() works (and is more chemically explicit than V5's mg/dL mode), but for phosphate_mmol_L and sulfate_mmol_L, note the same caveat as equil2(): the mg_phosphate/dL unit is the mass of PO4 (94.97 g/mol), not the mass of inorganic phosphorus that U.S. clinical labs typically report.

Value

A list with elements:

supersaturation: a data.frame with columns species, activity_product (mol^2/L^2 or mol^3/L^3 depending on stoichiometry), and RSR (relative saturation ratio; >1 means supersaturated).
ionic_strength: scalar.
activity_factors: named numeric c(F1, F2, F3, F4) for ions of charge 1/2/3/4 respectively.
iterations: number of convergence iterations.
chloride_mmol_L: chloride used (input or electroneutrality-derived).

References

Werness PG, Brown CM, Smith LH, Finlayson B. Equil2: A Basic Computer Program for the Calculation of Urinary Saturation. Journal of Urology. 1985;134(6):1242-1244. doi:10.1016/S0022-5347(17)47703-2

Examples

# Same LabCorp inputs used by equil2()'s example, expressed in mmol/L
equil2_v1(
  pH = 5.5,
  sodium_mmol_L = 45,
  potassium_mmol_L = 55,
  calcium_mmol_L = units::set_units(15, "mg_calcium/dL"),
  magnesium_mmol_L = units::set_units(15, "mg_magnesium/dL"),
  ammonia_mmol_L = units::set_units(10, "ug_ammonia/dL"),
  chloride_mmol_L = 75,
  phosphate_mmol_L = 32.285,
  sulfate_mmol_L = 10,
  oxalate_mmol_L = units::set_units(10, "mg_oxalate/L"),
  citrate_mmol_L = units::set_units(400, "mg_citrate/L"),
  urate_mmol_L = units::set_units(50, "mg_urate/dL")
)

Package {equil2}

Add units to support unit conversion for calculations

Description

Usage

Value

Calculate urine saturation with the EQUIL-2 algorithm

Description

Usage

Arguments

Details

Value

References

Examples

Calculate urine saturation with the EQUIL-2 V1 algorithm

Description

Usage

Arguments

Details

Value

References

See Also

Examples