tempest2 package¶

Submodules¶

tempest2.defaults module¶

Created on Thu Mar 13 11:34:26 2025

@author: dphilippus

This provides default values.

tempest2.fit module¶

Created on Wed Jan 7 14:44:36 2026

@author: Daniel Philippus

This provides calibration functions for optimizing SCHEMA coefficients at a site.

Unlike the original TempEst 2, this version (experimentally) optimizes rather than analytically computing coefficients. This has two hypothesized advantages.

1. Experiments with TempEst-NEXT determined that analytic SCHEMA coefficients are not necessarily optimal, so this version may achieve better local fits, particularly when data are incomplete. 2. The calibration process will allow quantification of the uncertainty in the coefficients, which may enable follow-up experiments.

Since SCHEMA prediction is very fast, optimization can also be quite efficient and thorough. I plan to implement a mixed algorithm.

1. Use ordinary least squares to identify an approximately optimal set of 3sine coefficients using averaged seasonality. 2. Conduct a small-scale grid search near the analytic coefficients. 3. Analytically solve for sensitivity terms using the full timeseries.

This algorithm assumes that the initial fit will avoid the local optimum problem.

tempest2.fit.add_random(series)¶

tempest2.fit.fit_all(sites: DataFrame, **kwargs) → DataFrame¶

Generate TempEst 2 coefficients for all sites in the input dataframe.

Parameters:

sites (pl.DataFrame) – “id”, “date”, “temperature”, “LST”, “humidity”
**kwargs – Passed to full_fit.

Returns:

“id”, “Intercept”, “Amplitude”, “SpringSummer”, “FallWinter”, “WinterDay”, “SpringDay”, “SummerDay”, “FallDay”, “LST”, “Humidity”

Return type:

pl.DataFrame

tempest2.fit.fit_check(data: DataFrame, coefs: dict) → float¶

Evaluate the fit (by squared error) of a set of three-sine coefficients. Only the five coefficients that vary in TempEst 2 need to be tested.

Parameters:

data (pl.DataFrame) – DataFrame containing “day” and “temperature” (one year’s worth) used for observations.
coefs (dict) – Coefficients “Intercept”, “Amplitude”, “SpringSummer”, “FallWinter”, and “WinterDay” to evaluate.

Returns:

Squared error over the timeseries.

Return type:

float

Notes

The return value is the sum of squared errors, so it is NOT comparable across sites and should be used only to optimize for a single site.

tempest2.fit.full_fit(data: DataFrame, to_df: bool = False, **kwargs) → dict | DataFrame¶

Generate a full, optimized SCHEMA fit.

Parameters:

data (pl.DataFrame) – DataFrame containing “date”, “temperature”, “LST”, “humidity”.
to_df (bool, optional) – Return results as a DataFrame instead of a dictionary. The default is false.
**kwargs – Passed to optimize. ‘sample’ and ‘iters’ likely relevant.

Returns:

Full coefficients: “Intercept”, “Amplitude”, “SpringSummer”, “FallWinter”, “WinterDay”, “SpringDay”, “SummerDay”, “FallDay”, “LST”, “Humidity”.

Return type:

dict or pl.DataFrame

tempest2.fit.full_training_data(sites: DataFrame, **kwargs) → DataFrame¶

Generate TempEst 2 coefficients and prediction data for all sites in the input dataframe.

Parameters:

sites (pl.DataFrame) – ‘id’, ‘date’, ‘lat’, ‘lon’, ‘elevation’, ‘lst’, ‘humidity’, ‘water’, ‘shrubland’, ‘grassland’, ‘barren’, ‘year’, ‘day’, ‘temperature’
**kwargs (passed to fit_all)

Returns:

Full prediction data and coefficients. ‘humidity_03’, ‘cdd_10’, ‘amphum’, ‘lon’, ‘lst_10’, ‘humidity_05’, ‘freeze_days’, ‘humidity_07’, ‘grassland’, ‘lst_09’, ‘shrubland’, ‘lst_05’, ‘Intercept’, ‘barren’, ‘elevation’, ‘humidity_01’, ‘maxT’, ‘humidity_11’, ‘humidity_09’, ‘lat’, ‘humidity_sd’, ‘minT’, ‘water’, ‘humidity_08’, ‘cdd_09’ ‘FallWinter’, ‘WinterDay’, ‘Amplitude’, ‘Intercept’, ‘SpringSummer’, ‘LST’, ‘Humidity’

Return type:

pl.DataFrame

tempest2.fit.optimize(data: DataFrame, coefs: dict, tol: float = 0.0001, iters: int = 100, sample: int = 100, prt: bool = False) → dict¶

Iteratively optimize all coefficients together and return optimized version

Parameters:

data (pl.DataFrame) – DataFrame containing “day” and “temperature” (one year’s worth) used for observations.
coefs (dict) – Coefficients “Intercept”, “Amplitude”, “SpringSummer”, “FallWinter”, and “WinterDay” to evaluate.
iters (int, optional) – Maximum number of iterations. The default is 100.
tol (float, optional) – Minimum proportional improvement in squared error before iteration halts. The default is 0.0001.
sample (int, optional) – Sample size per iteration. The default is 100.
prt (bool, optional) – Print progress info. The default is False.

Returns:

Optimized coefficients.

Return type:

dict

Notes

Each coefficient either increases or decreases by up to 20%. Also offset by up to 0.5 to allow for negative values, etc.

tempest2.gents module¶

Created on Wed Jan 14 08:52:57 2026

@author: daniel

This file deals with generating timeseries from specified coefficients and input timeseries. Includes standalone Polars and LibSCHEMA implementations.

class tempest2.gents.Model(ssn: ThreeSine | dict | ndarray, LST, Humidity, periodics)¶

Bases: SCHEMA

run_series(data)¶: Run a full timeseries at once if modification engines are not present. Otherwise, reverts to run_series_incremental. Period_col specifies a period column if one exists. Returns the predicted array (if context=False) or the data with an added prediction column (if context=True).

class tempest2.gents.ScAnomaly(LST, Humidity)¶

Bases: Anomaly

apply(periodic, period, anom_history)¶

apply_vec(periodic, period, anom_history)¶

class tempest2.gents.ScSeasonality(ssn: ThreeSine | dict | ndarray)¶

Bases: Seasonality

apply(period)¶

apply_vec(period)¶

class tempest2.gents.TeBmi¶

Bases: SchemaBmi

initialize(filename)¶: Initialize the model. Filename points to input file.

tempest2.gents.all_timeseries(data: DataFrame) → DataFrame¶

Generate all timeseries for multiple site IDs with coefficients included.

Parameters:: data (pl.DataFrame) – “id”, “date”, “lst”, “humidity”, ‘FallWinter’, ‘WinterDay’, ‘Amplitude’, ‘Intercept’, ‘SpringSummer’, ‘LST’, ‘Humidity’
Returns:: With added columns temp.doy, temp.anom, and temp.mod.
Return type:: pl.DataFrame

Notes

Current implementation is not properly polarized, i.e., not taking full advantage of polars. However, as prediction is fast, this should not be a significant problem.

tempest2.gents.anoms(inp: DataFrame, coefs: DataFrame | dict) → array¶

Generate anomaly (temp.anom) timeseries for the given inputs.

Parameters:

inp (pl.DataFrame) – Timeseries inputs: “date”, “lst”, “humidity”. Must be sorted by date. May include “id”.
coefs (pl.DataFrame | dict) – TempEst 2 anomaly coefficients ‘LST’, ‘Humidity’

Returns:

Array of temp.mod predictions.

Return type:

np.array

tempest2.gents.timeseries(inp: DataFrame, coefs: DataFrame | dict) → DataFrame¶

Standalone timeseries generation from input dataframe.

Parameters:

inp (pl.DataFrame) – Timeseries inputs: “date”, “lst”, “humidity”
coefs (pl.DataFrame | dict) – All TempEst 2 coefficients ‘FallWinter’, ‘WinterDay’, ‘Amplitude’, ‘Intercept’, ‘SpringSummer’, ‘LST’, ‘Humidity’

Returns:

Timeseries of predicted temperatures. Adds temp.doy, temp.anom, and temp.mod columns.

Return type:

pl.DataFrame

tempest2.spatial module¶

Created on Wed Jan 14 11:19:19 2026

@author: daniel

This file covers the implementation of spatial/ungaged fitting and prediction through PyKrige.

class tempest2.spatial.HiddenPrints¶

Bases: object

PyKrige prints a lot, which is a problem in programmatic use. Courtesy of StackExchange user Alexander C, https://stackoverflow.com/a/45669280

tempest2.spatial.build_krig(fit_data: DataFrame | DataFrame) → dict¶

Fit a set of kriging models for all TempEst 2 coefficients.

Parameters:: fit_data (pd.DataFrame) – DataFrame with all predictors and fitted coefficients. ‘humidity_03’, ‘cdd_10’, ‘amphum’, ‘lon’, ‘lst_10’, ‘humidity_05’, ‘AutumnWinter’, ‘freeze_days’, ‘humidity_07’, ‘grassland’, ‘lst_09’, ‘shrubland’, ‘lst_05’, ‘Intercept’, ‘barren’, ‘elevation’, ‘humidity_01’, ‘maxT’, ‘humidity_11’, ‘humidity_09’, ‘lat’, ‘humidity_sd’, ‘minT’, ‘water’, ‘humidity_08’, ‘cdd_09’ ‘FallWinter’, ‘WinterDay’, ‘Amplitude’, ‘Intercept’, ‘SpringSummer’, ‘LST’, ‘Humidity’
Returns:: dict of {str – Named RegressionKriging fits.
Return type:: RegressionKriging}

tempest2.spatial.build_model(data: DataFrame | DataFrame) → dict¶

Build a model from TempEst 2 timeseries input data.

Parameters:: data (pd.DataFrame | pl.DataFrame) – ‘id’, ‘date’, ‘lat’, ‘lon’, ‘elevation’, ‘lst’, ‘humidity’, ‘water’, ‘shrubland’, ‘grassland’, ‘barren’, ‘year’, ‘day’, ‘temperature’
Returns:: dict of {str – Named RegressionKriging fits.
Return type:: RegressionKriging}

tempest2.spatial.from_pickle(file: str) → dict¶

tempest2.spatial.predict_coefs(krigs: dict, pdata: DataFrame | DataFrame) → DataFrame¶

Predict all coefficients using trained krigs.

Parameters:

krigs (dict of {str: RegressionKriging}) – Named RegressionKriging fits.
pdata (pd.DataFrame | pl.DataFrame) – All required prediction data (see XVars).

Returns:

‘FallWinter’, ‘WinterDay’, ‘Amplitude’, ‘Intercept’, ‘SpringSummer’, ‘LST’, ‘Humidity’, ‘SpringDay’, ‘SummerDay’, ‘FallDay’

Return type:

pl.DataFrame

tempest2.spatial.predict_timeseries(krigs: dict, data: DataFrame | DataFrame, keep_coefs: bool = False) → DataFrame¶

Parameters:

krigs (dict of {str: RegressionKriging}) – Named RegressionKriging fits.
data (pd.DataFrame | pl.DataFrame) – ‘id’, ‘date’, ‘lat’, ‘lon’, ‘elevation’, ‘lst’, ‘humidity’, ‘water’, ‘shrubland’, ‘grassland’, ‘barren’, ‘year’, ‘day’, ‘temperature’
keep_coefs (keep SCHEMA coefficients in result)

Returns:

Full predicted timeseries. Added columns temp.doy, temp.anom, and temp.mod.

Return type:

pl.DataFrame

tempest2.spatial.test_data()¶

tempest2.spatial.test_run()¶

tempest2.spatial.to_pickle(krigs: dict, file: str)¶

tempest2.spatial.train_krig(**kwargs)¶

Wrapper to train and return a RegressionKriging object.

Parameters:: **kwargs (Any) – Arguments passed to RegressionKriging.fit
Return type:: RegressionKriging

tempest2.spatial.tune_varg()¶

tempest2.summaries module¶

Created on Tue Jan 13 15:22:20 2026

@author: daniel

This file contains a function for summarizing the required prediction data.

tempest2.summaries.full_summary(data)¶: Helper function that pulls all predictors from timeseries data.

tempest2.summaries.summaries(dyndata: DataFrame)¶

Computes required summary statistics for coefficient estimation from dynamic data.

Parameters:: dyndata (DataFrame) – DataFrame with id, date, LST (Kelvin or Celsius), and humidity (kg/kg).
Returns:: humidity_sd (std dev of smoothed anomaly, not of overall timeseries) amphum (coefficient of DOY mean humidity in terms of 210-centered cosine) humidity_01 (mean January humidity) humidity_03 humidity_05 humidity_07 humidity_08 humidity_09 humidity_11 minT (min daily mean LST) maxT freeze_days (total days of year with mean LST < 0) lst_05 lst_09 lst_10 cdd_09 (cumulative degree days from January 1) cdd_10
Return type:: Dataset with required summary layers

Notes

Before doing anything, Kelvin is converted to Celsius.

tempest2.summaries.test_data()¶

tempest2.tests module¶

Created on Thu Jan 15 08:43:59 2026

@author: daniel

This file contains some general tests.

tempest2.tests.kf_test(data, output)¶

tempest2.tests.modbuilder(full_data)¶

tempest2.tests.test_data()¶

tempest2.ufuncs module¶

Created on Fri Mar 28 14:52:50 2025

@author: dphilippus

This file implements all required functions as Numpy ufuncs. All summary functions are applied to DOY means. Straightforward means, etc, are not provided.

Summary functions:: amphum (coefficient of DOY mean humidity in terms of 210-centered cosine)
Prediction functions:: anomaly application anomaly smoothers coefficient predictors

tempest2.ufuncs.amphum(humidity: array, doy: array)¶

Compute amplitude of humidity as a linear function of the cos-ts.

Parameters:

humidity (array) – Humidity timeseries.
doy (array) – Corresponding Julian days of year.

Returns:

Amplitude of the humidity function as a sinusoid of day-of-year, determined using ordinary least squares.

Return type:

number

tempest2.ufuncs.costs(doy: array) → array¶

Generates a generic cosine timeseries based on a center of 210 and period of 365.

Parameters:: doy (array) – Julian day of year array.
Returns:: Periodic timeseries corresponding to input array.
Return type:: array

tempest2.ufuncs.humidity_smooth(humidity: array) → array¶

Apply simple 1/0.1 smoother to humidity anomaly - i.e., today*1 + yesterday*0.1.

Parameters:: humidity (array) – Humidity _anomaly_ timeseries - not the actual humidity timeseries.
Returns:: Smoothed humidity anomaly timeseries.
Return type:: array

tempest2.ufuncs.lst_smooth(lst: array) → array¶

Apply sigmoidal smoother to LST anomaly.

Parameters:: lst (array) – LST _anomaly_ timeseries - not the actual LST timeseries.
Returns:: Smoothed LST anomaly timeseries.
Return type:: array

Notes

There are two steps to the smoother. First, LST anomalies are transformed sigmoidally: 1/(1+exp(-LST*0.3)) - 0.5 Then, the sigmoided anomalies are smoothed over today and the preceding six days using the weights: 1 (today), then 1/(2N) for day N before today.

tempest2.util module¶

Created on Thu Jan 15 11:11:42 2026

@author: daniel

Utility functions.

tempest2.util.predict(modfile: str, data: str | DataFrame | DataFrame) → DataFrame¶

Full prediction run from raw data.

Parameters:

modfile (str) – Path of model pickle.
data (str | pl.DataFrame | pandas.DataFrame) – Input data (or path) with id, date, lst, humidity, lat, lon, elevation, grassland, shrubland, barren, water

Returns:

Predicted stream temperature timeseries with added columns temp.doy (seasonal temp), temp.anom (daily anomaly), and temp.mod (daily mean temp).

Return type:

pl.DataFrame

Module contents¶

Created on Tue Mar 4 13:38:16 2025

@author: dphilippus

tempest2 package¶

Submodules¶

tempest2.defaults module¶

tempest2.fit module¶

tempest2.gents module¶

tempest2.spatial module¶

tempest2.summaries module¶

tempest2.tests module¶

tempest2.ufuncs module¶

tempest2.util module¶

Module contents¶

Table of Contents

Table of Contents