API reference#

Dataset#

class Dataset(X: NDArray[float64], y: NDArray[Any], feature_names: tuple[str, ...], target_names: tuple[str, ...] | None, description: str, info: DatasetInfo)[source]#

Dataset with its data matrix, targets and metadata.

Iterating over a Dataset yields X and y, so X, y = load_iris() works as well as data = load_iris().

Attributes:
  • X (ndarray of shape (n_samples, n_features)) – Data matrix. Missing values, if the dataset has any, are NaN.

  • y (ndarray of shape (n_samples,) or (n_samples, n_targets)) – Target values.

  • feature_names (tuple of str) – Names of the columns of X.

  • target_names (tuple of str or None) – Class names for classification or target names for multi-output regression, None if the source does not provide them.

  • description (str) – Description of the dataset: what it is, where it comes from, how to cite it, which license applies and which changes were made.

  • info (DatasetInfo) – The structured form of the provenance and license information.

property has_missing: bool#

Whether X contains at least one missing value (NaN).

property categorical_features: tuple[int, ...]#

Column indices of the categorical features, stored as integer codes.

The category names of a column are in info.categorical under the feature name.

Iterating over a Dataset yields X and then y.

DatasetInfo#

class DatasetInfo(*, name: str, title: str, task: Literal['classification', 'regression'], summary: str, license: Literal['CC0-1.0', 'CC-BY-4.0'], license_url: str, source: str, source_url: str, doi: str | None, creators: tuple[str, ...], citation: str, obtained_from: str, changes: tuple[str, ...], verified_on: str, references: tuple[str, ...] = (), categorical: Mapping[str, tuple[str, ...]] = dict(), has_missing: bool = False, notes: tuple[str, ...] = ())[source]#

Provenance and license of a dataset.

Every bundled dataset has exactly one DatasetInfo. Everything that talks about a dataset’s origin (the description stored in its file, the NOTICE.md file, the tables of the README and of the documentation) is generated from it, so a fact is written down only once. Invalid values are rejected when the object is created.

Attributes:
  • name (str) – Short identifier, lowercase letters, digits and underscores. It is also the name of the data file (<name>.npz) and of the loader (load_<name>).

  • title (str) – Human readable name of the dataset.

  • task ({“classification”, “regression”}) – Kind of the prediction problem. It decides the dtype of y.

  • summary (str) – One or two sentences about what the dataset contains.

  • license ({“CC0-1.0”, “CC-BY-4.0”}) – SPDX identifier of the license the data is redistributed under. Only licenses that allow redistribution with at most an attribution duty are accepted.

  • license_url (str) – Address of the license text.

  • source (str) – Name of the original publisher of the data.

  • source_url (str) – Page of the original publisher that describes the dataset and its license.

  • doi (str or None) – DOI of the dataset or of the release that was used, without the resolver prefix.

  • creators (tuple of str) – The people or institutions that created the dataset, as the source names them.

  • citation (str) – The citation the source asks users to give, copied as the source writes it.

  • obtained_from (str) – Where the bytes in this repository really came from. It can differ from source when a copy of the dataset was used.

  • changes (tuple of str) – Every change made to the data, as the attribution duty of the license requires.

  • verified_on (str) – ISO date (YYYY-MM-DD) on which the license was last checked at the source.

  • references (tuple of str, default=()) – Papers and records that describe the dataset or that the source asks to cite.

  • categorical (mapping of str to tuple of str, default={}) – Categorical features. Each key is a feature name, each value the category names in the order of the integer codes stored in X (code 0 is the first name).

  • has_missing (bool, default=False) – Whether X contains missing values. They are stored as NaN.

  • notes (tuple of str, default=()) – Warnings and remarks that users of the dataset should see.

to_dict() → dict[str, Any][source]#

Return the information as a dict of plain Python values.

Return type:

dict[str, Any]

Returns:

dict of str to object – Strings, lists, dicts, booleans and None only, so the result can be written as JSON.

Finding datasets#

list_datasets(task: Optional[Literal['classification', 'regression']] = None) → tuple[str, ...][source]#

List the names of the bundled datasets.

No dataset module is imported to answer this.

Parameters:

task (Optional[Literal['classification', 'regression']], default: None) – Keep only the datasets of this task, all datasets if not given.

Return type:

tuple[str, ...]

Returns:

tuple of str – Dataset names in alphabetical order. Each name works with load_dataset.

Examples

>>> from pyml_datasets import list_datasets
>>> "iris" in list_datasets()
True
>>> "iris" in list_datasets("regression")
False
get_info(name: str) → DatasetInfo[source]#

Return the provenance and license of a dataset without reading its data.

Parameters:

name (str) – Dataset name, one of list_datasets().

Return type:

DatasetInfo

Returns:

DatasetInfo – License, source, citation and changes of the dataset.

Raises:

ValueError – If no dataset has this name.

Examples

>>> from pyml_datasets import get_info
>>> get_info("iris").license
'CC-BY-4.0'
load_dataset(name: str) → Dataset[source]#

Load a dataset by its name.

This is the same as calling the load_<name> function of the dataset.

Parameters:

name (str) – Dataset name, one of list_datasets().

Return type:

Dataset

Returns:

Dataset – Freshly loaded dataset.

Raises:

ValueError – If no dataset has this name.

Examples

>>> from pyml_datasets import load_dataset
>>> X, y = load_dataset("iris")
>>> X.shape
(150, 4)

Loaders#

load_abalone() → Dataset[source]#

Load the Abalone dataset (regression, 4177 samples, 8 features).

The dataset has one categorical feature, sex, stored as integer codes.

Return type:

Dataset

Returns:

Dataset – Dataset with the sex and the physical measurements of an abalone as features and the number of rings of its shell as target. Dataset.info holds the license, the source, the citation and the names of the categories.

Examples

>>> from pyml_datasets import load_abalone
>>> X, y = load_abalone()
>>> X.shape, y.shape
((4177, 8), (4177,))
load_adult() → Dataset[source]#

Load the Adult dataset (classification, 48842 samples, 14 features).

Return type:

Dataset

Returns:

Dataset – Dataset with person features, 8 of them categorical integer codes, and two classes: the yearly income is at most 50K (0) or above 50K (1). Missing entries of three features are NaN. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_adult
>>> X, y = load_adult()
>>> X.shape, y.shape
((48842, 14), (48842,))
load_airfoil_self_noise() → Dataset[source]#

Load the Airfoil Self-Noise dataset (regression, 1503 samples, 5 features).

Return type:

Dataset

Returns:

Dataset – Dataset with the frequency, the angle of attack, the chord length, the free-stream velocity and the suction side displacement thickness as features, and the scaled sound pressure level in decibels as target. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_airfoil_self_noise
>>> X, y = load_airfoil_self_noise()
>>> X.shape, y.shape
((1503, 5), (1503,))
load_auto_mpg() → Dataset[source]#

Load the Auto MPG dataset (regression, 398 samples, 7 features).

The dataset has 6 missing values in horsepower, stored as NaN.

Return type:

Dataset

Returns:

Dataset – Dataset with the characteristics of a car as features and its fuel consumption in miles per gallon as target. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_auto_mpg
>>> X, y = load_auto_mpg()
>>> X.shape, y.shape
((398, 7), (398,))
load_bank_marketing() → Dataset[source]#

Load the Bank Marketing dataset (classification, 45211 samples, 16 features).

Return type:

Dataset

Returns:

Dataset – Dataset with client and campaign features, 9 of them categorical integer codes, and two classes: the client did not (0) or did (1) subscribe a term deposit. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_bank_marketing
>>> X, y = load_bank_marketing()
>>> X.shape, y.shape
((45211, 16), (45211,))
load_breast_cancer() → Dataset[source]#

Load the Breast Cancer Wisconsin (Diagnostic) dataset.

Binary classification with 569 samples and 30 features.

Return type:

Dataset

Returns:

Dataset – Dataset with malignant (0) and benign (1) classes. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_breast_cancer
>>> X, y = load_breast_cancer()
>>> X.shape, y.shape
((569, 30), (569,))
load_combined_cycle_power_plant() → Dataset[source]#

Load the Combined Cycle Power Plant dataset (regression, 9568 samples, 4 features).

Return type:

Dataset

Returns:

Dataset – Dataset with the temperature, the exhaust vacuum, the ambient pressure and the relative humidity as features and the net hourly electrical energy output in MW as target. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_combined_cycle_power_plant
>>> X, y = load_combined_cycle_power_plant()
>>> X.shape, y.shape
((9568, 4), (9568,))
load_concrete_strength() → Dataset[source]#

Load the Concrete Compressive Strength dataset (regression, 1030 samples, 8 features).

Return type:

Dataset

Returns:

Dataset – Dataset with the amounts of the ingredients and the age of the concrete as features and its compressive strength in MPa as target. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_concrete_strength
>>> X, y = load_concrete_strength()
>>> X.shape, y.shape
((1030, 8), (1030,))
load_credit_card_default() → Dataset[source]#

Load the Default of Credit Card Clients dataset.

Binary classification with 30000 samples and 23 features: credit limit, demographics, six months of repayment status, bill amounts and previous payments.

Return type:

Dataset

Returns:

Dataset – X has shape (30000, 23). y has shape (30000,) and holds the codes 0 (no default payment next month) and 1 (default payment next month), in the order of target_names. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_credit_card_default
>>> X, y = load_credit_card_default()
>>> X.shape, y.shape
((30000, 23), (30000,))
load_digits() → Dataset[source]#

Load the handwritten digits dataset (classification, 1797 samples, 64 features).

Return type:

Dataset

Returns:

Dataset – Dataset with the 10 digits as classes and the pixels of an 8x8 image as features. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_digits
>>> X, y = load_digits()
>>> X.shape, y.shape
((1797, 64), (1797,))
load_energy_efficiency() → Dataset[source]#

Load the Energy Efficiency dataset (regression, 768 samples, 8 features, 2 targets).

Return type:

Dataset

Returns:

Dataset – Dataset with the parameters of a building as features and its heating load and cooling load as the two columns of the target y. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_energy_efficiency
>>> X, y = load_energy_efficiency()
>>> X.shape, y.shape
((768, 8), (768, 2))
load_forest_fires() → Dataset[source]#

Load the Forest Fires dataset (regression, 517 samples, 12 features).

Return type:

Dataset

Returns:

Dataset – Dataset with the place, the time and the weather of a fire, two of the features (month and day) categorical integer codes, and the burned area in hectares as the target. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_forest_fires
>>> X, y = load_forest_fires()
>>> X.shape, y.shape
((517, 12), (517,))
load_german_credit() → Dataset[source]#

Load the German Credit dataset (classification, 1000 samples, 20 features).

Return type:

Dataset

Returns:

Dataset – Dataset with credit applicants described by 20 features, 13 of them categorical integer codes, and two classes: a good (0) or a bad (1) credit risk. Dataset.info holds the license, the source, the citation and the cost matrix of the source in its notes.

Examples

>>> from pyml_datasets import load_german_credit
>>> X, y = load_german_credit()
>>> X.shape, y.shape
((1000, 20), (1000,))
load_iris() → Dataset[source]#

Load the Iris dataset (classification, 150 samples, 4 features).

Return type:

Dataset

Returns:

Dataset – Dataset with 3 classes of iris plants. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_iris
>>> X, y = load_iris()
>>> X.shape, y.shape
((150, 4), (150,))
load_mushroom() → Dataset[source]#

Load the Mushroom dataset (classification, 8124 samples, 22 features).

Return type:

Dataset

Returns:

Dataset – Dataset with 22 categorical features, stored as integer codes, and two classes: the mushroom is edible (0) or poisonous (1). Missing entries of stalk_root are NaN. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_mushroom
>>> X, y = load_mushroom()
>>> X.shape, y.shape
((8124, 22), (8124,))
load_penguins() → Dataset[source]#

Load the Palmer Penguins dataset (classification, 344 samples, 7 features).

The dataset has missing values, stored as NaN, and two categorical features, stored as integer codes.

Return type:

Dataset

Returns:

Dataset – Dataset with 3 penguin species as classes. Dataset.info holds the license, the source, the citation and the names of the categories.

Examples

>>> from pyml_datasets import load_penguins
>>> data = load_penguins()
>>> data.X.shape, data.y.shape
((344, 7), (344,))
>>> data.has_missing
True
load_real_estate_valuation() → Dataset[source]#

Load the Real Estate Valuation dataset (regression, 414 samples, 6 features).

Return type:

Dataset

Returns:

Dataset – Dataset with the transaction date, the age and the surroundings of a house, and the house price of unit area (10000 New Taiwan Dollar per Ping) as the target. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_real_estate_valuation
>>> X, y = load_real_estate_valuation()
>>> X.shape, y.shape
((414, 6), (414,))
load_superconductivity() → Dataset[source]#

Load the Superconductivity dataset (regression, 21263 samples, 81 features).

Return type:

Dataset

Returns:

Dataset – Dataset with 81 numeric features of a superconductor and its critical temperature as the target. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_superconductivity
>>> X, y = load_superconductivity()
>>> X.shape, y.shape
((21263, 81), (21263,))
load_wine() → Dataset[source]#

Load the Wine dataset (classification, 178 samples, 13 features).

Return type:

Dataset

Returns:

Dataset – Dataset with 3 classes of wine cultivars. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_wine
>>> X, y = load_wine()
>>> X.shape, y.shape
((178, 13), (178,))
load_wine_quality() → Dataset[source]#

Load the Wine Quality dataset (regression, 6497 samples, 11 features).

Return type:

Dataset

Returns:

Dataset – Dataset with physicochemical features and the sensory quality score as target. Dataset.info holds the license, the source and the citation.

Examples

>>> from pyml_datasets import load_wine_quality
>>> X, y = load_wine_quality()
>>> X.shape, y.shape
((6497, 11), (6497,))