geossm.data_preparation.DesignMatrices

class geossm.data_preparation.DesignMatrices(X, X_design_info, x_names, x_exprs, points, formula, crs, box, geometry, timestamps, delta, unit, y=None, y_design_info=None, y_name=None, y_expr=None, time_col_name='Time', dtype=<class 'numpy.float32'>)

Bases: object

Container for the response and covariate design matrices of a spatio-temporal dataset, organized on an [N x T] (site x time) grid, together with the spatial/temporal/formula metadata needed to interpret and reproduce them.

Instances are normally produced by DesignMatricesBuilder (via DesignMatricesBuilder.build() or DesignMatricesBuilder.build_predict()), not constructed directly; the constructor’s validation (see __post_init__) exists mainly to keep the builder’s output self-consistent.

Parameters:

• X (numpy.ndarray) – Covariate design array of shape [N, P, T] (sites x covariates x timesteps), built from the right-hand side of formula.

• X_design_info (patsy.design_info.DesignInfo) – Patsy metadata describing how X’s columns were built from formula (term names, factor info, etc.). Reused by DesignMatricesBuilder.build_predict() to evaluate prediction covariates with the same (e.g. standardize) statistics as the training data.

• x_names (list of str) – Column names of X (one per covariate), taken from X_design_info.column_names.

• x_exprs (list of str) – Transformation/expression applied to each covariate term (e.g. "1" for a plain variable, or the full expression for I(...)/function terms), as extracted from formula.

• points (list of shapely.geometry.Point or numpy.ndarray) – The N unique site locations, in the CRS given by crs. Passed in as Point geometries; converted in __post_init__ to an [N, 2] coordinate array of dtype dtype.

• formula (str) – The Patsy/R-style model formula (e.g. "AQ_pm10 ~ 1 + WE_temp_2m") that X (and y, if present) were built from.

• crs (pyproj.CRS) – Coordinate reference system of points, taken from the source GeoDataFrame.

• box (list of float) – Bounding box [minx, miny, maxx, maxy] of the source GeoDataFrame’s geometries.

• geometry (array-like of str) – Unique geometry type(s) found in the source GeoDataFrame (e.g. ["Point"]).

• timestamps (numpy.ndarray) – The T unique, sorted timestamps that make up the time axis of X (and y, if present).

• delta (int or float) – Size of the regular time step between consecutive timestamps, in the unit given by unit (see check_regular_timestamps).

• unit (str) – Unit of delta (e.g. "day", "hour", "month").

• y (numpy.ndarray, optional) – Response array of shape [N, T], built from the left-hand side of formula. None if formula has no response (covariates only). Missing observations are NaN rather than dropped, so the site x time grid stays complete.

• y_design_info (patsy.design_info.DesignInfo, optional) – Patsy metadata for y, analogous to X_design_info. None when y is None.

• y_name (str, optional) – Column name of the response, taken from y_design_info.column_names. None when y is None.

• y_expr (list of str, optional) – Transformation/expression applied to the response term, as extracted from formula.

• time_col_name (str, default "Time") – Name of the column in the source GeoDataFrame that held the timestamps.

• dtype (numpy.dtype, default numpy.float32) – Numeric precision used for X, y and points. Passing a 64-bit dtype (e.g. numpy.float64) also enables JAX’s x64 mode, since JAX otherwise silently truncates float64 arrays to 32-bit.

N

Number of sites (derived from X.shape[0]).

Type:

int

b

Number of covariates/columns in X (derived from X.shape[1]).

Type:

int

T

Number of timesteps (derived from X.shape[2]).

Type:

int

terms

Parsed representation of formula, computed in __post_init__.

Type:

patsy.desc.ModelDesc

Notes

geometry_id (a further, non-constructor field of this dataclass) holds the name used internally for the per-site identifier column ("geometry_id").

Raises:

• TypeError – If dtype is not a valid NumPy dtype.

• ValueError – If the shapes of y, X and timestamps are inconsistent (see __post_init__).

Methods

astype	Cast X, y and points to a new numeric dtype, in place.
generate_summary	Build the two side-by-side tables of key/value pairs shown by summary.
summary	Build a human-readable summary of the design matrices.

Attributes

geometry_id
isnan	Boolean mask [N x T] — True where y is NaN.
n_obs	Total number of observed (non-NaN) values in y.
nan_ratio	Fraction of missing (NaN) values over all [N x T] entries.
shape	Shape of the design matrices as a tuple (N, P, T).
time_col_name
y
y_design_info
y_expr
y_name
X
X_design_info
x_names
x_exprs
points
formula
crs
box
geometry
timestamps
delta
unit

X: ndarray

X_design_info: object

x_names: list[str]

x_exprs: list[str]

points: list[Point]

formula: str

crs: object

box: object

geometry: object

timestamps: ndarray

delta: int

unit: str

y: ndarray = None

y_design_info: object = None

y_name: str = None

y_expr: list[str] = None

time_col_name: str = 'Time'

geometry_id: str = 'geometry_id'

dtype

alias of float32

__post_init__()

Validate and normalize the fields set by the dataclass constructor.

Coerces dtype, casts X/y/points to it, validates array shapes, and derives N, b, T and terms.

astype(dtype)

Cast X, y and points to a new numeric dtype, in place.

Lets an already-built DesignMatrices be realigned with a model’s dtype (e.g. LRStateSpaceModel.dtype) without re-running formula parsing / matrix construction, which is comparatively expensive.

Parameters:

dtype (numpy.dtype or str) – Target numeric precision (e.g. numpy.float32, numpy.float64). If it is 64-bit, JAX’s x64 mode is enabled (see dtype on the class), since JAX otherwise silently truncates float64 arrays to 32-bit.

Returns:

DesignMatrices – self, with X, y, points and dtype updated. Returned unchanged (no copy/cast) if dtype already matches self.dtype.

Return type:

DesignMatrices

property isnan: ndarray

Boolean mask [N x T] — True where y is NaN.

property n_obs: int

Total number of observed (non-NaN) values in y.

property nan_ratio: float

Fraction of missing (NaN) values over all [N x T] entries.

property shape

Shape of the design matrices as a tuple (N, P, T).

generate_summary()

Build the two side-by-side tables of key/value pairs shown by summary.

Returns:

• gen_top_left (list of (str, list[str])) – Left-hand column: formula, response/covariate names and transformations, observed/missing counts, and dtype.

• gen_top_right (list of (str, list[str])) – Right-hand column: array dimensions (N, b, T), CRS, geometry type, bounding box, timestamp range, and (delta, unit).

summary()

Build a human-readable summary of the design matrices.

Assembles the key/value tables from generate_summary into a statsmodels.iolib.summary.Summary, in the same style as a statsmodels model-fit summary. Also used by __str__.

Notes

As a side effect, sets placeholder model/params/bse/ tvalues/pvalues attributes on self, required by Summary.add_table_2cols; these are not meaningful statistics (DesignMatrices holds no fitted model).

Returns:

statsmodels.iolib.summary.Summary – Two-column summary table describing the formula, response and covariates, missingness, array shapes, CRS and time range.

Return type:

Summary

__str__()

Return the text rendering of summary.

__repr__()

Return a short DesignMatrices(N=..., b=..., T=..., dtype=...) repr.

Return type:

str