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 list

Prints 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 --offset and --limit choose.

--task {classification,regression}

Show only the datasets of this task.

--name PATTERN

Show only the datasets whose name matches the pattern, like ILIKE in SQL. * (or %, as in SQL) stands for any characters, ? for one character and [abc] for one of the listed characters, so "wine*" starts with wine, "*quality" ends with quality and "*ine*" contains ine. Capital letters do not matter. A pattern without these characters has to match the whole name, as ILIKE '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.

--missing or --no-missing

Show 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.

--reverse

Reverse the order, for example to see the largest dataset first. Datasets with an equal value stay in the order of their names.

--offset N

Skip the first N rows of the ordered list. The default is 0.

--limit N

Show at most N rows. The default is 25. When the table is cut, a line below it says which rows are shown, for example Showing 1-25 of 31., and how to see the rest.

--all

Show every row, without a limit. It cannot be used together with --limit.

When no dataset matches the filters, or --offset is 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 PATH choose the format and the file, see Format and file. The default limit does not cut the JSON.

pyml-datasets show NAME

Prints 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.

--full

Also 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 PATH choose 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}

text is the output for the terminal and the default. md is Markdown: a table for list, and for show sections in the style of NOTICE.md, with the addresses in angle brackets. json is for programs: list gives an array of objects (name, task, license, samples, features and has_missing) and show gives one object with every field of DatasetInfo and also n_samples, n_features, feature_names, target_names and size_bytes. The JSON of list is 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 PATH

Write the result to a file instead of the terminal. Without --format the extension chooses the format: .md, .txt or .json. Another extension needs --format, and a --format that does not fit the extension is an error.

A file is always written in UTF-8, without a byte order mark and with \n at 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.

--force

Overwrite the file of --output if 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

rich or rich-argparse is not installed, so the command cannot start. It prints which package is missing and how to install it, to the standard error stream.

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.