Skip to content

Timefence

Labels

gauthierpiarrette/timefence

Labels¶

Defines the prediction target: which entities, at what times, and what outcome.

`Labels(*, path=None, df=None, keys, label_time, target)` ¶

Prediction targets with entity keys and event times.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path \| None`	Path to the labels file.	`None`
`df`	`Any`	DataFrame with labels (mutually exclusive with path).	`None`
`keys`	`str \| list[str]`	Column name(s) used as entity keys.	required
`label_time`	`str`	Column name containing the label event time.	required
`target`	`str \| list[str]`	Column name(s) for the prediction target.	required

Source code in src/timefence/core.py

def __init__(
    self,
    *,
    path: str | Path | None = None,
    df: Any = None,
    keys: str | list[str],
    label_time: str,
    target: str | list[str],
):
    if path is None and df is None:
        raise TimefenceValidationError(
            "Labels requires either 'path' or 'df' parameter."
        )
    if path is not None and df is not None:
        raise TimefenceValidationError(
            "Labels accepts either 'path' or 'df', not both."
        )

    self.path = Path(path) if path is not None else None
    self.df = df
    self.keys = _as_list(keys)
    if not self.keys:
        raise TimefenceValidationError(
            "Labels 'keys' cannot be empty. Provide at least one entity key column."
        )
    self.label_time = label_time
    self.target = _as_list(target)
    if not self.target:
        raise TimefenceValidationError(
            "Labels 'target' cannot be empty. Provide at least one target column."
        )

Parameters¶

Parameter	Type	Description
`path`	`str \\| Path \\| None`	Path to labels file (Parquet). Mutually exclusive with `df`.
`df`	`Any \\| None`	DataFrame, DuckDB relation, or any object with a compatible interface. Mutually exclusive with `path`.
`keys`	`str \\| list[str]`	Entity key column(s). Must match the keys used in features.
`label_time`	`str`	Column name for the label event timestamp.
`target`	`str \\| list[str]`	Prediction target column(s) (e.g., `"churned"`).

Example¶

labels = timefence.Labels(
    path="data/labels.parquet",
    keys=["user_id"],
    label_time="label_time",
    target="churned",
)