Skip to content

API Reference

MELITE exposes a focused public Python API, defined by melite.__all__. Complete classification and regression evaluation is performed through the command-line interface (CLI) using melite run.

The Python API complements these task-specific workflows with programmatic access to configuration, dataset loading, classification evaluation-evidence visualization, classification and regression inference, and version information.

from melite import predict
from melite import Config
from melite import load_datasets
from melite import plot_f1_macro_evidence
from melite import __version__

MELITE is currently pre-stable. The documented symbols are supported for the current release but may evolve before version 1.0.

predict

Loads a fitted artifact produced by melite export. Classification artifacts return labels and optional probabilities; regression artifacts return continuous predictions with probabilities set to None.

Binary and multiclass classifier artifacts preserve their original class identities. For multiclass inference, probability columns follow the loaded model's classes_ order. Numeric artifacts require the same two-dimensional NumPy feature representation, order, and count used for fitting. Exported categorical and mixed CatBoost artifacts instead require a pandas DataFrame whose feature names, order, and compatible categorical/numeric types exactly match the schema stored in the artifact; the original TOML is not required.

Run classification or regression inference with an exported model.

Parameters:

Name Type Description Default
model_path str or Path

Path to a .pkl file produced by melite export.

required
X ndarray or DataFrame

Feature matrix of shape (n_samples, n_features). Numeric artifacts retain the NumPy input contract. Exported categorical CatBoost models require a DataFrame with the same feature names, order, and compatible numeric/categorical types used during training.

required
return_proba bool

Whether to request class probabilities for a classification model when the loaded model supports predict_proba. Default is True. If disabled or unsupported, or if the artifact is a regressor, the returned probabilities value is None.

True

Returns:

Type Description
dict[str, Any]

Dictionary with the following keys:

  • "predictions" : numpy.ndarray One-dimensional output with shape (n_samples,): predicted class labels for classification or continuous numeric predictions for regression.
  • "probabilities" : numpy.ndarray or None Classification probabilities with shape (n_samples, n_classes), or None when unavailable, not requested, or performing regression.
  • "model_path" : str Resolved path to the loaded model artifact.
  • "n_samples" : int Number of samples in X.

Raises:

Type Description
FileNotFoundError

If model_path does not exist.

ValueError

If X violates the artifact's array or DataFrame input contract. For categorical CatBoost artifacts, also raised for missing, extra, reordered, or type-incompatible columns. For regression artifacts, also raised when X is not finite real numerical data or its feature count differs from n_features_in_ exposed by the fitted model.

Notes

This function is intended for fitted model artifacts created by melite export. Regression input validation checks array structure, numerical finiteness, and the fitted model's feature count when available; it cannot verify that columns have the same scientific meaning as during training.

Examples:

>>> import numpy as np
>>> from melite import predict
>>> X_new = np.random.default_rng(42).random((4, 5)).astype(np.float32)
>>> result = predict("output/Model_SVC_sample_tabular.pkl", X_new)
>>> result["predictions"].shape == (4,)
True
>>> result["n_samples"]
4

Config

Loads and normalizes dataset tasks, active classifiers, active regressors, cross-validation settings, optimization settings, and paths.

Configuration container for loading, merging, normalizing, and inspecting MELITE runtime settings.

Loads defaults from melite/config_default.toml. If user_config is provided, its values are merged over the defaults — user values win and missing keys fall back to defaults.

Parameters:

Name Type Description Default
smoke bool

Whether to use reduced CV/search settings for lightweight execution checks. Default is False.

False
user_config Path or None

Optional TOML configuration file merged over packaged defaults. Default is None.

None

Attributes:

Name Type Description
SMOKE bool

Whether the instance was created in smoke mode.

PATHS dict

Dictionary with keys "INPUT", "DATASET", and "OUTPUT" mapping to the corresponding directory paths as strings.

RESULTS_FILE str

Path to the TXT results file (output/results.txt by default).

RANDOM_STATE int

Canonical global random seed used by MELITE runtime and evaluation components. Default is 42.

N_TRIALS int

Optimization trial budget. Normal mode uses the effective [optimization].n_trials value, which defaults to 100. Smoke mode always uses MELITE's internal, non-configurable budget of 5.

DATASETS dict

Normalized dataset registry keyed by user-defined dataset id. Each entry contains path and metadata plus label_path for NPZ datasets or label_column for CSV datasets. Every entry also contains task, which is exactly "classification" or "regression". CSV classification entries may additionally contain a declared categorical_features list. Registered datasets default to classification when task is omitted; the legacy synthesized registry is also classification-only.

ACTIVE_CLASSIFIERS list of str

Classifier keys from [classifiers].active in configured evaluation order. The packaged default is ["svc", "rf", "xgb"].

ACTIVE_REGRESSORS list of str

Validated regressor keys from [regressors].active in configured evaluation order. Supported values are "linear", "poly", "ridge", and "lasso". The packaged default is an empty list; at least one regressor is required when any registered dataset has task = "regression".

CATBOOST_CONFIG dict

Validated optional settings from [catboost]. Empty when the section or boosting_type is omitted; otherwise contains boosting_type set to exactly "Plain" or "Ordered".

CV_CONFIG dict

Cross-validation settings with keys n_splits, n_repeats, and inner_n_splits.

Raises:

Type Description
FileNotFoundError

If the supplied user configuration file does not exist.

ValueError

If a user configuration uses the obsolete [models] section, defines the unsupported [optimization_smoke] section, specifies random_state under [cv] or [cv_smoke] instead of [benchmark], contains an unsupported [optimization] key, sets an invalid [optimization].n_trials value, or defines an invalid registered dataset or active-regressor list, or configures a regression dataset without an active regressor. Registered datasets support only .npz files with label_path and .csv files with a non-empty label_column; task accepts exactly "classification" or "regression". [catboost].boosting_type accepts exactly "Plain" or "Ordered".

Examples:

Default configuration:

>>> from melite import Config
>>> cfg = Config()
>>> cfg.RANDOM_STATE
42

Smoke mode:

>>> cfg = Config(smoke=True)
>>> cfg.CV_CONFIG["n_splits"]
3

load_datasets

Loads registered NPZ and CSV datasets while preserving each normalized classification or regression task.

Load every normalized classification or regression dataset.

Parameters:

Name Type Description Default
config Config

Normalized MELITE configuration containing DATASETS.

required

Returns:

Type Description
dict[str, dict[str, Any]]

Dictionary keyed by user-defined dataset id. Each dataset value is a dictionary containing:

  • "X" : numpy.ndarray or pandas.DataFrame Two-dimensional feature matrix. Numeric datasets use NumPy arrays; CSV datasets declaring categorical features use DataFrames that preserve feature names and column order.
  • "y" : numpy.ndarray One-dimensional target vector loaded from label_path for NPZ or from label_column for CSV. Classification targets may contain categorical class labels. Regression targets represent quantitative values and are subject to the regression workflow's finite real numerical validation.
  • "task" : str Normalized prediction task, exactly "classification" or "regression". Configuration normalization supplies "classification" when the dataset omits task.
  • "metadata" : dict Shallow copy of the dataset metadata dictionary. Metadata keys are transported but not interpreted by load_datasets; nested mutable values are not deep-copied.

Dataset ids are not interpreted as method, representation, reduction, or model names. For NPZ, the configured label_path is authoritative and an embedded y is used only as a consistency check. For CSV, the configured label_column supplies y and all remaining columns supply X in their original order. Declared categorical columns are loaded as non-missing strings and all other predictors must be numeric. Loading preserves the target values and task identity; task-specific training applies the corresponding target contract.

Raises:

Type Description
FileNotFoundError

If a configured dataset file or authoritative label file does not exist.

ValueError

If an NPZ dataset violates its feature or label consistency contract, or if a CSV cannot be parsed, lacks its configured label or any feature columns, contains an Unnamed: column, a non-numeric undeclared feature column, a missing declared categorical column, invalid categorical values, or invalid feature or label dimensions or row counts.

Examples:

>>> import pandas as pd
>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> from melite import Config, load_datasets
>>> with TemporaryDirectory() as temporary_directory:
...     root = Path(temporary_directory).resolve()
...     data_path = root / "sample_tabular.csv"
...     config_path = root / "config.toml"
...     table = pd.DataFrame(
...         {
...             "feature_a": [0.0, 1.0],
...             "feature_b": [1.0, 0.0],
...             "Outcome": ["class_a", "class_b"],
...         }
...     )
...     table.to_csv(data_path, index=False)
...     config_text = (
...         "[datasets.sample_tabular]\n"
...         f'path = "{data_path.as_posix()}"\n'
...         'label_column = "Outcome"\n'
...         'description = "Neutral numeric example"\n'
...     )
...     _ = config_path.write_text(config_text, encoding="utf-8")
...     cfg = Config(user_config=config_path)
...     loaded = load_datasets(cfg)
...     loaded["sample_tabular"]["task"], loaded["sample_tabular"]["X"].shape
('classification', (2, 2))

plot_f1_macro_evidence

Creates the classification F1-macro evidence visualization from existing outer-cross-validation results. Regression does not currently expose a corresponding plotting function.

Visualize preserved outer-CV F1-macro evidence.

The supplied scores are plotted directly, and the classifier previously selected by the evaluation workflow is explicitly marked.

Parameters:

Name Type Description Default
classifier_scores Mapping[str, Sequence[float]]

Mapping from classifier name to supplied outer-CV F1-macro scores. Each score sequence must be numeric, one-dimensional, non-empty, finite, and within [0, 1].

required
selected_classifier str

Classifier previously selected by the evaluation workflow. This function marks that classifier but does not recompute selection.

required
dataset_id str

User-defined dataset identifier shown in the figure title.

required
save_to Path or str or None

Optional destination path. Parent directories are created automatically, and Matplotlib infers the output format from the path or extension. If None, the figure is not saved.

None
smoke bool

Whether to annotate the figure as smoke-mode evidence. This affects presentation only.

False

Returns:

Type Description
Figure

Newly created figure. The function does not show or close it; the caller owns the returned figure and is responsible for displaying or closing it when appropriate.

Raises:

Type Description
ValueError

If classifier_scores is empty; if selected_classifier is not present; or if any classifier's scores cannot be converted to floats, are not one-dimensional, are empty, contain non-finite values, or fall outside [0, 1].

Notes

This function performs no fitting, hyperparameter tuning, cross-validation, or classifier selection. Supplied scores are visualized directly. The mean and population standard deviation (ddof=0) are shown. Classifiers follow the iteration order of the supplied mapping. Horizontal jitter uses a deterministic local random-number generator and affects display position only; supplied F1-macro values are not modified.

Saved raster output uses 300 dpi; vector formats follow Matplotlib's behavior. Filesystem and Matplotlib saving errors propagate to the caller.

Examples:

>>> import matplotlib.pyplot as plt
>>> from melite import plot_f1_macro_evidence
>>> scores = {
...     "SVC": [0.78, 0.82, 0.80],
...     "RandomForestClassifier": [0.81, 0.84, 0.83],
... }
>>> fig = plot_f1_macro_evidence(
...     scores,
...     selected_classifier="RandomForestClassifier",
...     dataset_id="sample_tabular",
... )
>>> fig.axes[0].get_ylabel()
'Outer-CV F1-macro'
>>> plt.close(fig)

__version__

Current MELITE package version.

For workflow-oriented examples, configuration, and the evaluation contract, see Usage.