Command line#
The package installs a command, pyml-datasets, that prints the facts about the bundled
datasets, so you can look up a license or a citation without writing any Python. The same
command runs as python -m pyml_datasets.
Note
The output is meant to be read by people and its layout can change in any release. A
program should use list_datasets(), get_info()
and load_dataset() and not parse it.
Commands#
pyml-datasets listPrints a table of the datasets with their task, license, number of samples and number of features. The line below the table counts the datasets that are shown, by task. The options choose the rows and their order. The datasets are filtered first, then ordered, and the table shows the page that
--offsetand--limitchoose.--task {classification,regression}Show only the datasets of this task.
--name PATTERNShow only the datasets whose name matches the pattern, like
ILIKEin SQL.*(or%, as in SQL) stands for any characters,?for one character and[abc]for one of the listed characters, so"wine*"starts withwine,"*quality"ends withqualityand"*ine*"containsine. Capital letters do not matter. A pattern without these characters has to match the whole name, asILIKE 'wine'does, and when a wider pattern would find more datasets, a line below the table suggests it._is an ordinary character, not a wildcard, because the names have it. Put the pattern in quotes: a Unix shell can replace an*that is not quoted with the names of files.--missingor--no-missingShow only the datasets that have, or do not have, missing values. Without either option both kinds are shown.
--sort {name,samples,features}The column to order the rows by. The default is
name.--reverseReverse the order, for example to see the largest dataset first. Datasets with an equal value stay in the order of their names.
--offset NSkip the first
Nrows of the ordered list. The default is 0.--limit NShow at most
Nrows. The default is 25. When the table is cut, a line below it says which rows are shown, for exampleShowing 1-25 of 31., and how to see the rest.--allShow every row, without a limit. It cannot be used together with
--limit.
When no dataset matches the filters, or
--offsetis past the last row, a message says so and the exit code is 0 (the JSON is an empty array).--format {text,md,json}and--output PATHchoose the format and the file, see Format and file. The default limit does not cut the JSON.pyml-datasets show NAMEPrints the facts about one dataset in sections. The header has the title, the task and the license. Overview has the number of samples and features, the class or target names, whether values are missing and the size of the data file. Provenance has the source, the license with the date it was checked, the DOI and the creators, and the addresses are links in terminals that support links. Features lists every feature name, numeric and categorical ones apart, and Citation has the text to cite.
--fullAlso print the changes made to the data and the notes. Without it a line below the report counts them. The notes can hold a warning, for example about a cost matrix or about features that describe people, so read them before you use a dataset. The JSON always has the changes and the notes.
--format {text,md,json}and--output PATHchoose the format and the file, see Format and file.
The examples below are not copied: they are the output of the commands, produced when this documentation is built.
$ pyml-datasets list
Dataset Task License Samples Features
────────────────────────────────────────────────────────────────────────
abalone regression CC-BY-4.0 4177 8
adult classification CC-BY-4.0 48842 14
airfoil_self_noise regression CC-BY-4.0 1503 5
auto_mpg regression CC-BY-4.0 398 7
bank_marketing classification CC-BY-4.0 45211 16
breast_cancer classification CC-BY-4.0 569 30
combined_cycle_power_plant regression CC-BY-4.0 9568 4
concrete_strength regression CC-BY-4.0 1030 8
credit_card_default classification CC-BY-4.0 30000 23
digits classification CC-BY-4.0 1797 64
energy_efficiency regression CC-BY-4.0 768 8
forest_fires regression CC-BY-4.0 517 12
german_credit classification CC-BY-4.0 1000 20
iris classification CC-BY-4.0 150 4
mushroom classification CC-BY-4.0 8124 22
penguins classification CC0-1.0 344 7
real_estate_valuation regression CC-BY-4.0 414 6
superconductivity regression CC-BY-4.0 21263 81
wine classification CC-BY-4.0 178 13
wine_quality regression CC-BY-4.0 6497 11
20 datasets: classification 10, regression 10
The regression datasets, the one with the most samples first:
$ pyml-datasets list --task regression --sort samples --reverse
Dataset Task License Samples Features
────────────────────────────────────────────────────────────────────
superconductivity regression CC-BY-4.0 21263 81
combined_cycle_power_plant regression CC-BY-4.0 9568 4
wine_quality regression CC-BY-4.0 6497 11
abalone regression CC-BY-4.0 4177 8
airfoil_self_noise regression CC-BY-4.0 1503 5
concrete_strength regression CC-BY-4.0 1030 8
energy_efficiency regression CC-BY-4.0 768 8
forest_fires regression CC-BY-4.0 517 12
real_estate_valuation regression CC-BY-4.0 414 6
auto_mpg regression CC-BY-4.0 398 7
10 datasets: regression 10
The datasets whose name starts with wine, and the ones without missing values, two at a
time (the second page):
$ pyml-datasets list --name "wine*"
Dataset Task License Samples Features
──────────────────────────────────────────────────────────
wine classification CC-BY-4.0 178 13
wine_quality regression CC-BY-4.0 6497 11
2 datasets: classification 1, regression 1
$ pyml-datasets list --no-missing --limit 2 --offset 2
Dataset Task License Samples Features
────────────────────────────────────────────────────────────
bank_marketing classification CC-BY-4.0 45211 16
breast_cancer classification CC-BY-4.0 569 30
2 datasets: classification 2
Showing 3-4 of 16. Use --offset or --all to see more.
$ pyml-datasets show iris
Iris classification CC-BY-4.0
────────────────────────────────────────────────────────────────────────────────
Measurements of 150 iris flowers from three species, 50 flowers each: the length
and the width of the sepals and of the petals.
Overview ───────────────────────────────────────────────────────────────────────
Samples 150
Features 4 (all numeric)
Classes setosa, versicolor, virginica
Missing no
File size 4.6 KiB
Provenance ─────────────────────────────────────────────────────────────────────
Source UCI Machine Learning Repository
https://archive.ics.uci.edu/dataset/53/iris
License CC-BY-4.0, checked 2026-10-17
https://creativecommons.org/licenses/by/4.0/
DOI 10.24432/C56C76
Creators R. A. Fisher
Features ───────────────────────────────────────────────────────────────────────
Numeric (4) sepal length (cm), sepal width (cm), petal length (cm), petal
width (cm)
Citation ───────────────────────────────────────────────────────────────────────
Fisher, R. (1936). Iris [Dataset]. UCI Machine Learning Repository.
https://doi.org/10.24432/C56C76
3 changes are not shown. Run with --full to read them.
A dataset with notes, and the changes and the notes in full:
$ pyml-datasets show german_credit
German Credit classification CC-BY-4.0
────────────────────────────────────────────────────────────────────────────────
The Statlog German Credit Data classify people, described by 20 attributes, as
good or bad credit risks. Each of the 1000 samples is a credit applicant
described by 13 categorical and 7 numeric attributes. The source states that the
dataset requires a cost matrix: classifying a bad customer as good is five times
worse than classifying a good customer as bad.
Overview ───────────────────────────────────────────────────────────────────────
Samples 1000
Features 20 (13 categorical, 7 numeric)
Classes good, bad
Missing no
File size 23.2 KiB
Provenance ─────────────────────────────────────────────────────────────────────
Source UCI Machine Learning Repository
https://archive.ics.uci.edu/dataset/144/statlog+german+credit+data
License CC-BY-4.0, checked 2026-11-03
https://creativecommons.org/licenses/by/4.0/
DOI 10.24432/C5NC77
Creators Hans Hofmann
Features ───────────────────────────────────────────────────────────────────────
Numeric (7) duration, credit_amount, installment_rate, residence_since,
age, existing_credits, people_liable
Categorical (13) checking_status, credit_history, purpose, savings,
employment_since, personal_status_sex, other_debtors,
property, other_installment_plans, housing, job, telephone,
foreign_worker
Citation ───────────────────────────────────────────────────────────────────────
Hofmann, H. (1994). Statlog (German Credit Data) [Dataset]. UCI Machine
Learning Repository. https://doi.org/10.24432/C5NC77
4 changes and 5 notes are not shown. Run with --full to read them.
$ pyml-datasets show iris --full
Iris classification CC-BY-4.0
────────────────────────────────────────────────────────────────────────────────
Measurements of 150 iris flowers from three species, 50 flowers each: the length
and the width of the sepals and of the petals.
Overview ───────────────────────────────────────────────────────────────────────
Samples 150
Features 4 (all numeric)
Classes setosa, versicolor, virginica
Missing no
File size 4.6 KiB
Provenance ─────────────────────────────────────────────────────────────────────
Source UCI Machine Learning Repository
https://archive.ics.uci.edu/dataset/53/iris
License CC-BY-4.0, checked 2026-10-17
https://creativecommons.org/licenses/by/4.0/
DOI 10.24432/C56C76
Creators R. A. Fisher
Features ───────────────────────────────────────────────────────────────────────
Numeric (4) sepal length (cm), sepal width (cm), petal length (cm), petal
width (cm)
Citation ───────────────────────────────────────────────────────────────────────
Fisher, R. (1936). Iris [Dataset]. UCI Machine Learning Repository.
https://doi.org/10.24432/C56C76
Changes made to the data ───────────────────────────────────────────────────────
- Converted to the NumPy NPZ format. Values are stored as float64 and the
species as int64 labels (0 = setosa, 1 = versicolor, 2 = virginica).
- Samples 35 and 38 follow Fisher's paper, as corrected in scikit-learn. The
UCI page lists these two samples as differing between its file and the
paper.
- Feature and class names follow scikit-learn.
$ pyml-datasets --help
Usage: pyml-datasets [-h] COMMAND ...
Look up the datasets bundled with pyml-datasets.
Positional Arguments:
COMMAND
list show a table of the datasets
show show the facts about one dataset
Options:
-h, --help show this help message and exit
examples:
pyml-datasets list
pyml-datasets list --task regression --sort samples --reverse
pyml-datasets list --name 'wine*' --no-missing
pyml-datasets list --limit 5 --offset 10
pyml-datasets list --format json
pyml-datasets show iris
pyml-datasets show german_credit --full
pyml-datasets show german_credit --full -o german_credit.md
Both commands only read what is bundled with the package, nothing is downloaded or written.
Format and file#
list and show take the same three options.
--format {text,md,json}textis the output for the terminal and the default.mdis Markdown: a table forlist, and forshowsections in the style ofNOTICE.md, with the addresses in angle brackets.jsonis for programs:listgives an array of objects (name,task,license,samples,featuresandhas_missing) andshowgives one object with every field ofDatasetInfoand alson_samples,n_features,feature_names,target_namesandsize_bytes. The JSON oflistis not cut by the default limit. On the terminal it is plain ASCII, so a console with another code page, such as cp1252 on Windows, still gets valid JSON.--output PATH,-o PATHWrite the result to a file instead of the terminal. Without
--formatthe extension chooses the format:.md,.txtor.json. Another extension needs--format, and a--formatthat does not fit the extension is an error.A file is always written in UTF-8, without a byte order mark and with
\nat the end of every line, whatever the console, the locale and the platform are, so the same command gives the same bytes everywhere. A character is never replaced with?in a file. A text file has no colors and no links and is wrapped at 100 characters, not at the width of the terminal.A name alone is a file in the current directory of the terminal, a relative path is taken from there, and a full path is used as it is.
~is expanded. The directory must exist, it is not created. After the file is written, its full path is printed to the standard error, so the standard output stays clean.-o -means the terminal.--forceOverwrite the file of
--outputif it exists. Without it an existing file is an error, and nothing is written.
$ pyml-datasets show german_credit --full -o german_credit.md
$ pyml-datasets list --format json --task classification -o classification.json
$ pyml-datasets list --format md --name "wine*"
The wrong options (a format that does not fit the extension, a missing directory, a file that exists) end with exit code 2, and a file that cannot be written with exit code 1.
Colors#
The output is colored when it goes to a terminal. It is plain text when it is redirected to
a file or a pipe, so it can be saved or searched without escape codes. The NO_COLOR
environment variable switches the colors off and FORCE_COLOR switches them on, also when
the output is not a terminal.
Exit codes#
Code |
Meaning |
|---|---|
0 |
The command succeeded. |
1 |
A data file is missing from the package or cannot be read. |
2 |
The dataset name is unknown, or the command line is wrong. Errors are printed to the standard error stream. |
3 |
|
Dependencies#
The command uses rich and
rich-argparse. They belong to the optional
cli extra of the package, so install pyml-datasets with it (see Installation) or
install the two packages yourself. They are imported only when the command runs, so
import pyml_datasets does not load them. Without them the command prints which package is
missing and ends with exit code 3.