datasets

`eigenkit.datasets`

The datasets of eigenkit: the registry of their metadata, and the loaders.

`FONTSIZE_AXES = 20` `module-attribute`

The font size, in points, that rc_params() gives the axis labels and titles.

`FONTSIZE_LEGEND = 18` `module-attribute`

The font size, in points, that rc_params() gives the legend entries.

`FONTSIZE_TICKS = 16` `module-attribute`

The font size, in points, of the tick labels, which is also the base font.size.

`STYLE_COLORS = ('#CE2173', '#AA5EFF', '#7D4ECF', '#43CDFF', '#3333FB', '#11E57A', '#E6C541', '#94A3B8')` `module-attribute`

The plot palette of the library, in the order of the colour cycle.

rc_params() sets it as axes.prop_cycle, so a plot drawn inside that context uses these colours without naming them. Index it when a series needs a fixed colour, and not the next one in the cycle. For example, use STYLE_COLORS[0] for a training curve and STYLE_COLORS[1] for validation, so that the two curves keep their colours across figures. It is a tuple, so that an append by mistake cannot change how every later plot in the process looks.

`DatasetInfo`

Bases: BaseModel

The metadata of a dataset that eigenkit provides.

Parameters:

Name	Type	Description	Default
`name`	`str`	The unique name of the dataset, which is also its key in `REGISTRY`.	required
`source`	`str`	Where the dataset comes from. It is one of these values: `'sklearn'`: the dataset is loaded with a function of `sklearn.datasets`. `'url'`: the dataset is downloaded from a web address. `'synthetic'`: the dataset is generated by a function, for example `make_moons`.	required
`url`	`str`	The web address of the file to download. It is used only when `source='url'`.	`None`
`sha256`	`str`	The SHA-256 hash, in hexadecimal, that the downloaded file must match. A downloaded file that does not match is deleted, and a `ValueError` is raised. A cached file that does not match is downloaded again. It is used only when `source='url'`.	`None`
`sklearn_loader`	`str`	The name of the `sklearn.datasets` function, for example `'load_iris'`. It is used only when `source='sklearn'`.	`None`
`synthetic_generator`	`str`	The name of the generator function, for example `'make_moons'`. It is used only when `source='synthetic'`.	`None`
`task`	`str`	The type of task: `'classification'`, `'regression'`, `'timeseries'`, `'optimization'` or `'chemistry'`.	required
`n_features`	`int`	The number of input features. It must be at least `1`.	required
`n_samples`	`int`	The total number of samples. It is `None` when the number is not recorded, for example for the synthetic datasets, whose size is chosen when they are generated.	`None`
`n_classes`	`int`	The number of classes. It is `None` for regression and time-series tasks.	`None`
`feature_names`	`list[str]`	Readable names of the input features.	`None`
`target_names`	`list[str]`	Readable names of the classes, or of the output.	`None`
`window_size`	`int`	The recommended size of the sliding window, for time-series datasets.	`None`
`description`	`str`	A short description of the dataset.	required

Example

info = DatasetInfo(
    name="iris",
    source="sklearn",
    sklearn_loader="load_iris",
    task="classification",
    n_features=4,
    n_samples=150,
    n_classes=3,
    description="Classic multi-class classification dataset.",
)

`DatasetReport` `dataclass`

An exploratory data analysis (EDA) report for a built-in or custom dataset.

Parameters:

Name	Type	Description	Default
`X`	`ndarray`	The feature matrix, of shape `(n_samples, n_features)`.	required
`y`	`ndarray`	The target vector, of shape `(n_samples,)`.	required
`feature_names`	`list[str]`	Readable names of the features, in the order of the columns of `X`.	required
`target_name`	`str`	The name of the target in the plots and the summary.	required
`task`	`str`	The type of task, usually `"classification"`, `"regression"` or `"timeseries"`.	required
`metadata`	`Any`	The metadata of the dataset, for example a `DatasetInfo`.	`None`
`time_index`	`Any`	The time axis for the time-series plots. It can be numeric (array-like) or a `pd.DatetimeIndex`.	`None`
`theme`	`str`	The theme of the plots, `"light"` or `"dark"`.	`'light'`

Notes

The recommended way to build a report is from_data(), which accepts the dictionaries returned by load_dataset(...) as well as your own X and y.

Example

from eigenkit.datasets import DatasetReport, load_dataset

data = load_dataset("iris", split=False)
report = DatasetReport.from_data(data)
figs = report.plot_overview()
summary = report.summarize()

`from_data(data=None, *, X=None, y=None, feature_names=None, target_name='target', task=None, time_index=None, theme='light')` `classmethod`

Build a report from a dataset dictionary, or from your own arrays or tensors.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	A dataset dictionary in the format of eigenkit, either `{"X", "y"}` or `{"X_train", "y_train", "X_test", "y_test"}`. The training and test sets are combined.	`None`
`X`	`Any`	Your own feature matrix, as a NumPy array, a pandas object, a PyTorch tensor or another array-like.	`None`
`y`	`Any`	Your own target vector, in the same formats as `X`.	`None`
`feature_names`	`list[str]`	The names of the features. If they are not given, the names come from the metadata, or they are `feature_0`, `feature_1` and so on.	`None`
`target_name`	`str`	The name of the target in the plots and the summary.	`'target'`
`task`	`str`	The type of task. If it is not given, it is taken from the metadata, or guessed from `y`.	`None`
`time_index`	`Any`	The time axis for the time-series analysis.	`None`
`theme`	`str`	The theme of the plots, `"light"` or `"dark"`.	`'light'`

Returns:

Type	Description
`'DatasetReport'`	The report, ready for plotting and for the summary.

Raises:

Type	Description
`ValueError`	If the inputs are missing or do not agree, for example if the shapes do not match, or if `feature_names` does not have one name per feature.

`plot(kind, **kwargs)`

Build one plot, chosen by its kind.

Parameters:

Name	Type	Description	Default
`kind`	`str`	The kind of plot: `"data_health"`, `"target"`, `"distributions"`, `"correlation"`, `"feature_target"` or `"timeseries_target"`.	required
`**kwargs`	`Any`	Options of the plot, such as `bins`, `max_features` and `max_points`.	`{}`

Returns:

Type	Description
`Any`	The matplotlib figure.

Raises:

Type	Description
`ValueError`	If `kind` is not one of the kinds above.

`plot_overview(*, max_features=None, bins=30, max_points=2000, path=None)`

Build the default set of plots of the exploratory data analysis.

Parameters:

Name	Type	Description	Default
`max_features`	`int`	The largest number of features shown in the panels about features. `None` shows every feature.	`None`
`bins`	`int`	The number of histogram bins in the distribution plots.	`30`
`max_points`	`int`	The largest number of points in the scatter plots. Larger datasets are subsampled.	`2000`
`path`	`str \| Path`	A directory where every overview plot is saved as a PNG file. With `None`, the plots are not saved.	`None`

Returns:

Type	Description
`dict[str, Any]`	A dictionary from each kind of plot to its matplotlib figure. The `"timeseries_target"` plot is included only for a time-series task.

`summarize()`

Build a reproducible summary of the dataset, with recommendations.

Returns:

Type	Description
`dict[str, Any]`	A dictionary with statistics about the shape and the quality of the data, signals specific to the task when there are any, and a readable summary under the `"text"` key.

`generate_ad_hoc(n_samples=200, n_qubits=2, gap=0.3, random_state=42)`

Generate the "ad hoc" dataset of Havlíček et al., Nature 567, 209 (2019).

The dataset is designed so that a quantum kernel separates it. Each point x in [0, 2π)^n is encoded with the ZZ feature map, with two repetitions as in Qiskit's ZZFeatureMap. Its label is the sign of ⟨ψ(x)| V† Z^{⊗n} V |ψ(x)⟩ for a fixed random unitary V. The points closer than gap to the decision boundary are dropped, and the two classes are balanced. A kernel built from the same ZZ feature map classifies the data almost perfectly, and classical kernels usually do not.

Parameters:

Name	Type	Description	Default
`n_samples`	`int`	The number of points, split evenly between the two classes.	`200`
`n_qubits`	`int`	The number of features, which is also the number of qubits of the circuit that generates the data.	`2`
`gap`	`float`	The margin around the decision boundary, in `[0, 1)`.	`0.3`
`random_state`	`int \| None`	The seed of the unitary `V` and of the sampled points.	`42`

Returns:

Type	Description
`tuple[ndarray, ndarray]`	The pair `(X, y)`, with `X` of shape `(n_samples, n_qubits)` and `y` of shape `(n_samples,)`. The labels are `0` and `1`.

Raises:

Type	Description
`ValueError`	If `gap` is not in `[0, 1)`, or if `n_qubits < 1`.

`generate_checkerboard(n_samples=200, grid_size=2, random_state=42)`

Generate a dataset with a checkerboard pattern.

The points are drawn uniformly in [0, grid_size]². The label is (floor(x) + floor(y)) % 2, which gives regions of alternating classes.

Parameters:

Name	Type	Description	Default
`n_samples`	`int`	The number of points to generate.	`200`
`grid_size`	`int`	The number of cells along each axis.	`2`
`random_state`	`int \| None`	The random seed, for reproducible results.	`42`

Returns:

Type	Description
`tuple[ndarray, ndarray]`	The pair `(X, y)`, with `X` of shape `(n_samples, 2)` and `y` of shape `(n_samples,)`.

`generate_circles(n_samples=200, noise=0.05, factor=0.5, random_state=42)`

Generate two concentric circles.

Parameters:

Name	Type	Description	Default
`n_samples`	`int`	The number of points to generate.	`200`
`noise`	`float`	The standard deviation of the Gaussian noise added to the data.	`0.05`
`factor`	`float`	The ratio of the inner circle to the outer circle, between `0` and `1`.	`0.5`
`random_state`	`int \| None`	The random seed, for reproducible results.	`42`

Returns:

Type	Description
`tuple[ndarray, ndarray]`	The pair `(X, y)`, with `X` of shape `(n_samples, 2)` and `y` of shape `(n_samples,)`.

`generate_moons(n_samples=200, noise=0.1, random_state=42)`

Generate two half-circles that interleave, called moons.

Parameters:

Name	Type	Description	Default
`n_samples`	`int`	The number of points to generate.	`200`
`noise`	`float`	The standard deviation of the Gaussian noise added to the data.	`0.1`
`random_state`	`int \| None`	The random seed, for reproducible results.	`42`

Returns:

Type	Description
`tuple[ndarray, ndarray]`	The pair `(X, y)`, with `X` of shape `(n_samples, 2)` and `y` of shape `(n_samples,)`.

`generate_regression(n_samples=200, n_features=4, noise=0.1, random_state=42)`

Generate a synthetic regression dataset with scikit-learn's make_regression.

Parameters:

Name	Type	Description	Default
`n_samples`	`int`	The number of samples to generate.	`200`
`n_features`	`int`	The number of input features.	`4`
`noise`	`float`	The standard deviation of the Gaussian noise on the output.	`0.1`
`random_state`	`int \| None`	The random seed, for reproducible results.	`42`

Returns:

Type	Description
`tuple[ndarray, ndarray]`	The pair `(X, y)`, with `X` of shape `(n_samples, n_features)` and `y` of shape `(n_samples,)`, both of type `float32`.

`generate_timeseries(n_samples=300, kind='sine', noise=0.05, random_state=42)`

Generate a 1-D time series, as the pair (t, y).

Parameters:

Name	Type	Description	Default
`n_samples`	`int`	The number of time steps.	`300`
`kind`	`str`	The shape of the series: `"sine"` for a sine wave with noise, or `"ar"` for an autoregressive process of order `1`, written AR(1).	`'sine'`
`noise`	`float`	The standard deviation of the Gaussian noise.	`0.05`
`random_state`	`int \| None`	The random seed, for reproducible results.	`42`

Returns:

Type	Description
`tuple[ndarray, ndarray]`	The pair `(t, y)`, two arrays of shape `(n_samples,)` and type `float32`. `t` holds time values spaced evenly in `[0, 1]`, and `y` is the signal. The arrays are not cut into windows, because the algorithms do that.

`get_dataset_info(name)`

Return the DatasetInfo of a dataset.

Parameters:

Name	Type	Description	Default
`name`	`str`	The key of the dataset in `REGISTRY`.	required

Returns:

Type	Description
`DatasetInfo`	The metadata of the dataset.

Raises:

Type	Description
`ValueError`	If `name` is not in the registry. The message lists every available name.

Example

info = get_dataset_info("iris")

`list_datasets()`

Return the metadata of every available dataset.

Returns:

Type	Description
`list[DatasetInfo]`	One `DatasetInfo` for each dataset in the registry.

Example

datasets = list_datasets()
print(datasets[0].name)  # 'breast_cancer_wisconsin'

`load_dataset(name, *, split=True, test_size=0.2, validation_size=0.0, random_state=42, cache_dir=None)`

Load a dataset by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the dataset in `REGISTRY`, for example `"iris"`.	required
`split`	`bool`	If `True`, the default, the data is split into a training set and a test set.	`True`
`test_size`	`float`	The fraction of the samples used for the test set.	`0.2`
`validation_size`	`float`	The fraction of the samples used for the validation set. With `0`, the default, there is no validation set.	`0.0`
`random_state`	`int \| None`	The random seed of the split, and of the generator for the synthetic datasets.	`42`
`cache_dir`	`str \| None`	A cache directory for the downloaded datasets, in place of the default one.	`None`

Returns:

Type	Description
`dict`	A dictionary with these keys: With `split=True`: `"X_train"`, `"y_train"`, `"X_test"`, `"y_test"` and `"metadata"`, and also `"X_val"` and `"y_val"` when `validation_size` is above `0`. With `split=False`: `"X"`, `"y"` and `"metadata"`. The synthetic time-series datasets also have a `"sequence"` key, which holds the whole series. `"metadata"` is the `DatasetInfo` of the dataset.

Raises:

Type	Description
`ValueError`	If `name` is not in the registry, if `validation_size` is not in `[0, 1)`, or if `test_size + validation_size` is `1` or more with `split=True`.

Example

data = load_dataset("iris")
X_train, y_train = data["X_train"], data["y_train"]

`rc_params(theme='light')`

Return the matplotlib settings of the library for one plot, as rcParams.

Every figure that the library draws uses these settings: DatasetReport.plot_overview(), the benchmark curves and the plots in the worked examples. This is what makes them look like one set. Pass the result to matplotlib.rc_context() and draw as usual. The settings apply only inside that block, because the returned dictionary is a new copy and the global matplotlib.rcParams is never changed.

The two themes differ only in what has to change for a dark page. "dark" makes the backgrounds of the figure, the axes and the legend transparent, and makes the text, the ticks and the spines white. The sizes, the spines, the grid and STYLE_COLORS are the same in both themes, so a figure saved with each theme differs only in its background and in the colour of its text and lines.

Parameters:

Name	Type	Description	Default
`theme`	`str`	`"light"` or `"dark"`. The case and any surrounding spaces are ignored.	`'light'`

Returns:

Type	Description
`dict`	The rcParams to draw with, ready for `matplotlib.rc_context()`.

Raises:

Type	Description
`ValueError`	If `theme` is neither `"light"` nor `"dark"`.

Example

import matplotlib
import matplotlib.pyplot as plt
from eigenkit.datasets import STYLE_COLORS, rc_params

with matplotlib.rc_context(rc_params(theme="light")):
    fig, ax = plt.subplots(figsize=(7, 4))
    ax.plot(history, color=STYLE_COLORS[0], label="train loss")
    ax.legend()
    fig.savefig("loss.png", bbox_inches="tight")

datasets

eigenkit.datasets

FONTSIZE_AXES = 20 module-attribute

FONTSIZE_LEGEND = 18 module-attribute

FONTSIZE_TICKS = 16 module-attribute

STYLE_COLORS = ('#CE2173', '#AA5EFF', '#7D4ECF', '#43CDFF', '#3333FB', '#11E57A', '#E6C541', '#94A3B8') module-attribute

DatasetInfo

DatasetReport dataclass

from_data(data=None, *, X=None, y=None, feature_names=None, target_name='target', task=None, time_index=None, theme='light') classmethod

plot(kind, **kwargs)

plot_overview(*, max_features=None, bins=30, max_points=2000, path=None)

summarize()

generate_ad_hoc(n_samples=200, n_qubits=2, gap=0.3, random_state=42)

generate_checkerboard(n_samples=200, grid_size=2, random_state=42)

generate_circles(n_samples=200, noise=0.05, factor=0.5, random_state=42)

generate_moons(n_samples=200, noise=0.1, random_state=42)

generate_regression(n_samples=200, n_features=4, noise=0.1, random_state=42)

generate_timeseries(n_samples=300, kind='sine', noise=0.05, random_state=42)

get_dataset_info(name)

list_datasets()

load_dataset(name, *, split=True, test_size=0.2, validation_size=0.0, random_state=42, cache_dir=None)

rc_params(theme='light')

`eigenkit.datasets`

`FONTSIZE_AXES = 20` `module-attribute`

`FONTSIZE_LEGEND = 18` `module-attribute`

`FONTSIZE_TICKS = 16` `module-attribute`

`STYLE_COLORS = ('#CE2173', '#AA5EFF', '#7D4ECF', '#43CDFF', '#3333FB', '#11E57A', '#E6C541', '#94A3B8')` `module-attribute`

`DatasetInfo`

`DatasetReport` `dataclass`

`from_data(data=None, *, X=None, y=None, feature_names=None, target_name='target', task=None, time_index=None, theme='light')` `classmethod`

`plot(kind, **kwargs)`

`plot_overview(*, max_features=None, bins=30, max_points=2000, path=None)`

`summarize()`

`generate_ad_hoc(n_samples=200, n_qubits=2, gap=0.3, random_state=42)`

`generate_checkerboard(n_samples=200, grid_size=2, random_state=42)`

`generate_circles(n_samples=200, noise=0.05, factor=0.5, random_state=42)`

`generate_moons(n_samples=200, noise=0.1, random_state=42)`

`generate_regression(n_samples=200, n_features=4, noise=0.1, random_state=42)`

`generate_timeseries(n_samples=300, kind='sine', noise=0.05, random_state=42)`

`get_dataset_info(name)`

`list_datasets()`

`load_dataset(name, *, split=True, test_size=0.2, validation_size=0.0, random_state=42, cache_dir=None)`

`rc_params(theme='light')`