Metadata-Version: 2.4
Name: TempEst2
Version: 0.1.2
Summary: TempEst 2 estimates stream water temperature at a point, for streams of any size, using a data-driven model based on satellite remote sensing data. This is the Python implementation.
Home-page: https://www.rivertempest.org/pyte2/readme.html
Author: Daniel Philippus
Author-email: daniel@dphilippus.com
Project-URL: Bug Tracker, https://github.com/mines-ciroh/pyTE2/issues
Project-URL: Source Code, https://github.com/mines-ciroh/pyTE2
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Requires-Python: >=3.0
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: polars
Requires-Dist: polars-ols
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: xarray
Requires-Dist: rioxarray
Requires-Dist: earthaccess
Requires-Dist: pynldas2
Requires-Dist: dask
Requires-Dist: s3fs
Requires-Dist: rtseason
Requires-Dist: scipy
Requires-Dist: libschema
Requires-Dist: bmipy
Requires-Dist: scikit-learn
Requires-Dist: pykrige
Requires-Dist: pyarrow
Dynamic: license-file

# TempEst 2
TempEst 2/SCHEMA is "TEMPerature ESTimation, version 2, using Seasonal Conditions Historical Expectation with Modeled daily Anomaly". It estimates stream water temperature, for streams of any size, using a data-driven model based on satellite remote sensing data. This is the Python implementation with some additional data processing features.

Note that the geostatistical implementation is similar but *not identical* to the original (R) impementation described in Philippus et al., 2025 because PyKrige does not have the same spatial covariance functions available as fields and does not have MLE-based covariance function parameter estimation.

## Usage Guide

Full documentation is available at RiverTempest.org.

### Generating Predictions

TempEst 2 will return:

* temp.mod (modeled daily mean temperature; Celsius)
* temp.doy (modeled day-of-year mean temperature; Celsius)
* temp.anom (modeled temperature anomaly relative to day-of-year mean; Celsius)

`temp.mod` = `temp.doy` + `temp.anom`.

These three variables are the final output, and can be used to assess actual estimated temperature (`temp.mod`); typical seasonal conditions (`temp.doy`), such as to assess general long-term behavior; and departure from typical seasonal conditions (`temp.anom`), such as to assess heat waves or other extremes.

1. Install TempEst 2: `pip install TempEst2`
2. Download pre-trained model pickle from [GitHub Releases](https://github.com/mines-ciroh/pyTE2/releases) as `model.pkl`
3. Download prediction data by any suitable means, such as the [reference implementation's](github.com/mines-ciroh/tempest2) Google Earth Engine data retrieval script, as `data.csv`. Required columns: id, date, lst, humidity, lat, lon, elevation, grassland, shrubland, barren, water.
4. `predictions = tempest2.predict('model.pkl', 'data.csv')`

#### Relevant Functionality

The above-described `predict` function handles the entire prediction process. There are several key functions that may be relevant on their own and to fitting a model:

- Spatial prediction:
    - `tempest2.spatial.to_pickle` and `.from_pickle`: store and retrieve geospatial models in Pickle format.
    - `tempest2.build_model`: train a geospatial model from timeseries data.
    - `tempest2.predict_coefs` and `.predict_timeseries`: predict site coefficients and full timeseries, respectively. `predict_coefs` requires summarized inputs, while `.predict_timeseries` uses a full timeseries input.
- Single site:
    - `tempest2.full_fit`: fit TempEst 2 coefficients from a site timeseries. Unlike the reference implementation, this begins with a direct solution, then iteratively optimizes.
    - `tempest2.timeseries`: predict a timeseries for a single site using a timeseries input and specified coefficients.
    - `tempest2.Model`: LibSCHEMA model implementation
- `tempest2.full_summary`: generate prediction data from an input timeseries.

## Citation and More Information

If you use this model in your research, please cite TempEst 2 (Philippus et al., 2025).

Reference implementation in R and data retrieval tools for Google Earth Engine: https://github.com/mines-ciroh/tempest2

The model design is based on Philippus, Corona, Schneider, Rust, and Hogue, 2025, "Satellite-Based Spatial-Statistical Modeling of Daily Stream Water Temperatures at the CONUS Scale", *Journal of Hydrology*, https://doi.org/10.1016/j.jhydrol.2025.133321.  This paper also contains a detailed description of model design and performance characteristics.

The seasonality component is based on the "three-sine" stream annual temperature cycle function described in: Philippus, Corona, and Hogue, 2024, "Improved annual temperature cycle function for stream seasonal thermal regimes", *JAWRA*, https://doi.org/10.1111/1752-1688.13228.

Full training datasets, pre-trained models, and a knitted model validation notebook PDF are available in CUAHSI HydroShare: [TempEst 2 Development Data: Observed Stream Temperature, Covariates, Performance Data, and Analysis Notebooks](https://www.hydroshare.org/resource/a8b243957f7946e388d10ab206990675/).