geossm.data_preparation.DesignMatricesBuilder¶

class geossm.data_preparation.DesignMatricesBuilder(geodf, formula, dtype=<class 'numpy.float32'>, verbose=True, tmin=None, tmax=None, domain=None)[source]¶

Bases: object

Turn a spatio-temporal geopandas.GeoDataFrame plus a Patsy/R-style model formula into a DesignMatrices object (response + covariates organized on an [N x T] site x time grid), ready to be consumed by geossm’s state-space models.

The constructor parses and validates formula against geodf (spatial CRS/geometry checks, time column detection, regular-spacing check, optional time-window/domain filtering) but does not itself build the arrays; call build (or __call__) to actually construct the DesignMatrices. Once built, the same builder can be reused via build_predict to construct design matrices for new (prediction) locations/times using the training formula’s fitted state (e.g. standardize(…) statistics).

Examples

>>> builder = DesignMatricesBuilder(geodf, "AQ_pm10 ~ 1 + WE_temp_2m")
>>> dm = builder.build()
>>> dm_new = builder.build_predict(new_geodf)

Methods

`build`	Build the design matrices from the GeoDataFrame passed to __init__, using the already-parsed formula.
`build_predict`	Build the design matrix for new (prediction) locations/times, reusing this builder's fitted X_design_info so stateful transforms (e.g. standardize(...)) are evaluated with the training mean/std instead of being recomputed on df.
`print_info`	Print a UTC-timestamped log line.

build(verbose=None)[source]¶

Build the design matrices from the GeoDataFrame passed to __init__, using the already-parsed formula.

After building, the underlying GeoDataFrame is discarded (only the resulting DesignMatrices and the fitted X_design_info are kept), so a builder kept around for build_predict does not hold a copy of the training data.

Parameters:: verbose (bool, optional) – Temporarily override self.verbose for this call only. If None (default), self.verbose (set in __init__) is used.
Returns:: DesignMatrices – The response (if any) and covariate design matrices, plus spatial/temporal metadata, built from the training data.
Return type:: DesignMatrices

build_predict(df, verbose=None, domain=None)[source]¶

Build the design matrix for new (prediction) locations/times, reusing this builder’s fitted X_design_info so stateful transforms (e.g. standardize(…)) are evaluated with the training mean/std instead of being recomputed on df. build() must be called first.

df is validated the same way as the training GeoDataFrame (spatial checks, time column detection, regular-spacing check, formula-column existence – but no response column is required), and is additionally checked for consistency with the training data’s CRS and time step, and clipped to the training data’s observed time range.

Parameters:

df (geopandas.GeoDataFrame) – New (prediction) spatio-temporal dataset, in the same format, CRS and time step as the GeoDataFrame build was trained on. It only needs to supply the covariate columns referenced by formula, not the response.
verbose (bool, optional) – Temporarily override self.verbose for this call only. If None (default), self.verbose (set in __init__) is used.
domain (shapely Polygon/MultiPolygon, optional) – The scientific interest domain, in the same CRS as df. When given, every prediction point is checked against it and the result is stored as the boolean array self.mask (True where the point falls inside domain), aligned with points/the N axis of the returned DesignMatrices. Points outside domain are not dropped, only flagged – filtering is left to the caller. self.mask is left None when domain is not given.

Returns:

DesignMatrices – Covariate-only design matrices (y is None) for df, built with the training X_design_info.

Raises:

ValueError – If build() has not been called yet, if df fails the same validation as the training data, or if df’s CRS or time step does not match the training data’s.

Return type:

DesignMatrices

__call__(verbose=None)[source]¶

Return the built DesignMatrices, building them first if needed.

Convenience wrapper around build: calls it only if this builder has not been built yet, otherwise returns the cached result.

Parameters:: verbose (bool, optional) – Forwarded to build if a build is triggered; ignored if the cached DesignMatrices is returned instead.
Returns:: DesignMatrices – The (possibly cached) result of build.

static print_info(msg)[source]¶

Print a UTC-timestamped log line.

Parameters:: msg (str) – Message to print, prefixed with the current UTC timestamp (YYYY-MM-DD HH:MM:SS).