1 Paquetes

# Instalar los que falten:
# install.packages(c("xts", "zoo", "fitdistrplus", "evd", "PearsonDS"))
library(xts)           # series de tiempo
library(fitdistrplus)  # ajuste de distribuciones y gráficos de bondad de ajuste
library(evd)           # Gumbel y GEV (dgumbel, pgumbel, qgumbel, dgev, ...)
library(PearsonDS)     # Pearson tipo III
library(lubridate)     # manejo de fechas: year(), month(), ...

2 Parámetros del análisis

mes_inicio_anio <- 1      # 1 = año calendario. Para año hidrológico, ej. 10 (octubre)
umbral_completitud <- 0.8 # fracción mínima de días con dato para aceptar un año
periodos_retorno <- c(2, 5, 10, 25, 50, 100, 200, 500)
criterio <- "aic"         # criterio de selección: "aic", "bic", "ks", "cvm" o "ad"
n_boot <- 500             # remuestreos para intervalos de confianza

3 Datos

Se espera un objeto xts con caudales máximos diarios. Cambia el nombre q_diario por el de tu objeto. Si el objeto no existe, se genera una serie sintética solo para que el cuaderno se pueda ejecutar de ejemplo.

serie_diaria <- read.csv("~/02. Profesionales/DOCENCIA/HIDROLOGIA-UNAL/PREPARACION/21017030.csv") |> 
  (\(x) as.xts(x$Valor, order.by = as.Date(x$Fecha)))()


fecha_inicial <- min(index(serie_diaria))
fecha_final   <- max(index(serie_diaria))
fechas        <- seq(fecha_inicial, fecha_final, by = "day")

serie_diaria <- cbind(
  serie_diaria,
  xts(order.by = fechas)   # serie vacía solo con el calendario completo
)


summary(as.numeric(serie_diaria))
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.    NA's 
##   5.455  47.827  82.016 116.444 145.776 963.547      56
plot(serie_diaria, main = "Caudales máximos diarios", ylab = "Q (m³/s)")

4 Serie de máximos anuales

agregar <- function(x) {
  if (sum(!is.na(x)) < umbral_completitud * length(x)) {
    return(NA)
  } else {
    return(max(x, na.rm = TRUE))
  }
}

qmax_xts <- aggregate(serie_diaria, by = year(index(serie_diaria)), agregar)

qmax_xts <- as.xts(qmax_xts, as.Date(paste0(index(qmax_xts), "-01-01")))

tabla_anual <- data.frame(anio = lubridate::year(index(qmax_xts)),
                          Qmax = as.numeric(qmax_xts))
plot(tabla_anual$anio, tabla_anual$Qmax, type = "h", lwd = 3, col = "steelblue",
     xlab = "Año", ylab = "Q máximo anual (m³/s)", main = "Máximos anuales")
points(tabla_anual$anio, tabla_anual$Qmax, pch = 19, col = "steelblue")

4.1 Verificación rápida de los supuestos

El análisis de frecuencia supone una muestra aleatoria, independiente y estacionaria. Aquí se verifica con un test de tendencia (Kendall) y con la autocorrelación.

kt <- cor.test(tabla_anual$anio, tabla_anual$Qmax, method = "kendall")
cat("Test de tendencia (Mann-Kendall vía Kendall tau): tau =", round(kt$estimate, 3),
    "| p-valor =", round(kt$p.value, 4), "\n")
## Test de tendencia (Mann-Kendall vía Kendall tau): tau = -0.09 | p-valor = 0.7194
# p < 0.05 sugiere tendencia, es decir, serie no estacionaria
acf(tabla_anual$Qmax, main = "Autocorrelación de los máximos anuales")

5 Distribuciones de probabilidad candidatas

Además de las distribuciones de R base (Normal, Log-Normal, Gamma, Weibull) se incluyen Gumbel, GEV, Pearson tipo III y Log-Pearson tipo III. Estas últimas se definen a continuación para que fitdistrplus pueda usarlas.

# --- Pearson III (paquete PearsonDS), con parámetros: shape, location, scale
dpe3 <- function(x, shape, location, scale) dpearsonIII(x, shape = shape, location = location, scale = scale)
ppe3 <- function(q, shape, location, scale) ppearsonIII(q, shape = shape, location = location, scale = scale)
qpe3 <- function(p, shape, location, scale) qpearsonIII(p, shape = shape, location = location, scale = scale)

# --- Log-Pearson III: log(X) ~ Pearson III
dlp3 <- function(x, shape, location, scale) dpearsonIII(log(x), shape = shape, location = location, scale = scale) / x
plp3 <- function(q, shape, location, scale) ppearsonIII(log(q), shape = shape, location = location, scale = scale)
qlp3 <- function(p, shape, location, scale) exp(qpearsonIII(p, shape = shape, location = location, scale = scale))

# Valores iniciales de Pearson III por el método de momentos
inicio_pe3 <- function(y) {
  m <- mean(y); s <- sd(y)
  g <- mean(((y - m) / s)^3)
  if (abs(g) < 0.1) g <- sign(g + 1e-9) * 0.1   # evita asimetría ~ 0
  shape <- 4 / g^2
  scale <- sign(g) * s / sqrt(shape)
  list(shape = shape, location = m - shape * scale, scale = scale)
}

# Valores iniciales de Gumbel / GEV por momentos
sc_gum <- sd(tabla_anual$Qmax) * sqrt(6) / pi
loc_gum <- mean(tabla_anual$Qmax) - 0.5772 * sc_gum
ajustar <- function(datos, dist, start = NULL, ...) {
  tryCatch(fitdist(datos, dist, start = start, ...),
           error = function(e) { message("No se pudo ajustar ", dist, ": ", e$message); NULL })
}

fits <- list(
  "Normal"         = ajustar(tabla_anual$Qmax, "norm"),
  "Log-Normal"     = ajustar(tabla_anual$Qmax, "lnorm"),
  "Gamma"          = ajustar(tabla_anual$Qmax, "gamma", method = "mme"),
  "Weibull"        = ajustar(tabla_anual$Qmax, "weibull"),
  "Gumbel"         = ajustar(tabla_anual$Qmax, "gumbel", start = list(loc = loc_gum, scale = sc_gum))
  # "GEV"            = ajustar(tabla_anual$Qmax, "gev",    start = list(loc = loc_gum, scale = sc_gum, shape = 0.1)),
  # "Pearson III"    = ajustar(tabla_anual$Qmax, "pe3", start = inicio_pe3(tabla_anual$Qmax)),
  # "Log-Pearson III"= ajustar(log(tabla_anual$Qmax), "pe3", start = inicio_pe3(log(tabla_anual$Qmax)))  # parámetros en escala log
)

# Para Log-Pearson III se reajusta con las funciones definidas sobre la escala original
# (así las comparaciones de AIC y gráficos son sobre la misma variable X)
fits[["Log-Pearson III"]] <- ajustar(x, "lp3", start = inicio_pe3(log(x)))

fits <- Filter(Negate(is.null), fits)

5.1 Parámetros estimados

for (nm in names(fits)) {
  cat("\n---", nm, "---\n")
  print(round(fits[[nm]]$estimate, 4))
}
## 
## --- Normal ---
##     mean       sd 
## 723.8838 154.9773 
## 
## --- Log-Normal ---
## meanlog   sdlog 
##  6.5599  0.2267 
## 
## --- Gamma ---
##   shape    rate 
## 21.8173  0.0301 
## 
## --- Weibull ---
##    shape    scale 
##   5.4836 786.0577 
## 
## --- Gumbel ---
##      loc    scale 
## 645.1245 146.7325

6 Comparación gráfica: función de probabilidad teórica vs. empírica

La probabilidad empírica usa la posición de graficación de Weibull, i/(n+1).

6.1 Todas las distribuciones juntas

cols <- rainbow(length(fits))
cdfcomp(fits, legendtext = names(fits), main = "Función de distribución acumulada: empírica vs. teóricas",
        xlab = "Q máximo anual (m³/s)", ylab = "F(x)", use.ppoints = TRUE, a.ppoints = 0,
        fitcol = cols, fitlty = 1, datapch = 19)

denscomp(fits, legendtext = names(fits), main = "Densidad: histograma vs. teóricas",
         xlab = "Q máximo anual (m³/s)", fitcol = cols, fitlty = 1)

6.2 Una gráfica por distribución

Para cada distribución: densidad, CDF, Q-Q y P-P.

for (nm in names(fits)) {
  cat("\n\n### ", nm, "\n\n")
  f <- list(fits[[nm]])
  par(mfrow = c(2, 2))
  denscomp(f, legendtext = nm, main = "Densidad", fitcol = "firebrick", fitlty = 1)
  cdfcomp(f, legendtext = nm, main = "CDF empírica vs. teórica", fitcol = "firebrick",
          fitlty = 1, use.ppoints = TRUE, a.ppoints = 0)
  qqcomp(f, legendtext = nm, main = "Q-Q", fitcol = "firebrick", use.ppoints = TRUE, a.ppoints = 0)
  ppcomp(f, legendtext = nm, main = "P-P", fitcol = "firebrick", use.ppoints = TRUE, a.ppoints = 0)
  par(mfrow = c(1, 1))
}

6.2.1 Normal

6.2.2 Log-Normal

6.2.3 Gamma

6.2.4 Weibull

6.2.5 Gumbel

7 Bondad de ajuste y selección

Se calculan los estadísticos de Kolmogorov-Smirnov, Cramér-von Mises y Anderson-Darling (menor es mejor), y los criterios AIC y BIC (menor es mejor).

gof <- gofstat(fits, fitnames = names(fits))

tabla_gof <- data.frame(
  Distribucion = names(fits),
  n_param = sapply(fits, function(f) length(f$estimate)),
  KS  = round(as.numeric(gof$ks),  4),
  CvM = round(as.numeric(gof$cvm), 4),
  AD  = round(as.numeric(gof$ad),  4),
  AIC = round(as.numeric(gof$aic), 2),
  BIC = round(as.numeric(gof$bic), 2),
  row.names = NULL
)
tabla_gof <- tabla_gof[order(tabla_gof[[toupper(criterio)]]), ]
tabla_gof

Nota: los estadísticos KS, CvM y AD con parámetros estimados a partir de los mismos datos son orientativos (los p-valores estándar no aplican directamente). Conviene usarlos como ranking, junto con los gráficos.

mejor <- tabla_gof$Distribucion[1]
cat("Mejor distribución según", toupper(criterio), ":", mejor, "\n")
## Mejor distribución según AIC : Weibull
# Si prefieres elegirla manualmente, descomenta y cambia:
# mejor <- "GEV"
par(mfrow = c(2, 2))
fm <- list(fits[[mejor]])
denscomp(fm, legendtext = mejor, main = paste("Densidad -", mejor), fitcol = "darkgreen", fitlty = 1)
cdfcomp(fm, legendtext = mejor, main = paste("CDF -", mejor), fitcol = "darkgreen", fitlty = 1, 
        use.ppoints = TRUE, a.ppoints = 0)
qqcomp(fm, legendtext = mejor, main = "Q-Q", fitcol = "darkgreen", use.ppoints = TRUE, a.ppoints = 0)
ppcomp(fm, legendtext = mejor, main = "P-P", fitcol = "darkgreen", use.ppoints = TRUE, a.ppoints = 0)

par(mfrow = c(1, 1))

8 Caudales para diferentes periodos de retorno

Para un periodo de retorno T, el caudal de diseño es el cuantil de probabilidad de no excedencia p = 1 − 1/T de la distribución seleccionada. Los intervalos de confianza (95 %) se obtienen por bootstrap paramétrico.

fit_mejor <- fits[[mejor]]
nombre_dist <- fit_mejor$distname   # "norm", "lnorm", "gev", "lp3", ...
qfun <- get(paste0("q", nombre_dist))
p_nexc <- 1 - 1 / periodos_retorno

cuantil <- function(par) do.call(qfun, c(list(p_nexc), as.list(par)))

# Estimación puntual
q_est <- cuantil(fit_mejor$estimate)

# Intervalos por bootstrap paramétrico
set.seed(42)
boot <- bootdist(fit_mejor, bootmethod = "param", niter = n_boot)
q_boot <- t(apply(boot$estim, 1, function(par) tryCatch(cuantil(par), error = function(e) rep(NA, length(p_nexc)))))
ic <- apply(q_boot, 2, quantile, probs = c(0.025, 0.975), na.rm = TRUE)

tabla_Tr <- data.frame(
  T_anios = periodos_retorno,
  prob_excedencia = round(1 / periodos_retorno, 4),
  Q_m3s = round(q_est, 2),
  IC95_inf = round(ic[1, ], 2),
  IC95_sup = round(ic[2, ], 2)
)
tabla_Tr
# Curva de frecuencia: Q vs. periodo de retorno (eje log)
T_emp <- (nrow(tabla_anual) + 1) / rank(-tabla_anual$Qmax)             # Weibull
T_seq <- exp(seq(log(1.01), log(max(periodos_retorno)), length.out = 200))
q_seq <- do.call(qfun, c(list(1 - 1 / T_seq), as.list(fit_mejor$estimate)))

# bandas de confianza para la curva
q_boot_seq <- t(apply(boot$estim, 1, function(par)
  tryCatch(do.call(qfun, c(list(1 - 1 / T_seq), as.list(par))), error = function(e) rep(NA, length(T_seq)))))
ic_seq <- apply(q_boot_seq, 2, quantile, probs = c(0.025, 0.975), na.rm = TRUE)

plot(T_emp, tabla_anual$Qmax, log = "x", pch = 19, col = "steelblue",
     xlim = c(1, max(periodos_retorno)), ylim = range(tabla_anual$Qmax, ic_seq, na.rm = TRUE),
     xlab = "Periodo de retorno T (años, escala log)", ylab = "Q (m³/s)",
     main = paste("Curva de frecuencia -", mejor))
lines(T_seq, q_seq, col = "darkgreen", lwd = 2)
lines(T_seq, ic_seq[1, ], col = "darkgreen", lty = 2)
lines(T_seq, ic_seq[2, ], col = "darkgreen", lty = 2)
points(periodos_retorno, q_est, pch = 17, col = "red", cex = 1.2)
grid()
legend("topleft", c("Datos (Weibull)", paste("Ajuste", mejor), "IC 95 %", "Periodos de retorno"),
       pch = c(19, NA, NA, 17), lty = c(NA, 1, 2, NA), col = c("steelblue", "darkgreen", "darkgreen", "red"), bty = "n")

9 Exportar resultados

write.csv(tabla_anual, "maximos_anuales.csv", row.names = FALSE)
write.csv(tabla_gof,   "bondad_ajuste.csv",   row.names = FALSE)
write.csv(tabla_Tr,    "caudales_periodo_retorno.csv", row.names = FALSE)

10 Información de la sesión

sessionInfo()
## R version 4.5.0 (2025-04-11 ucrt)
## Platform: x86_64-w64-mingw32/x64
## Running under: Windows 11 x64 (build 22631)
## 
## Matrix products: default
##   LAPACK version 3.12.1
## 
## locale:
## [1] LC_COLLATE=Spanish_Spain.utf8  LC_CTYPE=Spanish_Spain.utf8   
## [3] LC_MONETARY=Spanish_Spain.utf8 LC_NUMERIC=C                  
## [5] LC_TIME=Spanish_Spain.utf8    
## 
## time zone: America/Bogota
## tzcode source: internal
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] lubridate_1.9.4    PearsonDS_1.3.2    evd_2.3-7.1        fitdistrplus_1.2-6
## [5] survival_3.8-3     MASS_7.3-65        xts_0.14.1         zoo_1.8-14        
## 
## loaded via a namespace (and not attached):
##  [1] vctrs_0.6.5       cli_3.6.5         knitr_1.50        rlang_1.1.6      
##  [5] xfun_0.52         generics_0.1.4    jsonlite_2.0.0    htmltools_0.5.8.1
##  [9] sass_0.4.10       rmarkdown_2.29    grid_4.5.0        evaluate_1.0.5   
## [13] jquerylib_0.1.4   fastmap_1.2.0     yaml_2.3.10       lifecycle_1.0.4  
## [17] compiler_4.5.0    timechange_0.3.0  rstudioapi_0.19.0 lattice_0.22-6   
## [21] digest_0.6.37     R6_2.6.1          splines_4.5.0     bslib_0.9.0      
## [25] Matrix_1.7-3      tools_4.5.0       cachem_1.1.0