Model API

lefts.interface.Model dataclass

Source code in src/lefts/interface.py

@dataclass
class Model(_Model):
    def __post_init__(self):
        _validate(self.root)

    def fit(
        self,
        df: DataFrame,
        logging: Literal["capture", "drop", "print"] = "capture",
        errors: Literal["capture", "raise"] = "raise",
    ):
        """
        Fit every leaf model in the tree.

        Parameters
        ----------
        logging
            Determines how we handle each leaf model's stdout/stderr during fit:
                - print: stdout/stderr from each model will behave as normal
                - drop: stdout/stderr from all models will be dropped.
                - capture: collects it into self.logs keyed by model label.
        errors
            Determines how we handle exceptions that raise during fit:
             - raise: an error in the fit of any leaf halts the fit call
             - capture: records the exception in self.exceptions, keyed by model label,
                and continues fitting the remaining models.
        """

        fitted, hyperparameters, logs, exceptions = _fit(
            self.root,
            df,
            logging=logging,
            errors=errors,
        )
        self.fitted = fitted
        self.hyperparameters = hyperparameters
        self.logs = logs
        self.exceptions = exceptions

        if exceptions:
            warnings.warn(
                f"{len(exceptions)} model(s) failed to train: {sorted(exceptions)}",
                UserWarning,
                stacklevel=2,
            )

    def print_tree(self, print_all_labels: bool = False):
        print(
            _print_tree(
                self.root, print_all_labels=print_all_labels, models=self.fitted
            )
        )

    def collect_labels(self) -> Iterable[str]:
        return _collect_labels(self.root)

    def mark_train_validation_test_rows(self, df: DataFrame) -> DataFrame:
        """
        Annotate `df` with boolean columns describing whether each
        row belongs to the train, test and (if applicable) validation
        sets for each sub model.
        """
        new_cols = []
        for label, masks in _collect_masks(self.root).items():
            new_cols.append(masks["train"].alias(f"{label}__train"))
            new_cols.append(masks["test"].alias(f"{label}__test"))
            if masks["validation"] is not None:
                new_cols.append(masks["validation"].alias(f"{label}__validation"))
        return df.with_columns(new_cols)

fit(df, logging='capture', errors='raise')

Fit every leaf model in the tree.

Parameters:

Name	Type	Description	Default
logging	Literal['capture', 'drop', 'print']	Determines how we handle each leaf model's stdout/stderr during fit: - print: stdout/stderr from each model will behave as normal - drop: stdout/stderr from all models will be dropped. - capture: collects it into self.logs keyed by model label.	'capture'
errors	Literal['capture', 'raise']	Determines how we handle exceptions that raise during fit: - raise: an error in the fit of any leaf halts the fit call - capture: records the exception in self.exceptions, keyed by model label, and continues fitting the remaining models.	'raise'

Source code in src/lefts/interface.py

def fit(
    self,
    df: DataFrame,
    logging: Literal["capture", "drop", "print"] = "capture",
    errors: Literal["capture", "raise"] = "raise",
):
    """
    Fit every leaf model in the tree.

    Parameters
    ----------
    logging
        Determines how we handle each leaf model's stdout/stderr during fit:
            - print: stdout/stderr from each model will behave as normal
            - drop: stdout/stderr from all models will be dropped.
            - capture: collects it into self.logs keyed by model label.
    errors
        Determines how we handle exceptions that raise during fit:
         - raise: an error in the fit of any leaf halts the fit call
         - capture: records the exception in self.exceptions, keyed by model label,
            and continues fitting the remaining models.
    """

    fitted, hyperparameters, logs, exceptions = _fit(
        self.root,
        df,
        logging=logging,
        errors=errors,
    )
    self.fitted = fitted
    self.hyperparameters = hyperparameters
    self.logs = logs
    self.exceptions = exceptions

    if exceptions:
        warnings.warn(
            f"{len(exceptions)} model(s) failed to train: {sorted(exceptions)}",
            UserWarning,
            stacklevel=2,
        )

mark_train_validation_test_rows(df)

Annotate df with boolean columns describing whether each row belongs to the train, test and (if applicable) validation sets for each sub model.

Source code in src/lefts/interface.py

def mark_train_validation_test_rows(self, df: DataFrame) -> DataFrame:
    """
    Annotate `df` with boolean columns describing whether each
    row belongs to the train, test and (if applicable) validation
    sets for each sub model.
    """
    new_cols = []
    for label, masks in _collect_masks(self.root).items():
        new_cols.append(masks["train"].alias(f"{label}__train"))
        new_cols.append(masks["test"].alias(f"{label}__test"))
        if masks["validation"] is not None:
            new_cols.append(masks["validation"].alias(f"{label}__validation"))
    return df.with_columns(new_cols)

predict(df, errors='raise')

Run predict for every fitted leaf model in the tree.

Parameters:

Name	Type	Description	Default
errors	Literal['raise', 'skip_unfit_models', 'output_nan']	Determines how leaf models that were not fitted (e.g. because fit was called with errors='capture' and they raised) are handled during predict: - raise: raises a RuntimeError if any model is missing from self.models. - skip_unfit_models: silently omits the output column for any unfit model. - output_nan: adds the output column but fills it entirely with null.	'raise'

Source code in src/lefts/interpreter/predict.py

def predict(
    self,
    df: DataFrame,
    errors: Literal["raise", "skip_unfit_models", "output_nan"] = "raise",
) -> DataFrame:
    """
    Run predict for every fitted leaf model in the tree.

    Parameters
    ----------
    errors
        Determines how leaf models that were not fitted (e.g. because fit was called
        with errors='capture' and they raised) are handled during predict:
            - raise: raises a RuntimeError if any model is missing from self.models.
            - skip_unfit_models: silently omits the output column for any unfit model.
            - output_nan: adds the output column but fills it entirely with null.
    """
    return _predict(self.root, self.fitted, df, errors=errors)