custom_model

Back to custom extensions

Use custom models when the estimator is not built into macroforecast. A custom model returns a ModelSpec, so it can be passed to the runner exactly like a built-in model name.

custom_model

mf.models.custom_model(
    name,
    fit_func,
    *,
    default_params=None,
    default_preset=None,
    search_spaces=None,
    family="custom",
    requires_extra=None,
    metadata=None,
) -> mf.models.ModelSpec

Fit Callable Contract

fit_func(X: pandas.DataFrame, y: pandas.Series, **params) -> fitted_object
fitted_object.predict(X_test: pandas.DataFrame) -> predictions

Prediction output must have length len(X_test). If it is a pandas object, it must use X_test.index or RangeIndex(len(X_test)).

Example

class MeanFit:
    def __init__(self, value):
        self.value = float(value)

    def predict(self, X):
        return numpy.full(len(X), self.value)

def mean_model(X, y, *, offset=0.0):
    return MeanFit(pandas.Series(y).mean() + offset)

model = mf.models.custom_model(
    "mean_model",
    mean_model,
    default_params={"offset": 0.0},
    default_preset="small",
    search_spaces={"small": {"offset": (-0.1, 0.0, 0.1)}},
)

Runner Use

result = mf.forecasting.run(
    panel,
    {"mean": model, "ridge": "ridge"},
    window=window,
    features=features,
)

custom_model_ensemble

Use mf.model_ensemble.custom_model_ensemble(...) when the extension is a fit-time composition of member models, not a post-forecast combination.

spec = mf.model_ensemble.custom_model_ensemble(
    "my_stacker",
    fit_func=my_ensemble_fit,
    default_params={"base_models": ("ridge", "lasso")},
)

Custom type	Stage	Output
custom_model	one estimator fit	ModelSpec
custom_model_ensemble	fit-time member-model composition	ModelSpec with family="model_ensemble"
custom_combination	post-forecast combination	CombinationSpec

Metadata

The model spec stores the model name, callable name, default parameters, search-space metadata, optional dependency labels, and user metadata. It does not store the source code of fit_func.