Commands API

Auto-generated reference from source docstrings.

lefts.leaf(model_constructor, label)

Converts a model into the format required for transformation by lefts.

Parameters:

Name	Type	Description	Default
model_constructor	Callable[..., Any]	A constructor that creates a model with .fit() and .predict() methods.	required
label	str	A label for keeping track of this model.	required

Source code in src/lefts/interface.py

def leaf(model_constructor: Callable[..., Any], label: str) -> Model:
    """
    Converts a model into the format required for transformation by lefts.

    Parameters
    ----------
    model_constructor
        A constructor that creates a model with ``.fit()`` and ``.predict()`` methods.
    label
        A label for keeping track of this model.
    """

    leaf_node = Leaf(label=label, factory=model_constructor)
    return Model(leaf_node)

lefts.lift(model, values, name, train_filter, test_filter, validation_filter=None, aggregate_with=None)

Creates multiple copies of a model that are trained on (possibly overlapping) train, test and validation sets.

Parameters:

Name	Type	Description	Default
model	Model	A lefts Model object.	required
values		Values to lift the model over. One copy of the model will be trained for each value.	required
name		The name of the lift transformation. Has no effect on model training, but controls how the resulting models are labelled and addressed: each leaf beneath the lift gets a label of the form "<leaf label>[<name>=<value>]". When aggregate_with is set, the per-value columns are instead collapsed into a single output column named name.	required
train_filter		A function mapping each value in values to a boolean Polars expression indicating whether a given row is in the train set associated with that value.	required
test_filter		A function mapping each value in values to a boolean Polars expression indicating whether a given row is in the test set associated with that value.	required
validation_filter		A function mapping each value in values to a boolean Polars expression indicating whether a given row is in the validation set associated with that value.	None
aggregate_with		A function that postprocesses the output columns of the lift. It is called on the set of columns output by the lifted .predict().	None

Source code in src/lefts/interface.py

def lift(
    model: Model,
    values,
    name,
    train_filter,
    test_filter,
    validation_filter=None,
    aggregate_with=None,
) -> Model:
    """
    Creates multiple copies of a model that are trained on (possibly overlapping) train, test and validation sets.

    Parameters
    ----------
    model
        A lefts Model object.
    values
        Values to lift the model over. One copy of the model will be trained for each value.
    name
        The name of the lift transformation. Has no effect on model training, but controls how the resulting
        models are labelled and addressed: each leaf beneath the lift gets a label of the form
        ``"<leaf label>[<name>=<value>]"``. When ``aggregate_with`` is set, the per-value columns are instead
        collapsed into a single output column named ``name``.
    train_filter
        A function mapping each value in ``values`` to a boolean Polars expression indicating whether a given
        row is in the train set associated with that value.
    test_filter
        A function mapping each value in ``values`` to a boolean Polars expression indicating whether a given
        row is in the test set associated with that value.
    validation_filter
        A function mapping each value in ``values`` to a boolean Polars expression indicating whether a given
        row is in the validation set associated with that value.
    aggregate_with
        A function that postprocesses the output columns of the lift. It is called on the set of columns
        output by the lifted ``.predict()``.
    """
    lifted = Lift(
        child=model.root,
        values=values,
        name=name,
        train_filter=train_filter,
        test_filter=test_filter,
        validation_filter=validation_filter,
        aggregate_with=aggregate_with,
    )

    return Model(lifted)

lefts.split(name, model, train_filter, test_filter, validation_filter=None)

Restricts a model to train, test and (optionally) validate on defined subsets of the available data.

Parameters:

Name	Type	Description	Default
name	str	A name used to keep track of this lefts operation in the workflow. Has no effect on model training.	required
model	Model	A lefts Model object.	required
train_filter	Expr	A boolean Polars expression that indicates whether a given row is in the train set.	required
test_filter	Expr	A boolean Polars expression that indicates whether a given row is in the test set.	required
validation_filter	Expr | None	A boolean Polars expression that indicates whether a given row is in the validation set.	None

Source code in src/lefts/interface.py

def split(
    name: str,
    model: Model,
    train_filter: Expr,
    test_filter: Expr,
    validation_filter: Expr | None = None,
) -> Model:
    """
    Restricts a model to train, test and (optionally) validate on defined subsets of the available data.

    Parameters
    ----------
    name
        A name used to keep track of this lefts operation in the workflow. Has no effect on model training.
    model
        A lefts Model object.
    train_filter
        A boolean Polars expression that indicates whether a given row is in the train set.
    test_filter
        A boolean Polars expression that indicates whether a given row is in the test set.
    validation_filter
        A boolean Polars expression that indicates whether a given row is in the validation set.
    """
    node = Split(
        name=name,
        child=model.root,
        train_filter=train_filter,
        test_filter=test_filter,
        validation_filter=validation_filter,
    )

    return Model(node)

lefts.ensemble(name, *models, aggregate_with=None)

Binds multiple models into a unified model that fits and predicts all of them in parallel.

Parameters:

Name	Type	Description	Default
name	str	A name used to keep track of this lefts operation in the workflow. Has no effect on model training.	required
models		lefts Model objects.	()
aggregate_with		A function that postprocesses the output columns of the ensemble .predict() method.	None

Source code in src/lefts/interface.py

def ensemble(name: str, *models, aggregate_with=None):
    """
    Binds multiple models into a unified model that fits and predicts all of them in parallel.

    Parameters
    ----------
    name
        A name used to keep track of this lefts operation in the workflow. Has no effect on model training.
    models
        lefts Model objects.
    aggregate_with
        A function that postprocesses the output columns of the ensemble ``.predict()`` method.
    """
    roots = [model.root for model in models]
    node = Ensemble(name, roots, aggregate_with=aggregate_with)

    return Model(node)

lefts.tune(name, consumer, source, logic)

Learn hyperparameters by fitting the source model, applying customisable logic, then passing the resulting dictionary of hyperparameters to the consumer.

Parameters:

Name	Type	Description	Default
name	str	A name used to keep track of this lefts operation in the workflow. Has no effect on model training.	required
consumer	Model	A lefts Model object. Its leaf factories are instantiated using the outputs of logic as keyword arguments.	required
source	Model	A lefts Model object. It is fitted first; the fitted model is then handed to logic to derive the hyperparameters.	required
logic	Callable[[Model, DataFrame], dict]	A callable (fitted_source_model, df) -> dict that reads the fitted source and returns the hyperparameters to apply when fitting the consumer.	required

Source code in src/lefts/interface.py

def tune(
    name: str, consumer: Model, source: Model, logic: Callable[[Model, DataFrame], dict]
):
    """
    Learn hyperparameters by fitting the source model, applying customisable logic, then passing the resulting
    dictionary of hyperparameters to the consumer.

    Parameters
    ----------
    name
        A name used to keep track of this lefts operation in the workflow. Has no effect on model training.
    consumer
        A lefts Model object. Its leaf factories are instantiated using the outputs of ``logic`` as keyword
        arguments.
    source
        A lefts Model object. It is fitted first; the fitted model is then handed to ``logic`` to derive the
        hyperparameters.
    logic
        A callable ``(fitted_source_model, df) -> dict`` that reads the fitted source and returns the
        hyperparameters to apply when fitting the consumer.
    """
    node = Tune(name=name, consumer=consumer.root, source=source.root, logic=logic)

    return Model(node)

lefts.feed(name, source, consumer)

Chains two models: the source's predictions are available to the consumer as a feature or target during .fit and .predict.

Parameters:

Name	Type	Description	Default
name	str		required
source	Model		required
consumer	Model		required

Source code in src/lefts/interface.py

def feed(name: str, source: Model, consumer: Model) -> Model:
    """
    Chains two models: the source's predictions are available to the consumer as a feature or target during .fit and .predict.
    Parameters
    ----------
    name: A name used to keep track of this lefts operation in the workflow. Has no effect on model training.
    source: A lefts Model object, which provides the output of its predict to the consumer.
    consumer: A lefts Model object, which has access to the prediction output of the consumer.

    Returns
    -------

    """
    node = Feed(name=name, source=source.root, consumer=consumer.root)

    return Model(node)