heatwave3 1.4.0__tar.gz

heatwave3-1.4.0/CMakeLists.txt

@@ -0,0 +1,108 @@
+# Python build of heatwave3 (driven by scikit-build-core via pyproject.toml).
+# Compiles the language-neutral C++ core in src/ plus the pybind11 bindings in
+# python/src/. The R package's Rcpp files in src/ are not compiled here.
+
+cmake_minimum_required(VERSION 3.18...3.30)
+project(${SKBUILD_PROJECT_NAME} LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
+find_package(pybind11 CONFIG REQUIRED)
+find_package(Threads REQUIRED)
+
+pybind11_add_module(_core
+  python/src/bindings.cpp
+  src/netcdf_io.cpp
+  src/climatology.cpp
+  src/event_detect.cpp
+  src/hw3_api.cpp
+  src/blob_core.cpp
+  src/hw3_h5chunk.cpp
+)
+target_include_directories(_core PRIVATE src)
+target_compile_definitions(_core PRIVATE HW3_VERSION="${SKBUILD_PROJECT_VERSION_FULL}")
+target_link_libraries(_core PRIVATE Threads::Threads)
+# Keep the path to libnetcdf in the installed module's rpath, so the wheel
+# repair tools (auditwheel, delocate) can find the library to bundle.
+set_target_properties(_core PROPERTIES INSTALL_RPATH_USE_LINK_PATH TRUE)
+
+# libnetcdf: netCDFConfig.cmake first, then nc-config, then pkg-config
+# (mirrors the R package's configure script).
+find_package(netCDF CONFIG QUIET)
+if(netCDF_FOUND)
+  message(STATUS "netCDF ${netCDF_VERSION} via netCDFConfig.cmake")
+  target_link_libraries(_core PRIVATE netCDF::netcdf)
+else()
+  find_program(NC_CONFIG nc-config)
+  if(NC_CONFIG)
+    message(STATUS "netCDF via ${NC_CONFIG}")
+    execute_process(COMMAND ${NC_CONFIG} --cflags OUTPUT_VARIABLE NC_CFLAGS
+                    OUTPUT_STRIP_TRAILING_WHITESPACE)
+    execute_process(COMMAND ${NC_CONFIG} --libs OUTPUT_VARIABLE NC_LIBS
+                    OUTPUT_STRIP_TRAILING_WHITESPACE)
+    separate_arguments(NC_CFLAGS UNIX_COMMAND "${NC_CFLAGS}")
+    separate_arguments(NC_LIBS UNIX_COMMAND "${NC_LIBS}")
+    target_compile_options(_core PRIVATE ${NC_CFLAGS})
+    target_link_libraries(_core PRIVATE ${NC_LIBS})
+  else()
+    find_package(PkgConfig REQUIRED)
+    pkg_check_modules(NETCDF REQUIRED IMPORTED_TARGET netcdf)
+    message(STATUS "netCDF ${NETCDF_VERSION} via pkg-config")
+    target_link_libraries(_core PRIVATE PkgConfig::NETCDF)
+  endif()
+endif()
+
+# Optional: compress gridded outputs on all threads (src/hw3_h5chunk.cpp),
+# which needs HDF5 >= 1.10.3 and zlib. Use the HDF5 that libnetcdf uses (the
+# wheels point HDF5_ROOT at the prefix built by python/tools/build_netcdf.sh)
+# and check that its headers match the library; otherwise outputs are written
+# by netCDF on one thread. Disable with -DHW3_HDF5=OFF.
+option(HW3_HDF5 "Compress gridded outputs on all threads (HDF5 >= 1.10.3 + zlib)" ON)
+set(HW3_HDF5_USED OFF)
+if(HW3_HDF5)
+  find_package(ZLIB QUIET)
+  find_package(HDF5 QUIET COMPONENTS C)
+  if(HDF5_FOUND AND ZLIB_FOUND)
+    # Only libhdf5 itself (FindHDF5 also lists its dependencies, e.g. curl)
+    if(HDF5_C_LIBRARY_hdf5)
+      set(HW3_H5_LIBS ${HDF5_C_LIBRARY_hdf5})
+    else()
+      set(HW3_H5_LIBS ${HDF5_C_LIBRARIES})
+    endif()
+    if(NOT HW3_H5_LIBS)
+      set(HW3_H5_LIBS ${HDF5_LIBRARIES})
+    endif()
+    include(CheckCXXSourceRuns)
+    set(CMAKE_REQUIRED_INCLUDES ${HDF5_INCLUDE_DIRS} ${ZLIB_INCLUDE_DIRS})
+    set(CMAKE_REQUIRED_LIBRARIES ${HW3_H5_LIBS} ZLIB::ZLIB)
+    set(CMAKE_REQUIRED_DEFINITIONS ${HDF5_DEFINITIONS})
+    check_cxx_source_runs([=[
+#include <hdf5.h>
+#include <zlib.h>
+int main() {
+  unsigned a, b, c;
+  auto wc = &H5Dwrite_chunk;
+  auto cz = &compress2;
+  if (!wc || !cz || H5get_libversion(&a, &b, &c) < 0) return 1;
+  return (a == H5_VERS_MAJOR && b == H5_VERS_MINOR && c == H5_VERS_RELEASE) ? 0 : 2;
+}]=] HW3_HDF5_WORKS)
+    unset(CMAKE_REQUIRED_INCLUDES)
+    unset(CMAKE_REQUIRED_LIBRARIES)
+    unset(CMAKE_REQUIRED_DEFINITIONS)
+    if(HW3_HDF5_WORKS)
+      target_compile_definitions(_core PRIVATE HW3_HAVE_HDF5 ${HDF5_DEFINITIONS})
+      target_include_directories(_core PRIVATE ${HDF5_INCLUDE_DIRS})
+      target_link_libraries(_core PRIVATE ${HW3_H5_LIBS} ZLIB::ZLIB)
+      set(HW3_HDF5_USED ON)
+    endif()
+  endif()
+endif()
+if(HW3_HDF5_USED)
+  message(STATUS "HDF5 ${HDF5_VERSION} for parallel compression: ${HW3_H5_LIBS}")
+else()
+  message(STATUS "HDF5 for parallel compression: not used (gridded outputs are compressed on one thread)")
+endif()
+
+install(TARGETS _core LIBRARY DESTINATION heatwave3)

heatwave3-1.4.0/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 heatwave3 authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

heatwave3-1.4.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: heatwave3
+Version: 1.4.0
+Summary: Detect marine heatwaves and cold-spells directly in gridded NetCDF data
+Keywords: marine heatwave,cold-spell,climatology,NetCDF,oceanography
+Author-Email: "Robert W. Schlegel" <robwschlegel@gmail.com>, "Albertus J. Smit" <albertus.smit@gmail.com>
+Maintainer-Email: "Robert W. Schlegel" <robwschlegel@gmail.com>, "Albertus J. Smit" <albertus.smit@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Project-URL: Homepage, https://github.com/robwschlegel/heatwave3
+Project-URL: Documentation, https://heatwave3.readthedocs.io
+Project-URL: Source, https://github.com/robwschlegel/heatwave3
+Project-URL: R package, https://robwschlegel.github.io/heatwave3/
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=10; extra == "parquet"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.6; extra == "plot"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pyarrow>=10; extra == "test"
+Requires-Dist: matplotlib>=3.6; extra == "test"
+Description-Content-Type: text/markdown
+
+# heatwave3
+
+Detect marine heatwaves (MHWs) and marine cold-spells (MCSs) directly in
+gridded NetCDF data, following the Hobday et al. (2016, 2018) definitions.
+
+`heatwave3` is the Python interface to the same C++ core as the
+[heatwave3 R package](https://robwschlegel.github.io/heatwave3/): climatology,
+event detection, categorisation and blob detection run in multi-threaded C++
+with direct NetCDF I/O. Function names, arguments and outputs match the R
+package, so code translates line for line.
+
+```python
+import heatwave3 as hw3
+
+# Climatology + events (+ categories, + daily series) in one call
+out = hw3.detect3("sst.nc", "results/run1", ("1982-01-01", "2011-12-31"),
+                  category=True, daily="also", n_threads=4)
+
+events = hw3.hw3_export(out["events"])                       # pandas DataFrame
+daily = hw3.hw3_export(out["daily"], time_range=("2023-01-01", "2023-12-31"))
+hw3.hw3_export(out["events"], file_out="events.parquet")     # or .csv
+```
+
+Also available: `ts2clm3()`, `detect_event3()`, `category3()`,
+`category_daily3()`, `block_average3()`, `exceedance3()`, `detect_blob3()`
+(spatially connected events), `getHW3threads()` and `setHW3threads()`, and,
+with `pip install heatwave3[plot]`, the matplotlib plots `event_line3()`,
+`plot_metric3()`, `geom_flame3()` and `geom_lolli3()`. The one
+naming difference from R: `detect_blob3()`'s `return` argument is `return_`,
+because `return` is a Python keyword.
+
+Documentation: <https://heatwave3.readthedocs.io>
+
+Its version is pinned to the R package's: heatwave3 1.4.0 in Python has the
+same functions and outputs as heatwave3 1.4.0 in R.

heatwave3-1.4.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["scikit-build-core>=0.10", "pybind11>=2.13"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "heatwave3"
+version = "1.4.0"  # pinned to Version in DESCRIPTION (R): same features
+description = "Detect marine heatwaves and cold-spells directly in gridded NetCDF data"
+readme = "python/README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE.md"]
+authors = [
+  { name = "Robert W. Schlegel", email = "robwschlegel@gmail.com" },
+  { name = "Albertus J. Smit", email = "albertus.smit@gmail.com" },
+]
+maintainers = [
+  { name = "Robert W. Schlegel", email = "robwschlegel@gmail.com" },
+  { name = "Albertus J. Smit", email = "albertus.smit@gmail.com" },
+]
+keywords = ["marine heatwave", "cold-spell", "climatology", "NetCDF", "oceanography"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: C++",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Atmospheric Science",
+  "Topic :: Scientific/Engineering :: Hydrology",
+]
+dependencies = ["numpy>=1.23", "pandas>=1.5"]
+
+[project.optional-dependencies]
+parquet = ["pyarrow>=10"]
+plot = ["matplotlib>=3.6"]
+test = ["pytest>=7", "pyarrow>=10", "matplotlib>=3.6"]
+
+[project.urls]
+Homepage = "https://github.com/robwschlegel/heatwave3"
+Documentation = "https://heatwave3.readthedocs.io"
+Source = "https://github.com/robwschlegel/heatwave3"
+"R package" = "https://robwschlegel.github.io/heatwave3/"
+
+[tool.scikit-build]
+minimum-version = "build-system.requires"
+wheel.packages = ["python/heatwave3"]
+# The repo root is also the R package. Publish an explicit allowlist so R files
+# and stray local files (e.g. editor or agent settings) never reach PyPI.
+sdist.exclude = ["*"]
+sdist.include = [
+  "/pyproject.toml", "/CMakeLists.txt", "/LICENSE.md", "/python/README.md",
+  "/python/heatwave3/*.py", "/python/src/*.cpp", "/python/tests/*.py",
+  "/src/hw3_api.cpp", "/src/hw3_api.h", "/src/hw3_log.h", "/src/hw3_omp.h",
+  "/src/hw3_round.h", "/src/hw3_h5chunk.cpp", "/src/hw3_h5chunk.h",
+  "/src/heatwave3_types.h", "/src/netcdf_io.cpp", "/src/netcdf_io.h",
+  "/src/climatology.cpp", "/src/climatology.h", "/src/event_detect.cpp",
+  "/src/event_detect.h", "/src/blob_core.cpp", "/src/blob_core.h",
+]
+
+[tool.cibuildwheel]
+# CPython 3.10-3.14. CPython 3.15 and free-threaded builds can be added once
+# numpy and pandas publish wheels for them; musllinux (Alpine) users install
+# from the sdist for now.
+build = "cp310-* cp311-* cp312-* cp313-* cp314-*"
+skip = "cp31?t-* *-musllinux_*"
+build-verbosity = 1
+# Tests run against the installed wheel, from copies of these folders.
+test-sources = ["python/tests", "inst/extdata", "DESCRIPTION"]
+test-requires = ["pytest", "matplotlib"]
+test-command = "pytest python/tests -p no:cacheprovider"
+
+[tool.cibuildwheel.linux]
+# Pinned HDF5 + netcdf-c built from source; auditwheel bundles them.
+before-all = "dnf install -y zlib-devel && bash python/tools/build_netcdf.sh /opt/hw3-netcdf"
+environment = { CMAKE_PREFIX_PATH = "/opt/hw3-netcdf", HDF5_ROOT = "/opt/hw3-netcdf" }
+
+[tool.cibuildwheel.macos]
+# One architecture per runner (arm64 and x86_64 runners); delocate bundles
+# the libraries. MACOSX_DEPLOYMENT_TARGET is set inline for before-all.
+archs = ["native"]
+before-all = "MACOSX_DEPLOYMENT_TARGET=11.0 bash python/tools/build_netcdf.sh /tmp/hw3-netcdf"
+environment = { CMAKE_PREFIX_PATH = "/tmp/hw3-netcdf", HDF5_ROOT = "/tmp/hw3-netcdf", MACOSX_DEPLOYMENT_TARGET = "11.0" }
+
+[tool.pytest.ini_options]
+testpaths = ["python/tests"]

heatwave3-1.4.0/python/README.md

@@ -0,0 +1,35 @@
+# heatwave3
+
+Detect marine heatwaves (MHWs) and marine cold-spells (MCSs) directly in
+gridded NetCDF data, following the Hobday et al. (2016, 2018) definitions.
+
+`heatwave3` is the Python interface to the same C++ core as the
+[heatwave3 R package](https://robwschlegel.github.io/heatwave3/): climatology,
+event detection, categorisation and blob detection run in multi-threaded C++
+with direct NetCDF I/O. Function names, arguments and outputs match the R
+package, so code translates line for line.
+
+```python
+import heatwave3 as hw3
+
+# Climatology + events (+ categories, + daily series) in one call
+out = hw3.detect3("sst.nc", "results/run1", ("1982-01-01", "2011-12-31"),
+                  category=True, daily="also", n_threads=4)
+
+events = hw3.hw3_export(out["events"])                       # pandas DataFrame
+daily = hw3.hw3_export(out["daily"], time_range=("2023-01-01", "2023-12-31"))
+hw3.hw3_export(out["events"], file_out="events.parquet")     # or .csv
+```
+
+Also available: `ts2clm3()`, `detect_event3()`, `category3()`,
+`category_daily3()`, `block_average3()`, `exceedance3()`, `detect_blob3()`
+(spatially connected events), `getHW3threads()` and `setHW3threads()`, and,
+with `pip install heatwave3[plot]`, the matplotlib plots `event_line3()`,
+`plot_metric3()`, `geom_flame3()` and `geom_lolli3()`. The one
+naming difference from R: `detect_blob3()`'s `return` argument is `return_`,
+because `return` is a Python keyword.
+
+Documentation: <https://heatwave3.readthedocs.io>
+
+Its version is pinned to the R package's: heatwave3 1.4.0 in Python has the
+same functions and outputs as heatwave3 1.4.0 in R.

heatwave3-1.4.0/python/heatwave3/__init__.py

@@ -0,0 +1,38 @@
+"""Detect marine heatwaves and cold-spells directly in gridded NetCDF data.
+
+Python interface to the heatwave3 C++ core, shared with the R package of the
+same name. Function names, arguments and outputs match the R package.
+"""
+
+from importlib.metadata import version as _version
+
+from . import _core
+from .blob import detect_blob3
+from .category import block_average3, category3, category_daily3
+from .climatology import ts2clm3
+from .events import detect3, detect_event3, detect_event_array3, exceedance3
+from .export import hw3_export
+from .plot import event_line3, geom_flame3, geom_lolli3, plot_metric3
+from .threads import getHW3threads, setHW3threads
+
+__version__ = _version("heatwave3")
+
+__all__ = [
+    "__version__",
+    "block_average3",
+    "category3",
+    "category_daily3",
+    "detect3",
+    "detect_blob3",
+    "detect_event3",
+    "detect_event_array3",
+    "event_line3",
+    "exceedance3",
+    "geom_flame3",
+    "geom_lolli3",
+    "getHW3threads",
+    "hw3_export",
+    "plot_metric3",
+    "setHW3threads",
+    "ts2clm3",
+]

heatwave3-1.4.0/python/heatwave3/_frames.py

@@ -0,0 +1,163 @@
+"""Long data frames from the C++ readers (ports of the R builders in export.R).
+
+Gridded products use the pixel-major layout of the C++ core:
+pixel = (ilon * nlat + ilat) * ndepth + idepth, then the third axis
+(day-of-year or time) varies fastest within each pixel.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from ._utils import jd_to_datetime, nullable_int
+
+CAT_LABELS = np.array([None, "I Moderate", "II Strong", "III Severe", "IV Extreme"], dtype=object)
+SEASON_LABELS = np.array([None, "Summer", "Fall", "Winter", "Spring"], dtype=object)
+
+EVENT_METRICS = [
+    "duration",
+    "intensity_mean", "intensity_max", "intensity_var", "intensity_cumulative",
+    "intensity_mean_relThresh", "intensity_max_relThresh",
+    "intensity_var_relThresh", "intensity_cumulative_relThresh",
+    "intensity_mean_abs", "intensity_max_abs", "intensity_var_abs",
+    "intensity_cumulative_abs",
+    "rate_onset", "rate_decline",
+]
+
+
+def _pixel_axes(nlon, nlat, ndepth, pixels):
+    """(ilon, ilat, idepth) 0-based for 0-based pixel indices."""
+    pixels = np.asarray(pixels)
+    idepth = pixels % ndepth
+    lonlat = pixels // ndepth
+    return lonlat // nlat, lonlat % nlat, idepth
+
+
+def clim_df(cd: dict, start: int = 0, stop: int | None = None) -> pd.DataFrame:
+    """Climatology rows for pixels [start, stop): lon, lat, doy, seas, thresh, (depth)."""
+    ndepth = max(1, cd["ndepth"])
+    npix = cd["nlon"] * cd["nlat"] * ndepth
+    stop = npix if stop is None else stop
+    ndoy = cd["ndoy"]
+    has_depth = ndepth > 1 and len(cd["depth"]) > 0
+    pixels = np.arange(start, stop)
+    ilon, ilat, idepth = _pixel_axes(cd["nlon"], cd["nlat"], ndepth, pixels)
+    sl = slice(start * ndoy, stop * ndoy)
+    df = pd.DataFrame({
+        "lon": np.repeat(cd["lon"][ilon], ndoy),
+        "lat": np.repeat(cd["lat"][ilat], ndoy),
+        "doy": np.tile(np.arange(1, ndoy + 1, dtype=np.int32), len(pixels)),
+        "seas": cd["seas"][sl],
+        "thresh": cd["thresh"][sl],
+    })
+    if has_depth:
+        df["depth"] = np.repeat(cd["depth"][idepth], ndoy)
+    return df
+
+
+def daily_df(dd: dict, start: int = 0, stop: int | None = None) -> pd.DataFrame:
+    """Per-day rows (daily or protoevents) for pixels [start, stop)."""
+    ndepth = max(1, dd["ndepth"])
+    npix = dd["nlon"] * dd["nlat"] * ndepth
+    stop = npix if stop is None else stop
+    ntime = dd["ntime"]
+    has_depth = ndepth > 1 and len(dd["depth"]) > 0
+    pixels = np.arange(start, stop)
+    ilon, ilat, idepth = _pixel_axes(dd["nlon"], dd["nlat"], ndepth, pixels)
+    sl = slice(start * ntime, stop * ntime)
+    has = lambda k: len(dd[k]) > 0
+    df = pd.DataFrame({
+        "lon": np.repeat(dd["lon"][ilon], ntime),
+        "lat": np.repeat(dd["lat"][ilat], ntime),
+        "t": np.tile(jd_to_datetime(dd["time_jd"]), len(pixels)),
+    })
+    # temp / seas / thresh are absent from slim daily files (intensity + category)
+    for k in ("temp", "seas", "thresh"):
+        if has(k):
+            df[k] = dd[k][sl]
+    if has("threshCriterion"):
+        df["threshCriterion"] = dd["threshCriterion"][sl] != 0
+    if has("durationCriterion"):
+        df["durationCriterion"] = dd["durationCriterion"][sl] != 0
+    if has("intensity"):
+        df["intensity"] = dd["intensity"][sl]
+    if has("event"):
+        df["event"] = dd["event"][sl] != 0
+    if has("event_no"):
+        df["event_no"] = nullable_int(dd["event_no"][sl])
+    if has("category"):
+        df["category"] = nullable_int(dd["category"][sl])
+    if has_depth:
+        df["depth"] = np.repeat(dd["depth"][idepth], ntime)
+    return df
+
+
+def event_df(ev: dict, idx=None) -> pd.DataFrame:
+    """Event rows (all, or the 0-based indices `idx`), as .event_df_from_indices()."""
+    idx = np.arange(ev["nevents"]) if idx is None else np.asarray(idx, dtype=np.int64)
+    ref = ev["ref_date_jd"]
+    df = pd.DataFrame({
+        "lon": ev["lon"][idx],
+        "lat": ev["lat"][idx],
+        "pixel_index": ev["pixel_index"][idx],
+        "event_no": ev["event_no"][idx],
+        "date_start": jd_to_datetime(ref + ev["date_start"][idx]),
+        "date_peak": jd_to_datetime(ref + ev["date_peak"][idx]),
+        "date_end": jd_to_datetime(ref + ev["date_end"][idx]),
+    })
+    for m in EVENT_METRICS:
+        df[m] = ev[m][idx]
+    if len(ev["depth"]) > 0:
+        df["depth"] = ev["depth"][idx]
+    if len(ev["category"]) > 0 and (ev["category"] > 0).any():
+        df["category"] = CAT_LABELS[np.clip(ev["category"][idx], 0, 4)]
+        for p in ("p_moderate", "p_strong", "p_severe", "p_extreme"):
+            df[p] = ev[p][idx]
+        df["season"] = SEASON_LABELS[np.clip(ev["season"][idx], 0, 4)]
+    return df
+
+
+def subset_df(sub: dict) -> pd.DataFrame:
+    """Long frame from a hyperslab read: lon, lat, t|doy, vars..., (depth)."""
+    nlon, nlat, n3 = sub["nlon"], sub["nlat"], sub["n3"]
+    has_depth = bool(sub["has_depth"])
+    ndepth = sub["ndepth"] if has_depth else 1
+    vnames = list(sub["data"].keys())
+    third_is_t = sub["third_name"] == "t"
+    third = "t" if third_is_t else "doy"
+
+    if nlon == 0 or nlat == 0 or (has_depth and ndepth == 0) or n3 == 0:
+        cols = {"lon": np.array([], float), "lat": np.array([], float)}
+        if has_depth:
+            cols["depth"] = np.array([], float)
+        cols[third] = (np.array([], "datetime64[ns]") if third_is_t
+                       else np.array([], np.int32))
+        for v in vnames:
+            cols[v] = np.array([], float)
+        return _finalize_subset(pd.DataFrame(cols), vnames)
+
+    npix = nlon * nlat * ndepth
+    df = pd.DataFrame({
+        "lon": np.repeat(sub["lon"], nlat * ndepth * n3),
+        "lat": np.tile(np.repeat(sub["lat"], ndepth * n3), nlon),
+    })
+    if third_is_t:
+        df["t"] = np.tile(jd_to_datetime(sub["third"]), npix)
+    else:
+        df["doy"] = np.tile(sub["third"].astype(np.int32), npix)
+    for v in vnames:
+        df[v] = sub["data"][v]
+    if has_depth:
+        df["depth"] = np.tile(np.repeat(sub["depth"], n3), nlon * nlat)
+    return _finalize_subset(df, vnames)
+
+
+def _finalize_subset(df: pd.DataFrame, vnames: list[str]) -> pd.DataFrame:
+    for v in ("threshCriterion", "durationCriterion", "event"):
+        if v in vnames:
+            df[v] = df[v].to_numpy() != 0
+    for v in ("event_no", "category"):
+        if v in vnames:
+            df[v] = nullable_int(df[v].to_numpy())
+    return df

heatwave3-1.4.0/python/heatwave3/_utils.py

@@ -0,0 +1,158 @@
+"""Internal helpers: output paths, input resolution, dates and argument checks."""
+
+from __future__ import annotations
+
+import os
+import warnings
+from contextlib import contextmanager
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from . import _core
+
+# Julian Day Number of 1970-01-01.
+JD_UNIX_EPOCH = 2440588
+
+
+# Output paths: a single `name` stem maps to the four product files.
+
+def clim_path(name) -> str:
+    return f"{os.fspath(name)}_clim.nc"
+
+
+def events_path(name) -> str:
+    return f"{os.fspath(name)}_events.nc"
+
+
+def daily_path(name) -> str:
+    return f"{os.fspath(name)}_events_daily.nc"
+
+
+def proto_path(name) -> str:
+    return f"{os.fspath(name)}_protoevents.nc"
+
+
+def check_out_dir(path: str) -> None:
+    out_dir = os.path.dirname(os.path.abspath(path))
+    if not os.path.isdir(out_dir):
+        raise FileNotFoundError(f"Output directory does not exist: {os.path.dirname(path)}")
+
+
+# Inputs
+
+def is_multi(file_in) -> bool:
+    """True for a directory or a sequence of paths (as opposed to one file)."""
+    return not isinstance(file_in, (str, os.PathLike))
+
+
+def list_nc(directory, what: str = "the specified directory") -> list[str]:
+    files = sorted(str(p) for p in Path(directory).iterdir()
+                   if p.suffix in (".nc", ".nc4") and p.is_file())
+    if not files:
+        raise FileNotFoundError(f"No .nc or .nc4 files found in {what}.")
+    return files
+
+
+def resolve_input(file_in, missing_msg: str = "Input file does not exist: ",
+                  dir_what: str = "the specified directory") -> tuple[list[str], bool]:
+    """Resolve a file, directory or sequence of files to (files, multi_file)."""
+    if not is_multi(file_in):
+        path = os.fspath(file_in)
+        if os.path.isdir(path):
+            return list_nc(path, dir_what), True
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"{missing_msg}{path}")
+        return [path], False
+    files = [os.fspath(f) for f in file_in]
+    if len(files) == 1:
+        return resolve_input(files[0], missing_msg, dir_what)
+    return files, True
+
+
+# Dates
+
+def to_datetime64(dates) -> np.ndarray:
+    """Convert date-like input(s) to datetime64[D]; raise ValueError if invalid."""
+    try:
+        with warnings.catch_warnings():
+            # Invalid input raises below; don't also leak pandas' parse warnings.
+            warnings.simplefilter("ignore")
+            d = pd.to_datetime(pd.Series(np.atleast_1d(np.asarray(dates, dtype=object))))
+    except (ValueError, TypeError) as e:
+        raise ValueError(str(e)) from None
+    if d.isna().any():
+        raise ValueError("NaT")
+    return d.to_numpy().astype("datetime64[D]")
+
+
+def date_strings(dates) -> list[str]:
+    return [str(d) for d in to_datetime64(dates)]
+
+
+def to_jd(dates) -> list[int]:
+    days = to_datetime64(dates).astype(np.int64)
+    return [int(x) + JD_UNIX_EPOCH for x in days]
+
+
+def jd_to_datetime(jd) -> np.ndarray:
+    """Julian Day Numbers to datetime64[ns] (pandas' native resolution)."""
+    days = np.asarray(jd, dtype=np.int64) - JD_UNIX_EPOCH
+    return days.astype("datetime64[D]").astype("datetime64[ns]")
+
+
+# Arguments
+
+def pair(x, what: str) -> list[float] | None:
+    """Validate an optional (min, max) pair."""
+    if x is None:
+        return None
+    vals = [float(v) for v in np.atleast_1d(x)]
+    if len(vals) != 2:
+        raise ValueError(f"{what} must be a numeric vector of length 2.")
+    return vals
+
+
+def int_or_zero(x) -> int:
+    """R's `if (is.numeric(x)) as.integer(x) else 0L`: False/None mean 0."""
+    if x is None or isinstance(x, (bool, np.bool_)):
+        return 0
+    return int(x)
+
+
+def nthreads(n_threads) -> int:
+    """n_threads argument -> C++: None means the session default (0 tells the
+    core to use getHW3threads())."""
+    return 0 if n_threads is None else int(n_threads)
+
+
+def compression_level(compression) -> int:
+    """compression argument -> C++: one whole number from 0 to 9."""
+    if (isinstance(compression, bool) or not isinstance(compression, (int, float))
+            or compression != int(compression) or not 0 <= compression <= 9):
+        raise ValueError("compression must be a whole number from 0 to 9.")
+    return int(compression)
+
+
+def choose(value: str, choices: tuple[str, ...], what: str) -> str:
+    if value not in choices:
+        raise ValueError(f"'{what}' must be one of: {', '.join(choices)}.")
+    return value
+
+
+def nullable_int(values, na_values=(0,)) -> pd.arrays.IntegerArray:
+    """Integer column with the given sentinel values as missing (R NA_integer_)."""
+    v = np.asarray(values, dtype=np.int64)
+    mask = np.isin(v, na_values)
+    return pd.arrays.IntegerArray(v.astype(np.int32), mask)
+
+
+@contextmanager
+def quiet_core(quiet: bool):
+    """Silence the C++ core's messages (not warnings) on this thread while active."""
+    old = _core.hw3_set_quiet(bool(quiet))
+    try:
+        yield
+    finally:
+        _core.hw3_set_quiet(old)