Skops model cards with a custom template

By default, when using skops.card.Card, the skops model card template is being used, which adds a couple of useful sections and a general document structure to the model card. In some cases, it might, however, be desired to use a different template because the skops template doesn’t fit our needs. This document shows how to use a custom template.

Imports

from tempfile import mkstemp

from sklearn.datasets import fetch_california_housing
from sklearn.ensemble import RandomForestRegressor
from sklearn.inspection import PartialDependenceDisplay
from sklearn.metrics import mean_absolute_error, mean_squared_error, r2_score
from sklearn.model_selection import train_test_split

from skops import card
from skops import io as sio

Loading California Housing dataset

X, y = fetch_california_housing(return_X_y=True, as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=0)

Training the RandomForestRegressor

est = RandomForestRegressor(n_estimators=10, random_state=0)
est.fit(X_train, y_train)

RandomForestRegressor(n_estimators=10, random_state=0)

In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook.
On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.

Save the model

_, model_file_name = mkstemp(prefix="skops-", suffix=".skops")
sio.dump(est, model_file_name)

Create the model card

Initialize the empty card and add a few sections

Instead of using the default skops template, let’s define our own custom template to use in this example. A template is a simple dictionary whose keys are the section names and whose values are the contents of the sections. Both keys and values should be strings, and values may be empty strings if you want to only add a section without any content (yet). As always, subsections are delimited using a "/".

Once such a template is defined, it can be passed to the skops.card.Card class using the template argument. You may also pass template=None to start with a completely empty model card.

link = (
    "https://scikit-learn.org/stable"
    "/auto_examples/release_highlights/plot_release_highlights_0_24_0.html"
    "#individual-conditional-expectation-plots"
)
dataset_name = "California Housing"
custom_template = {
    "Regression on California Housing dataset": (
        f"This example is adopted from [here]({link})."
    ),
    f"Regression on {dataset_name} dataset/Model Description": (
        f"Use the `{est.__class__.__name__}` from sklearn."
    ),
    f"Regression on {dataset_name} dataset/Usage": "This is only for demo purposes.",
    f"Regression on {dataset_name} dataset/Results": "",
}
model_card = card.Card(est, template=custom_template)

Adding more content to the model card

From here on out, feel free to edit the model card as you would always do by calling the different methods starting with add, such as skops.card.Card.add(). and skops.card.Card.add_metrics(). Below, we add more content to the model card to demonstrate this.

Add metrics

y_pred = est.predict(X_test)
metrics_dict = {
    "R-squared": r2_score(y_test, y_pred),
    "Mean absolute error": mean_absolute_error(y_test, y_pred),
    "Mean squared error": mean_squared_error(y_test, y_pred),
}
model_card.add_metrics(
    section="Regression on California Housing dataset/Results/Metrics",
    description=(
        "Metrics are determined on a random split consisting of 25% of the data"
    ),
    **metrics_dict,
)

Card(
  model=RandomForestRegressor(n_estimators=10, random_state=0),
  Regression on California Housing dataset=This example is a...pectation-plots).,
  Regression on California Housing dataset/Model Description=Use the ...sklearn.,
  Regression on California Housing dataset/Usage=This is only for demo purposes.,
  Regression on California Housing dataset/Results/Metrics=TableSection(3x2),
)

Add hyperparameter table

model_card.add_hyperparams(
    section=(
        "Regression on California Housing dataset/Model Description/Hyperparameters"
    ),
    description="The model was trained with the hyperparameters listed below",
)

Card(
  model=RandomForestRegressor(n_estimators=10, random_state=0),
  Regression on California Housing dataset=This example is a...pectation-plots).,
  Regression on California Housing dataset/Model Description=Use the ...sklearn.,
  Regression on California Housing dataset/Model Description/Hyperparameters=...,
  Regression on California Housing dataset/Usage=This is only for demo purposes.,
  Regression on California Housing dataset/Results/Metrics=TableSection(3x2),
)

Add the model diagram

model_card.add_model_plot(
    section="Regression on California Housing dataset/Model Description/Model Diagram",
)

Card(
  model=RandomForestRegressor(n_estimators=10, random_state=0),
  Regression on California Housing dataset=This example is a...pectation-plots).,
  Regression on California Housing dataset/Model Description=Use the ...sklearn.,
  Regression on California Housing dataset/Model Description/Hyperparameters=...,
  Regression on California Housing dataset/Model Description/Model Diagram=<...>,
  Regression on California Housing dataset/Usage=This is only for demo purposes.,
  Regression on California Housing dataset/Results/Metrics=TableSection(3x2),
)

Add partial dependence plot

features = ["MedInc", "HouseAge", "AveRooms", "AveBedrms", "Population", "AveOccup"]
n_samples = 500  # make plot a bit faster
display = PartialDependenceDisplay.from_estimator(
    est,
    X[:n_samples],
    features,
    kind="individual",
    subsample=50,
    grid_resolution=20,
    random_state=0,
)
display.figure_.suptitle(
    "Partial dependence of house value on non-location features\n"
    "for the California housing dataset, with BayesianRidge"
)
display.figure_.subplots_adjust(hspace=0.3)
_, plot_file_name = mkstemp(prefix="skops-", suffix=".png")
display.figure_.savefig(plot_file_name)
model_card.add_plot(
    **{
        "Regression on California Housing dataset/Results/Partial Dependence Plots": (
            plot_file_name
        )
    },
)

Partial dependence of house value on non-location features for the California housing dataset, with BayesianRidge

Card(
  model=RandomForestRegressor(n_estimators=10, random_state=0),
  Regression on California Housing dataset=This example is a...pectation-plots).,
  Regression on California Housing dataset/Model Description=Use the ...sklearn.,
  Regression on California Housing dataset/Model Description/Hyperparameters=...,
  Regression on California Housing dataset/Model Description/Model Diagram=<...>,
  Regression on California Housing dataset/Usage=This is only for demo purposes.,
  Regression on California Housing dataset/Results/Metrics=TableSection(3x2),
  Regression on California Housing dataset/Results/Partial Dependence Plots=...),
)

Save the finished model card

_, card_file_name = mkstemp(prefix="skops-", suffix=".md")
model_card.save(card_file_name)

Further information

The model card created in this example is very bare bones, missing a lot of important information. It should only be used as a starting point and not be considered a complete example. If you would like to know more about model cards, the model card documentation on the Hugging Face Hub could be a good starting point.

Furthermore, this model card lacks metadata, which can be very useful if you plan to upload the model on Hugging Face Hub. If you want to add metadata, instantiate it using huggingface_hub.ModelCardData and pass it to the skops.card.Card class.

Total running time of the script: (0 minutes 2.690 seconds)

Gallery generated by Sphinx-Gallery

	n_estimators n_estimators: int, default=100 The number of trees in the forest. .. versionchanged:: 0.22 The default value of ``n_estimators`` changed from 10 to 100 in 0.22.	10
	criterion criterion: {"squared_error", "absolute_error", "friedman_mse", "poisson"}, default="squared_error" The function to measure the quality of a split. Supported criteria are "squared_error" for the mean squared error, which is equal to variance reduction as feature selection criterion and minimizes the L2 loss using the mean of each terminal node, "friedman_mse", which uses mean squared error with Friedman's improvement score for potential splits, "absolute_error" for the mean absolute error, which minimizes the L1 loss using the median of each terminal node, and "poisson" which uses reduction in Poisson deviance to find splits. Training using "absolute_error" is significantly slower than when using "squared_error". .. versionadded:: 0.18 Mean Absolute Error (MAE) criterion. .. versionadded:: 1.0 Poisson criterion.	'squared_error'
	max_depth max_depth: int, default=None The maximum depth of the tree. If None, then nodes are expanded until all leaves are pure or until all leaves contain less than min_samples_split samples.	None
	min_samples_split min_samples_split: int or float, default=2 The minimum number of samples required to split an internal node: - If int, then consider `min_samples_split` as the minimum number. - If float, then `min_samples_split` is a fraction and `ceil(min_samples_split * n_samples)` are the minimum number of samples for each split. .. versionchanged:: 0.18 Added float values for fractions.	2
	min_samples_leaf min_samples_leaf: int or float, default=1 The minimum number of samples required to be at a leaf node. A split point at any depth will only be considered if it leaves at least ``min_samples_leaf`` training samples in each of the left and right branches. This may have the effect of smoothing the model, especially in regression. - If int, then consider `min_samples_leaf` as the minimum number. - If float, then `min_samples_leaf` is a fraction and `ceil(min_samples_leaf * n_samples)` are the minimum number of samples for each node. .. versionchanged:: 0.18 Added float values for fractions.	1
	min_weight_fraction_leaf min_weight_fraction_leaf: float, default=0.0 The minimum weighted fraction of the sum total of weights (of all the input samples) required to be at a leaf node. Samples have equal weight when sample_weight is not provided.	0.0
	max_features max_features: {"sqrt", "log2", None}, int or float, default=1.0 The number of features to consider when looking for the best split: - If int, then consider `max_features` features at each split. - If float, then `max_features` is a fraction and `max(1, int(max_features * n_features_in_))` features are considered at each split. - If "sqrt", then `max_features=sqrt(n_features)`. - If "log2", then `max_features=log2(n_features)`. - If None or 1.0, then `max_features=n_features`. .. note:: The default of 1.0 is equivalent to bagged trees and more randomness can be achieved by setting smaller values, e.g. 0.3. .. versionchanged:: 1.1 The default of `max_features` changed from `"auto"` to 1.0. Note: the search for a split does not stop until at least one valid partition of the node samples is found, even if it requires to effectively inspect more than ``max_features`` features.	1.0
	max_leaf_nodes max_leaf_nodes: int, default=None Grow trees with ``max_leaf_nodes`` in best-first fashion. Best nodes are defined as relative reduction in impurity. If None then unlimited number of leaf nodes.	None
	min_impurity_decrease min_impurity_decrease: float, default=0.0 A node will be split if this split induces a decrease of the impurity greater than or equal to this value. The weighted impurity decrease equation is the following:: N_t / N * (impurity - N_t_R / N_t * right_impurity - N_t_L / N_t * left_impurity) where ``N`` is the total number of samples, ``N_t`` is the number of samples at the current node, ``N_t_L`` is the number of samples in the left child, and ``N_t_R`` is the number of samples in the right child. ``N``, ``N_t``, ``N_t_R`` and ``N_t_L`` all refer to the weighted sum, if ``sample_weight`` is passed. .. versionadded:: 0.19	0.0
	bootstrap bootstrap: bool, default=True Whether bootstrap samples are used when building trees. If False, the whole dataset is used to build each tree.	True
	oob_score oob_score: bool or callable, default=False Whether to use out-of-bag samples to estimate the generalization score. By default, :func:`~sklearn.metrics.r2_score` is used. Provide a callable with signature `metric(y_true, y_pred)` to use a custom metric. Only available if `bootstrap=True`. For an illustration of out-of-bag (OOB) error estimation, see the example :ref:`sphx_glr_auto_examples_ensemble_plot_ensemble_oob.py`.	False
	n_jobs n_jobs: int, default=None The number of jobs to run in parallel. :meth:`fit`, :meth:`predict`, :meth:`decision_path` and :meth:`apply` are all parallelized over the trees. ``None`` means 1 unless in a :obj:`joblib.parallel_backend` context. ``-1`` means using all processors. See :term:`Glossary ` for more details.	None
	random_state random_state: int, RandomState instance or None, default=None Controls both the randomness of the bootstrapping of the samples used when building trees (if ``bootstrap=True``) and the sampling of the features to consider when looking for the best split at each node (if ``max_features < n_features``). See :term:`Glossary ` for details.	0
	verbose verbose: int, default=0 Controls the verbosity when fitting and predicting.	0
	warm_start warm_start: bool, default=False When set to ``True``, reuse the solution of the previous call to fit and add more estimators to the ensemble, otherwise, just fit a whole new forest. See :term:`Glossary ` and :ref:`tree_ensemble_warm_start` for details.	False
	ccp_alpha ccp_alpha: non-negative float, default=0.0 Complexity parameter used for Minimal Cost-Complexity Pruning. The subtree with the largest cost complexity that is smaller than ``ccp_alpha`` will be chosen. By default, no pruning is performed. See :ref:`minimal_cost_complexity_pruning` for details. See :ref:`sphx_glr_auto_examples_tree_plot_cost_complexity_pruning.py` for an example of such pruning. .. versionadded:: 0.22	0.0
	max_samples max_samples: int or float, default=None If bootstrap is True, the number of samples to draw from X to train each base estimator. - If None (default), then draw `X.shape[0]` samples. - If int, then draw `max_samples` samples. - If float, then draw `max(round(n_samples * max_samples), 1)` samples. Thus, `max_samples` should be in the interval `(0.0, 1.0]`. .. versionadded:: 0.22	None
	monotonic_cst monotonic_cst: array-like of int of shape (n_features), default=None Indicates the monotonicity constraint to enforce on each feature. - 1: monotonically increasing - 0: no constraint - -1: monotonically decreasing If monotonic_cst is None, no constraints are applied. Monotonicity constraints are not supported for: - multioutput regressions (i.e. when `n_outputs_ > 1`), - regressions trained on data with missing values. Read more in the :ref:`User Guide `. .. versionadded:: 1.4	None