flowfreq 0.8.0__py3-none-any.whl

flowfreq/__init__.py

@@ -0,0 +1,272 @@
+"""
+flowfreq - Python library for hydrologic analysis
+
+Includes:
+- USGS gage data download (daily and peak flows)
+- Summary hydrograph plotting
+- Bulletin 17C flood frequency analysis:
+  - Method of Moments (MOM)
+  - Expected Moments Algorithm (EMA) with full PeakFQ parity
+- Historical flood information handling
+- Technical report generation
+- One-call analysis workflow (flowfreq.workflow.run_ffa)
+"""
+
+import logging
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _installed_version
+
+from .bulletin17c import (
+    Bulletin17C,
+    ExpectedMomentsAlgorithm,
+    FloodFrequencyAnalysis,
+    MethodOfMoments,
+)
+from .core import (
+    AnalysisMethod,
+    EMAParameters,
+    FlowInterval,
+    FrequencyResults,
+    LowFlowResults,
+    SkewMethod,
+    grubbs_beck_critical_value,
+    kfactor,
+    kfactor_array,
+)
+from .flowio import load_flow_frame, save_flow_frame
+from .hydrograph import Hydrograph
+from .lowflow import LOW_FLOW_YEAR_TYPES, LowFlowFrequency, annual_minimum_flow
+from .qppq import (
+    MONTHLY_SEASONS,
+    SNOWMELT_SEASONS,
+    FlowDurationCurve,
+    QppqResult,
+    apply_lag,
+    center_of_timing,
+    estimate_donor_lag,
+    loocv_qppq,
+    performance,
+    qppq,
+    rank_donors,
+    seasonal_curves,
+)
+from .regime import (
+    BASEFLOW_METHODS,
+    DEFAULT_EXCEEDANCE_PCT,
+    FlowRegime,
+    baseflow_index,
+    diel_variation,
+    diel_variation_summary,
+    flow_duration_curve,
+    monthly_flow_summary,
+    richards_baker_flashiness,
+    seasonal_flow_summary,
+    separate_baseflow,
+    tqmean,
+)
+from .report import HydroReport
+from .transpose import (
+    DEFAULT_AREA_RATIO_RANGE,
+    LOW_FLOW_AREA_RATIO_RANGE,
+    PROBABILITY_KINDS,
+    RegressionExponents,
+    TransposedResults,
+    TranspositionProvenance,
+    transpose_duration,
+    transpose_frequency,
+    transpose_low_flow,
+)
+from .usgs import (
+    GageAttributes,
+    NoInstantaneousDataError,
+    USGSgage,
+    fetch_nwis_batch,
+    fetch_nwis_peaks,
+)
+from .workflow import (
+    B17C_DEFAULT_SKEW,
+    DEFAULT_AEP,
+    DEFAULT_RETURN_INTERVALS,
+    SKEW_OPTIONS,
+    build_skew_curves_dict,
+    compute_skew_tables,
+    run_ffa,
+)
+
+# Alias for backwards compatibility
+USGSGage = USGSgage
+
+logger = logging.getLogger(__name__)
+
+
+def analyze_gage(
+    site_no: str,
+    method: str = "ema",
+    regional_skew: float = None,
+    regional_skew_mse: float = None,
+    historical_peaks: list = None,
+    output_dir: str = "./output",
+) -> dict:
+    """
+    Complete flood frequency analysis for a USGS gage.
+
+    Parameters
+    ----------
+    site_no : str
+        USGS site number
+    method : str
+        'mom' or 'ema' (default: 'ema')
+    regional_skew : float, optional
+        Regional skew coefficient
+    regional_skew_mse : float, optional
+        Mean squared error of regional skew
+    historical_peaks : list of (year, flow) tuples, optional
+        Historical peak observations
+    output_dir : str
+        Output directory
+    """
+    import os
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    logger.info("Downloading data for USGS %s...", site_no)
+    gage = USGSgage(site_no)
+
+    try:
+        gage.download_daily_flow()
+        logger.info("Downloaded %d days of daily flow data", len(gage.daily_data))
+    except Exception as e:
+        logger.warning("Could not download daily flow data: %s", e)
+
+    gage.download_peak_flow()
+    logger.info("Downloaded %d annual peak flow records", len(gage.peak_data))
+    logger.info("Site name: %s", gage.site_name)
+
+    logger.info("Running Bulletin 17C analysis (method=%s)...", method.upper())
+
+    water_years = gage.peak_data["water_year"].values
+
+    analysis = Bulletin17C(
+        gage.peak_data["peak_flow_cfs"].values,
+        water_years=water_years,
+        regional_skew=regional_skew,
+        regional_skew_mse=regional_skew_mse,
+        historical_peaks=historical_peaks,
+    )
+
+    results = analysis.run_analysis(method=method)
+
+    logger.info("Station skew: %.4f", results.skew_station)
+    if results.skew_weighted is not None:
+        logger.info("Weighted skew: %.4f", results.skew_weighted)
+    logger.info("Low outlier threshold: %s cfs", f"{results.low_outlier_threshold:,.0f}")
+
+    if results.method == AnalysisMethod.EMA:
+        logger.info("EMA iterations: %s", results.ema_iterations)
+        logger.info("EMA converged: %s", results.ema_converged)
+
+    logger.info("Generating report and figures...")
+    report = HydroReport(gage, analysis)
+    figures = report.generate_all_figures(output_dir)
+
+    report_path = os.path.join(output_dir, "flood_frequency_report.md")
+    report.save_report(report_path)
+    logger.info("Report saved to: %s", report_path)
+
+    return {
+        "gage": gage,
+        "analysis": analysis,
+        "results": results,
+        "figures": figures,
+        "report_path": report_path,
+    }
+
+
+# Read from the installed distribution rather than repeated here as a
+# literal. The literal drifted every time: it read "0.3.0" through the 0.4.0
+# release (docs/PHASE1_RUNBOOK.md still records it saying so) and "0.4.0"
+# through 0.5.0, 0.6.0 and 0.6.1, so `flowfreq.__version__` has spent most of
+# this project's life reporting a version that was not the one installed.
+# pyproject.toml is the single source of truth; this reads what pip actually
+# installed from it, which cannot disagree.
+try:
+    __version__ = _installed_version("flowfreq")
+except PackageNotFoundError:  # pragma: no cover - only in an uninstalled checkout
+    # No dist-info: someone is importing from a source tree they never
+    # installed. Saying so is better than naming a version that may be wrong.
+    __version__ = "unknown"
+
+__author__ = "FlowFreq"
+
+__all__ = [
+    # Core
+    "AnalysisMethod",
+    "SkewMethod",
+    "FlowInterval",
+    "EMAParameters",
+    "FrequencyResults",
+    "kfactor",
+    "kfactor_array",
+    "grubbs_beck_critical_value",
+    # QPPQ daily-series transfer
+    "FlowDurationCurve",
+    "QppqResult",
+    "qppq",
+    "seasonal_curves",
+    "center_of_timing",
+    "estimate_donor_lag",
+    "apply_lag",
+    "rank_donors",
+    "performance",
+    "loocv_qppq",
+    "SNOWMELT_SEASONS",
+    "MONTHLY_SEASONS",
+    # Transposition to an ungaged site
+    "RegressionExponents",
+    "TransposedResults",
+    "TranspositionProvenance",
+    "transpose_frequency",
+    "transpose_duration",
+    "transpose_low_flow",
+    "PROBABILITY_KINDS",
+    "DEFAULT_AREA_RATIO_RANGE",
+    "LOW_FLOW_AREA_RATIO_RANGE",
+    # Low-flow frequency analysis
+    "LowFlowResults",
+    "LowFlowFrequency",
+    "annual_minimum_flow",
+    "LOW_FLOW_YEAR_TYPES",
+    # Flow regime metrics
+    "FlowRegime",
+    "richards_baker_flashiness",
+    "tqmean",
+    "baseflow_index",
+    "flow_duration_curve",
+    "DEFAULT_EXCEEDANCE_PCT",
+    "separate_baseflow",
+    "monthly_flow_summary",
+    "seasonal_flow_summary",
+    "BASEFLOW_METHODS",
+    "diel_variation",
+    "diel_variation_summary",
+    # USGS data retrieval
+    "USGSgage",
+    "USGSGage",  # Alias for backwards compatibility
+    "GageAttributes",
+    "NoInstantaneousDataError",
+    "fetch_nwis_peaks",
+    "fetch_nwis_batch",
+    "save_flow_frame",
+    "load_flow_frame",
+    # Hydrograph
+    "Hydrograph",
+    # Bulletin 17C
+    "Bulletin17C",
+    "MethodOfMoments",
+    "ExpectedMomentsAlgorithm",
+    "FloodFrequencyAnalysis",
+    # Report
+    "HydroReport",
+    # Convenience
+    "analyze_gage",
+]

flowfreq/_detrat.py

@@ -0,0 +1,202 @@
+"""Native port of peakfq's detrat: the Halloween determinant ratio, Wd.
+
+TODO.md P3's second open item, independent of the ``var_mom``/``mse_ema``
+port (``flowfreq._var_mom``/``flowfreq._mse_ema``). ``Wd`` is HWN's other
+weighting input, alongside ``as_G_mse``: ``emafit.f``::
+
+    nG = n * Wd * as_G_mse / r_G_mse
+
+``Wd`` corrects for something ``as_G_mse`` alone does not capture: on a
+censored record, the at-site mean, variance, and skew estimates are
+correlated with each other, so the skew estimate carries less *independent*
+information than its own marginal MSE suggests. ``detrat`` measures that
+via a determinant ratio -- ``det(I - F)`` for the full (mean, variance,
+skew) system versus the (mean, variance)-only subsystem -- rather than
+treating skew's uncertainty in isolation. Below an at-site skew magnitude of
+0.04 the Fortran short-circuits to ``Wd = 1`` (``emafit.f:3654``); flowfreq
+matches that, so this module is only ever exercised above that floor.
+
+Everything here is a direct, function-for-function transcription of
+``vendor/peakfqr/src/emafit.f``'s ``detrat`` and ``vendor/peakfqr/src/probfun.f``'s
+``EXPMOMCDERIV`` (Greg Schwarz's derivation, cited in-line as "EQ n" the way
+the Fortran comments do), checked against two Fortran oracles
+``build_fortran/_emafort.pyf`` exposes (``expmomcderiv``, and Phase 1's
+``detratsub``) -- see ``tests/fortran_parity/test_fortran_oracles.py``.
+
+``EXPMOMCDERIV`` reuses ``flowfreq._var_mom._dexpect`` for the open-tail
+expected moments and their Jacobian -- the same building block
+``expmomderiv``/``d_est`` use -- rather than a second implementation of the
+same truncated-gamma machinery.
+
+Nothing in this module is wired into ``Bulletin17C``/``ExpectedMomentsAlgorithm``
+yet.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from flowfreq._p3_moments import _fp_g3_cdf, m2p
+from flowfreq._var_mom import _dexpect
+
+__all__ = ["detrat"]
+
+#: emafit.f:3654 -- below this at-site skew magnitude, Wd = 1 outright.
+#: Matches bulletin17c.py's _HWN_SKEW_FLOOR.
+_SKEW_FLOOR = 0.04
+
+#: probfun.f:916 -- EXPMOMCDERIV's own "infinity", log10(1e20). A different
+#: sentinel from flowfreq._var_mom's _D_EST_INF (1e19): this one is in the
+#: same log10(flow) units as tl/tu themselves, not an arbitrarily large
+#: number, and must match exactly for the open-tail Jacobian to line up
+#: with what the Fortran computes.
+_INF = 20.0
+
+#: probfun.f:940 -- below this censoring probability, EXPMOMCDERIV falls
+#: back to the unconditional (-inf, inf) moments/Jacobian rather than
+#: dividing by a near-zero PICK.
+_PICK_FLOOR = 1e-10
+
+
+def _p2m(parms: np.ndarray) -> np.ndarray:
+    """Pearson III params (tau, alpha, beta) -> central moments (mean, var, skew).
+
+    ``probfun.f`` ``P2M`` (line 752): the direct gamma-distribution moment
+    formulas (variance ``alpha*beta**2``, skew ``2/sqrt(alpha)`` signed by
+    beta), not ``m2p``'s inverse via the noncentral-moment route -- though
+    the two agree exactly, since both describe the same distribution.
+    """
+    tau, alpha, beta = float(parms[0]), float(parms[1]), float(parms[2])
+    mean = alpha * beta + tau
+    var = alpha * beta**2
+    skew = 2.0 / math.sqrt(alpha)
+    if beta < 0.0:
+        skew = -skew
+    return np.array([mean, var, skew])
+
+
+def _expmomcderiv(parms: np.ndarray, tl: float, tu: float):
+    """E[X^j | X outside [tl, tu]] and the Jacobian of the resulting expected
+
+    central moments w.r.t. the fit's own central moments (mean, variance,
+    skew). ``probfun.f`` ``EXPMOMCDERIV`` (line 872), Schwarz's EQ 27.
+
+    "Outside [tl, tu]" -- the *censored* region for this threshold group,
+    not the perceived one -- is deliberate: this asks what the moments
+    would look like restricted to exactly the data ``detrat`` never gets to
+    see, which is the whole point of a censoring bias correction.
+    """
+    mc = _p2m(parms)
+    mc1, mc2 = float(mc[0]), float(mc[1])
+    s = math.sqrt(mc2)
+    tau, alpha, beta = float(parms[0]), float(parms[1]), float(parms[2])
+
+    pil = _fp_g3_cdf(tl, parms)
+    pig = 1.0 - _fp_g3_cdf(tu, parms)
+    pick = pil + pig
+
+    if pick > _PICK_FLOOR:
+        mnel, jacl = _dexpect(tau, alpha, beta, -_INF, tl)
+        mneg, jacg = _dexpect(tau, alpha, beta, tu, _INF)
+        mne = (pil * mnel + pig * mneg) / pick
+        jac = (pil * jacl + pig * jacg) / pick
+    else:
+        mne, jac = _dexpect(tau, alpha, beta, -_INF, _INF)
+
+    db = np.array(
+        [
+            [0.0, 0.0, 0.0],
+            [2.0 * mc1, 0.0, 0.0],
+            [-3.0 * mc1**2 / s**3, 3.0 * mc1**3 / (2.0 * s**5), 0.0],
+        ]
+    )
+    b = np.array(
+        [
+            [1.0, 0.0, 0.0],
+            [-2.0 * mc1, 1.0, 0.0],
+            [3.0 * mc1**2 / s**3, -3.0 * mc1 / s**3, 1.0 / s**3],
+        ]
+    )
+    # d(tau, alpha, beta)/d(mean, variance, skew) directly -- not the same
+    # basis as flowfreq._var_mom._dpdm, which differentiates w.r.t.
+    # noncentral moments instead.
+    skew = float(mc[2])
+    tp = np.array(
+        [
+            [1.0, -1.0 / (s * skew), 2.0 * s / skew**2],
+            [0.0, 0.0, -8.0 / skew**3],
+            [0.0, skew / (4.0 * s), s / 2.0],
+        ]
+    )
+    d3 = np.array(
+        [
+            [0.0, 0.0, 0.0],
+            [-2.0 * mne[0], 0.0, 0.0],
+            [
+                6.0 * mc1 / s**3 * mne[0] - 3.0 / s**3 * mne[1],
+                (-4.5 * mc1**2 * mne[0] + 4.5 * mc1 * mne[1] - 1.5 * mne[2]) / s**5,
+                0.0,
+            ],
+        ]
+    )
+
+    dedmc = db + b @ jac @ tp + d3
+    return mc, mne, dedmc
+
+
+def detrat(mc: np.ndarray, n: int, nobs: np.ndarray, tl: np.ndarray, tu: np.ndarray) -> float:
+    """The Halloween determinant ratio, Wd. ``emafit.f`` ``detrat`` (line 3615).
+
+    Parameters
+    ----------
+    mc : central moments (mean, variance, skew) of the at-site fit.
+    n : total record length (not the number of threshold groups).
+    nobs, tl, tu : perception-threshold groups, ``var_mom``'s convention --
+        ``nobs[i]`` observations share the pair ``(tl[i], tu[i])``.
+
+    Returns
+    -------
+    float
+        ``1.0`` below the 0.04 at-site skew floor; otherwise
+        ``det(I - F) / det(I - F[:2, :2])``, the 3x3-vs-2x2 determinant
+        ratio.
+    """
+    skew = float(mc[2])
+    if abs(skew) < _SKEW_FLOOR:
+        return 1.0
+
+    parms = m2p(mc)
+    mc1, mc2 = float(mc[0]), float(mc[1])
+    s = math.sqrt(mc2)
+
+    f0phi = np.zeros((3, 3))
+    for nobs_k, tl_k, tu_k in zip(nobs, tl, tu):
+        pick = 1.0 - (_fp_g3_cdf(tu_k, parms) - _fp_g3_cdf(tl_k, parms))
+        etak = float(nobs_k) / n
+
+        _, mne, dck = _expmomcderiv(parms, tl_k, tu_k)
+
+        # Expected central moments given censored, about the *population*
+        # mean/variance (not the conditional mean) -- Schwarz's EQ 23.
+        mcexpect = np.array(
+            [
+                mne[0],
+                mc1**2 - 2.0 * mc1 * mne[0] + mne[1],
+                (-(mc1**3) + 3.0 * mc1**2 * mne[0] - 3.0 * mc1 * mne[1] + mne[2]) / s**3,
+            ]
+        )
+
+        f1 = np.zeros((3, 3))
+        f1[1, 0] = 2.0 * pick * (mcexpect[0] - mc1)
+        f1[2, 0] = 3.0 * (pick * mcexpect[1] - mc2) / s**3
+        f1[2, 1] = 3.0 * (pick * mcexpect[2] - skew) / (2.0 * mc2)
+
+        f0phi += (f1 + pick * dck) * etak
+
+    imf = np.eye(3) - f0phi
+    imful = imf[:2, :2]
+    det2 = np.linalg.det(imful)
+    det3 = np.linalg.det(imf)
+    return det3 / det2