hydrochem Hidroquímica reproducible en R, de la tabla del laboratorio al diagrama de Piper

install.packages("hydrochem") library(hydrochem) data(hc_data); data(data_qc)

Versión 0.1.0 en CRAN (junio de 2026), de G. Cinkus y R. Bondu. Chuleta de referencia rápida; los detalles y los ejemplos completos están en la guía Quarto.

Cationes

Ca27 %

Mg23 %

Na48 %

Aniones

HCO₃33 %

SO₄26 %

Cl41 %

Una muestra real de data_qc (S72) en % de meq/L, como la dibuja plot_stabler(): 16,2 meq/L de cationes frente a 17,1 de aniones, facies Na-Cl. Casi todo el paquete gira en torno a esta conversión.

1Prepara la tabla

Una fila por muestra y una columna por parámetro (formato ancho).
Nombres exactos, con mayúsculas: Ca, no calcio ni CA.
Una sola unidad para todos los iones; se declara en base_unit (por defecto, mg/L).
Los valores bajo el límite de detección pueden venir como texto: "<0.5".
Se pueden añadir otras columnas (punto, fecha, acuífero, grupo).

id	Ca	Mg	Na	K	HCO3	Cl	SO4	NO3
P-01	85.2	21.4	18.9	2.1	290	31.5	62	<1
P-02	120	35	95	4.5	310	160	180	28

Columnas que reconoce

CaMgNaK HCO3CO3ClSO4NO3 pHSiO2NO3_NNH4_NPO4_PFeMnSrBrF

cationes mayoritarios aniones mayoritarios otros. Hay 72 en total: hydrochem:::ions_meta.

Los sufijos _N, _P indican concentración expresada como elemento: 10 mg/L de NO₃-N son 44,3 mg/L de NO₃.

Del formato largo del laboratorio al ancho

datos <- lab_largo |>
  # equiv: c(Calcio = "Ca", ...)
  mutate(parametro = equiv[parametro]) |>
  pivot_wider(names_from = parametro,
              values_from = valor) |>
  replace_bdl()

Datos de ejemplo

hc_data: 59 muestras con los iones mayoritarios en mg/L y un grupo type (A, B, C). No tiene CO₃ ni pH.
data_qc: 146 aguas subterráneas de Quebec, con 55 columnas: pH, iones traza con valores censurados, isótopos, condición hidráulica (Hydro_cond) y clúster.

2Depura y controla

replace_bdl(data, method = "DL/2")

Convierte "<0.01" en número: LD/2, LD/√2, LD, 0 o NA. Solo toca las columnas con algún «<».

Devuelve un data.table.

convert_unit(data, ions, to_unit = "meq/L")

Pasa de mg/L a mmol/L o meq/L y viceversa. Añade columnas Ca_meq, Ca_mmol… Con convert_to_species = TRUE, NO3_N pasa a NO₃.

meq/L = mg/Lmasa molar × |carga| 80 mg/L de Ca²⁺ son 4,0 meq/L; 80 mg/L de Na⁺, 3,5 meq/L.

ionic_balance(data, method = "major")

Error de balance iónico (%). Por electroneutralidad, cationes y aniones en meq/L deberían igualarse. Es el primer filtro antes de interpretar.

EB = 100 × Σcat − ΣanΣcat + Σan Criterio habitual: |EB| ≤ 5 % (hasta 10 % en aguas poco mineralizadas). "major_minor" suma Fe, Mn, Sr, Br, F…

hydrochem::stat_summary(data, params, group, stats)

Resumen descriptivo completo: percentiles, media geométrica, CV, MAD, n.º de datos y de NA, por grupos si se pide.

Usa siempre el prefijo: choca con ggplot2::stat_summary().

3Caracteriza el agua

water_type(data, format = "short")

Facies: catión y anión dominantes en % meq/L, como "Ca-HCO3". Con "long" lista todos los que superan threshold (20 %): "Ca-Mg-HCO3-SO4".

tds(data, method = "major")

Sólidos disueltos como suma de iones en mg/L. Otros métodos: "major_si" (+SiO₂) y "all_ions".

No es el residuo seco: al evaporar, el HCO₃ conserva solo el 49 % de su masa.

total_hardness(data, output = "mg/L_CaCO3")

Dureza = 50 × (Ca + Mg) en meq/L, en mg/L de CaCO₃. También en "fH", "dH" o "e". Por encima de 180 mg/L, agua muy dura.

total_alkalinity(data, output = "meq/L")

HCO₃ + 2 CO₃ (+ OH − H). Necesita pH, por eso se prueba con data_qc.

Todo en un pipe

qc <- data_qc |>
  replace_bdl() |>
  as_tibble() |>
  mutate(
    eb = ionic_balance(pick(everything())),
    facies = water_type(pick(everything())),
    SAR = sar(pick(everything()))
  ) |>
  filter(abs(eb) <= 5)

plot_piper(qc, group = "Hydro_cond")

Los cálculos devuelven un vector por fila: encajan en mutate() con pick(everything()).

4Índices

Todos se calculan en meq/L (la conversión es interna) y se llaman igual: f(data, base_unit).

Índice	Fórmula
SAR `sar()`	Na / √((Ca+Mg)/2) Sodificación del suelo. < 10 excelente; > 26 inadecuada.
%Na `percent_sodium()`	100·Na / (Ca+Mg+Na+K) Wilcox. < 20 excelente; > 60 dudosa.
Kelly `kelly_ratio()`	Na / (Ca+Mg) > 1: exceso de sodio.
RSC `rsc()`	(HCO₃+CO₃) − (Ca+Mg) Carbonato sódico residual. > 2,5 meq/L inadecuada.
PI `permeability_index()`	100·(Na+√HCO₃) / (Ca+Mg+Na) Doneen. < 25 %: clase III, no apta.
MH `magnesium_hazard()`	100·Mg / (Ca+Mg) > 50 % perjudicial.
CAI-1 `cai1()`	(Cl − (Na+K)) / Cl > 0: el agua cede Na al terreno (intercambio inverso, intrusión salina). < 0: lo toma (intercambio directo).
CAI-2 `cai2()`	(Cl − (Na+K)) / (SO₄+HCO₃+CO₃+NO₃) Misma lectura. Necesita NO₃ (o NO₃_N).

Umbrales orientativos de la bibliografía clásica (Richards 1954, Wilcox 1955, Eaton 1950, Doneen 1964…); no los da el paquete.

Todos de una vez con purrr

ind <- list(SAR = sar, KR = kelly_ratio,
  MH = magnesium_hazard, CAI1 = cai1)
hc_data |>
  select(id, type) |>
  bind_cols(map(ind, \(f) f(hc_data)))

5DibujaTodos devuelven un objeto ggplot: se retocan con `+ labs()` o `+ theme()`

Clasificar muchas muestras: proporciones en triángulos

Diagrama de Piper de data_qc agrupado por condición hidráulica — plot_piper()Piper
Triángulo de cationes, de aniones y rombo, en % meq/L. Facies de un vistazo; las mezclas se alinean.
`include_NO3` `group` `label`

Diagrama de Durov con paneles de pH y TDS — plot_durov()Durov
Los triángulos proyectados en un cuadrado, con paneles de pH y TDS alineados. Requiere `pH`.
`plot_pH` `plot_TDS` `tds_log` `top_ions`

Diagrama ternario Ca-Mg-Na de data_qc — plot_ternary()Ternario libre
Tres solutos cualesquiera (incluso de distinto signo), normalizados en mmol/L o mg/L.
`first` `second` `third` `to_unit` `*_label`

Comparar perfiles y procesos

Diagrama de Schoeller coloreado por grupo — plot_schoeller()Schoeller
Una línea por muestra en meq/L, escala logarítmica. Líneas paralelas: mismas proporciones, distinta concentración.
`mg_guide` `include_NO3` `line_color`

Diagrama de Gibbs — plot_gibbs()Gibbs
TDS frente a Na/(Na+Ca) y Cl/(Cl+HCO₃): dominio de la lluvia, de la roca o de la evaporación. Cocientes en mg/L.
`show_text` `show_guide` `tds_method`

Biplots Na-Cl, Ca+Mg-HCO3 y Ca-SO4 con recta 1:1 — plot_biplot(pairs = "Na ~ Cl")Relaciones iónicas
Expresiones `"y ~ x"` con recta de referencia: Na:Cl 1:1 (halita), Ca+Mg:HCO₃ (carbonatos), Ca:SO₄ (yeso).
`slope` `intercept` `log_x` `log_y` `ncol`

Huella química de cada muestra: un panel por fila

Diagramas de Stiff de tres muestras — plot_stiff()Stiff
Polígono en meq/L: la forma dice la facies y el tamaño, la mineralización. Ideal como símbolo en mapas.
`idcol` `scales = "free_x"` `include_NO3 = "Cl"`

Diagramas de barras de Collins — plot_collins()Collins
Dos columnas apiladas, cationes y aniones, en % meq/L.
`idcol` `ncol` `show_label`

Diagramas de barras de Stabler — plot_stabler()Stabler
Las mismas proporciones en barras horizontales, como la cabecera de esta hoja.
`idcol` `ratio` `facet_dir`

Argumentos que comparten

base_unit: unidad de los datos.
group = "type": colorea por una columna.
group_custom = TRUE con vectores fill, color, shape, size: un valor por grupo, en orden alfabético (o en el de los niveles, si la columna es factor).
label: columna de etiquetas, con label_nudge_x y label_nudge_y.
legend.position, legend.title, plot_title, bg_color.

plot_piper(hc_data, group = "type",
  group_custom = TRUE,
  fill  = c("steelblue", "tomato", "gold"),
  shape = c(21, 22, 24))

El orden de los paneles de Stiff, Collins y Stabler es el de las filas: ordena antes con arrange().

Guardar

p <- plot_piper(hc_data)
save_plot("piper.png", type = "piper",
          plot = p)  # 300 ppp

type fija un tamaño adecuado a cada diagrama; width y height lo cambian.

Antes de fiarte del resultado

Lee los mensajes "... computed with: ...": dicen qué iones han entrado. Una columna mal nombrada se ignora sin error.
CO3 is missing es un aviso, no un error: se calcula sin carbonato.
Unidades distintas en una misma tabla (mg/L y µg/L): homogeneiza antes.
convert_unit(), replace_bdl() y stat_summary() devuelven data.table; as_tibble() lo resuelve.

R 4.3 o anterior: con group sin group_custom todos los puntos salen del mismo color y sin leyenda. La guía incluye un parche de cinco líneas.