API Reference¶

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

The Python API complements this workflow with programmatic access to configuration, dataset loading, evaluation-evidence visualization, 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. During the 0.2.x series, the documented symbols are supported for the current release but may evolve before version 1.0.

`predict`¶

Run inference with a model artifact produced by melite export.

Parameters:

Name	Type	Description	Default
`model_path`	`str or Path`	Path to a `.pkl` file produced by `melite export`.	required
`X`	`ndarray`	Numeric feature matrix of shape `(n_samples, n_features)`. It must use the same feature representation and number of features expected by the exported model, and it must be two-dimensional.	required
`return_proba`	`bool`	Whether to request class probabilities when the loaded model supports `predict_proba`. Default is `True`. If disabled or unsupported, the returned `probabilities` value is `None`.	`True`

Returns:

Type	Description
`dict[str, Any]`	Dictionary with the following keys: `"predictions"` : numpy.ndarray Predicted class labels with shape `(n_samples,)`. `"probabilities"` : numpy.ndarray or None Class probabilities with shape `(n_samples, n_classes)`, or `None` when unavailable or not requested. `"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` is not a two-dimensional NumPy array.

Notes

This function is intended for fitted model artifacts created by melite export.

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`¶

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.
`ACTIVE_CLASSIFIERS`	`list of str`	Classifier keys to include in the evaluation (e.g. `["svc", "rf", "xgb"]`; add `"stack"` to opt in to stacking).
`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. Registered datasets support only .npz files with label_path and .csv files with a non-empty label_column.

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`¶

Load every normalized dataset in a MELITE configuration.

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 Two-dimensional numeric feature matrix.
"y" : numpy.ndarray One-dimensional label vector loaded from label_path for NPZ or from label_column for CSV.
"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 classifier 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.

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 or non-numeric feature column, or produces 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"]["X"].shape
(2, 2)

`plot_f1_macro_evidence`¶

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.

API Reference¶

predict¶

Config¶

load_datasets¶

plot_f1_macro_evidence¶

__version__¶

`predict`¶

`Config`¶

`load_datasets`¶

`plot_f1_macro_evidence`¶

`version`¶