Skip to contents

The response head and the metric are registrations, never a fork of the fitting code.

All of the Python reference

Installation

# Install from CRAN
install.packages("timesift")

# Or install the development version from GitHub
# install.packages("pak")
pak::pak("gcol33/timesift")
# Install from PyPI
pip install timesift

# with the torch encoders, the contrasts and the plots
pip install "timesift[torch,contrasts,plot]"

# Or install the development version from GitHub
pip install git+https://github.com/gcol33/timesift

register_response()

register_response(name: str, spec: dict, overwrite: bool = False)

Register a response head: what the values being predicted are and where a score is defined.

spec is a mapping with prepare(y), returning the response a learner is fitted on; activation, the name of the output transform ("sigmoid", "identity" or "exp"); loss, the name of the training objective ("binary_cross_entropy", "squared_error" or "poisson_deviance"); metric, the default metric name; and cells(y, folds), returning the mask of scorable cells. Presence-absence with a joint multi-label head is what ships; an abundance or phenology response is a registration rather than a second fitting path. Every learner that ships reads loss and activation from here: the encoders train under the loss and predict through the activation, and the learners fitting one model per response take the family the loss names, logistic, Gaussian or Poisson. The combiner minimises the same loss. An optional weights(y, fitting) returns a [unit, variable] array of case weights every learner fits under, with fitting a boolean vector marking the rows the model is fitted on: whatever the head reads off the response, it reads off those rows, and it weights every row, so an encoder’s inner validation loss is weighted as its fit is. The shipped head’s is timesift.response.positive_weights, and a head without one fits unweighted.

responses()

responses()

The response heads registered under this session.

as_response()

as_response(y)

The response reaches everything downstream as a Response, whether it arrived as one, as a mapping of variable name to values, or as a two-dimensional array with no names at all.

Response

Response(values, units, variables)

A [unit, variable] matrix of observed values, with the units named.

Attributes:

  • values - np.ndarray
  • units - tuple[str, …]
  • variables - tuple[str, …]

from_columns()

from_columns(cls, data, id: str, variables=None)

A response from a table of one unit column and one column per variable.

take_units()

take_units(self, index)

The response restricted to a subset of its units, in the order given.

take_variables()

take_variables(self, index)

The response restricted to a subset of its variables, in the order given.

A learner covering one response at a time is handed them through this, so the matrix a candidate emits is assembled from the same names each part was fitted on.

align()

align(self, units)

Put the response into the row order of a representation, by unit and never by position.

check_presence_absence()

check_presence_absence(self)

Error unless every value is 0 or 1 and none is missing.

PRESENCE_ABSENCE

PRESENCE_ABSENCE = dict(prepare=lambda y: as_response(y).check_presence_absence(), activation='sigmoid', loss='binary_cross_entropy', metric='roc_auc', weights=lambda y, fitting: positive_weights(y, fitting=fitting), cells=lambda y, folds: scorable_cells(y, folds))

CONTINUOUS

CONTINUOUS = _numeric_head(lambda v: None, 'r_squared')

ABUNDANCE

ABUNDANCE = _numeric_head(_check_abundance, 'r_squared')

ORDINAL

ORDINAL = _numeric_head(_check_ordinal, 'ordinal_f1')

COUNT

COUNT = _numeric_head(_check_count, 'neg_poisson_deviance', activation='exp', loss='poisson_deviance')

positive_weights()

positive_weights(y, cap: float = 50.0, fitting=None)

Case weights that balance a rare response.

The weight every learner that ships fits a presence-absence response under: each presence of a response weighs the ratio of absences to presences among the fitting units, capped, and each absence weighs one. A response with a presence in one target of a hundred is otherwise fitted away by any learner that minimises a mean loss.

The ratio is read off the units the model is fitted on and the weight applies to every unit handed in. An encoder holds part of its units back as an inner validation set and reads the loss it stops on under the same weights, so the loss that stops the fit is the loss the fit minimises; a unit held back that way is not in the count the ratio is made from. fitting is a boolean vector over the rows of y, True for the units the model is fitted on, or None for all of them.

The weights are the response head’s: the shipped presence-absence head carries this function as its weights, and a head registered with weights=lambda y, fitting: positive_weights(y, cap=20, fitting=fitting) weights every learner by that cap instead. A head without weights is fitted unweighted. Returns a [unit, variable] array of case weights, one per cell of y.

register_metric()

register_metric(name: str, fn: Callable, overwrite: bool = False)

Register a metric: a function of (y, p) on one held-out cell.

y and p are the observed values of the units in one fold and a model’s predictions for them, both the same length. It returns one number, or a value that is not finite where the cell defines none. Registering one makes it available to grain_ladder by name, with no change to the fitting code.

metrics()

metrics()

The metrics registered under this session.

resolve_metric()

resolve_metric(metric, default: str | None = None)

The function that scores and the name a report prints, from either way a metric is given.

A metric reaches a run as a registered name or as a function of (y, p), and everything that rescores afterwards – the ensemble row of a report, an occlusion profile – needs the function rather than a name to look up again. Both travel with the fit. A function has no name to print, and reads as <function> on both sides rather than as whatever the language calls an anonymous one.