dataset_ml/lib.rs
1//! Built-in dataset implementations for machine learning.
2//!
3//! `dataset-ml` provides ready-to-use loaders for classic ML datasets built on top
4//! of [`dataset_core::Dataset`]. Each module is a worked example showing how to wrap
5//! `Dataset<T, E>` for a concrete data source: downloading from a URL, verifying a
6//! SHA-256 hash, parsing CSV records (or extracting raw documents from an archive),
7//! and exposing typed accessors backed by [`ndarray`].
8//!
9//! # Datasets
10//!
11//! | Module | Samples | Features | Task Type |
12//! |-------------------------------------------------------|---------|----------|----------------|
13//! | [`abalone`] | 4,177 | 8 | Regression |
14//! | [`adult`] | 32,561 | 14 | Classification |
15//! | [`bank_marketing`] | 45,211 | 16 | Classification |
16//! | [`iris`] | 150 | 4 | Classification |
17//! | [`breast_cancer`] | 569 | 30 | Classification |
18//! | [`boston_housing`] | 506 | 13 | Regression |
19//! | [`california_housing`] | 20,640 | 8 | Regression |
20//! | [`car_evaluation`] | 1,728 | 6 | Classification |
21//! | [`covtype`] | 581,012 | 54 | Classification |
22//! | [`diabetes`] | 442 | 10 | Regression |
23//! | [`digits`] | 1,797 | 64 | Classification |
24//! | [`heart_disease`] | 303 | 13 | Classification |
25//! | [`ionosphere`] | 351 | 34 | Classification |
26//! | [`kddcup99`] | 494,021 / 4,898,431 | 41 | Classification |
27//! | [`linnerud`] | 20 | 3 | Regression (multi-output) |
28//! | [`mushroom`] | 8,124 | 22 | Classification |
29//! | [`titanic`] | 891 | 11 | Classification |
30//! | [`palmer_penguins`] | 344 | 7 | Classification |
31//! | [`sms_spam`] | 5,574 | text | Classification |
32//! | [`wine_recognition`] | 178 | 13 | Classification |
33//! | [`wine_quality::red_wine_quality`] | 1,599 | 11 | Regression |
34//! | [`wine_quality::white_wine_quality`] | 4,898 | 11 | Regression |
35//! | [`youtube_spam`] | 1,956 | text | Classification |
36//! | [`sentiment_sentences`] | 3,000 | text | Classification |
37//! | [`newsgroups20`] | 11,314 / 18,846 | text | Classification |
38//! | [`movie_review_polarity`] | 2,000 | text | Classification |
39//!
40//! # Example
41//!
42//! ```no_run
43//! use dataset_ml::iris::Iris;
44//!
45//! let iris = Iris::new("./data");
46//! let (features, labels) = iris.data().unwrap();
47//! assert_eq!(features.shape(), &[150, 4]);
48//! ```
49//!
50//! All loaders are lazy: the first call downloads and parses the file, every
51//! subsequent call returns a cached reference. See the individual module docs
52//! for features, target, sample count, and source.
53
54/// Abalone dataset module.
55///
56/// Contains the Abalone dataset (UCI, Nash et al. 1994) for **regression**:
57/// predicting an abalone's `rings` (age in years is `rings + 1.5`) from 8 mixed
58/// (1 categorical `sex` + 7 numeric) physical measurements. Unlike the other
59/// mixed-type loaders (which are classification), its target is an
60/// `Array1<f64>` regression target via `targets()`.
61pub mod abalone;
62
63/// Adult / Census Income dataset module.
64///
65/// Contains the Adult dataset (also called "Census Income") for binary
66/// classification: predicting whether a person earns over $50K/year from 14 mixed
67/// (8 categorical + 6 numeric) demographic and employment features. Extracted from
68/// the 1994 US Census; uses the canonical `adult.data` training partition.
69pub mod adult;
70
71/// Bank Marketing dataset module.
72///
73/// Contains the Bank Marketing dataset for binary classification: predicting
74/// whether a client subscribes a term deposit from 16 mixed (9 categorical +
75/// 7 numeric) client, contact, and campaign features. Recorded from a Portuguese
76/// bank's phone campaigns; uses the full `bank-full.csv` partition. Sourced from a
77/// ZIP archive (like `digits`).
78pub mod bank_marketing;
79
80/// Boston Housing dataset module.
81///
82/// Contains the Boston Housing dataset for predicting median house values
83/// in Boston suburbs based on various features like crime rate, room count,
84/// and accessibility to highways.
85pub mod boston_housing;
86
87/// Breast Cancer Wisconsin (Diagnostic) dataset module.
88///
89/// Contains the Breast Cancer Wisconsin dataset for binary classification of
90/// tumors as malignant or benign based on 30 features computed from digitized
91/// images of cell nuclei.
92pub mod breast_cancer;
93
94/// California Housing dataset module.
95///
96/// Contains the California Housing dataset for predicting median house values
97/// in California districts. Reproduces scikit-learn's `fetch_california_housing`
98/// eight derived features. A modern replacement for Boston Housing.
99pub mod california_housing;
100
101/// Car Evaluation dataset module.
102///
103/// Contains the Car Evaluation dataset (UCI, Bohanec 1988) for multi-class
104/// classification: predicting a car's overall acceptability (`unacc`, `acc`,
105/// `good`, `vgood`) from 6 categorical price and technical attributes. Like
106/// [`mushroom`], it is **all-categorical** — `features()` returns a single
107/// `Array2<String>`.
108pub mod car_evaluation;
109
110/// Forest Cover Type dataset module.
111///
112/// Contains the scikit-learn Forest CoverType dataset (`fetch_covtype`) for
113/// multi-class classification: predicting one of seven forest cover types from 54
114/// cartographic features of 30×30 metre cells. Sourced from a gzip-compressed file,
115/// it is the first loader to decompress its source with `gunzip`.
116pub mod covtype;
117
118/// Diabetes dataset module.
119///
120/// Contains the scikit-learn diabetes dataset (`load_diabetes`) for regression:
121/// predicting disease progression from 10 standardized physiological features.
122pub mod diabetes;
123
124/// Optical Recognition of Handwritten Digits dataset module.
125///
126/// Contains the scikit-learn digits dataset (`load_digits`) for multi-class
127/// classification: recognizing handwritten digits (`0`–`9`) from 8×8 grayscale
128/// images flattened into 64 integer pixel intensities.
129pub mod digits;
130
131/// Heart Disease (Cleveland) dataset module.
132///
133/// Contains the Cleveland Heart Disease dataset (UCI, Janosi et al. 1988) for
134/// classification: predicting the presence of heart disease (`num`, `0`–`4`) from
135/// 13 clinical features. The `?` missing values in `ca`/`thal` are mapped to
136/// `NaN` (like [`titanic`]/[`palmer_penguins`]); the target is an `Array1<u8>`.
137pub mod heart_disease;
138
139/// Ionosphere dataset module.
140///
141/// Contains the Ionosphere dataset (UCI, Sigillito et al. 1989) for binary
142/// classification: predicting whether a radar return shows structure in the
143/// ionosphere (`good`) or passes through it (`bad`) from 34 continuous
144/// autocorrelation features. A compact pure-numeric benchmark like
145/// [`breast_cancer`].
146pub mod ionosphere;
147
148/// Iris flower dataset module.
149///
150/// Contains the classic Iris dataset for classifying iris flowers into
151/// three species (setosa, versicolor, virginica) based on sepal and petal
152/// measurements.
153pub mod iris;
154
155/// KDD Cup 1999 network-intrusion dataset module.
156///
157/// Contains the scikit-learn KDD Cup 1999 dataset (`fetch_kddcup99`) for
158/// multi-class classification: detecting network intrusions from 41 mixed
159/// (3 categorical + 38 numeric) connection features. `Kddcup99::new` loads the
160/// default 10% subset (494,021 samples) and `Kddcup99::new_full` the full set
161/// (4,898,431 samples). Like `covtype`, it is sourced from a gzip-compressed file
162/// and decompressed with `gunzip`.
163pub mod kddcup99;
164
165/// Linnerud dataset module.
166///
167/// Contains the scikit-learn Linnerud dataset (`load_linnerud`) for multi-output
168/// regression: predicting three physiological variables (`Weight`, `Waist`,
169/// `Pulse`) from three exercise variables (`Chins`, `Situps`, `Jumps`) measured
170/// on 20 middle-aged men.
171pub mod linnerud;
172
173/// Movie Review Polarity dataset module.
174///
175/// Contains the Cornell Movie Review Polarity dataset (Pang & Lee 2004, polarity
176/// dataset v2.0) for binary **text** classification: labelling 2,000 full IMDb
177/// movie reviews as `positive` or `negative` (1,000 each). Like [`sms_spam`] it
178/// is a text-modality loader (document accessor `texts()`, not `features()`) and
179/// complements the sentence-level [`sentiment_sentences`] with full-document
180/// reviews. Sourced from a `.tar.gz` archive (decompressed with `untar_gz`).
181pub mod movie_review_polarity;
182
183/// Mushroom dataset module.
184///
185/// Contains the Mushroom dataset (UCI `agaricus-lepiota`) for binary
186/// classification: predicting whether a mushroom is edible or poisonous from 22
187/// categorical attributes. The first **all-categorical** loader — every feature is
188/// a single-letter string code, so `features()` returns a single `Array2<String>`.
189pub mod mushroom;
190
191/// 20 Newsgroups dataset module.
192///
193/// Contains the classic 20 Newsgroups dataset (Lang 1995; the `bydate` version)
194/// for multi-class **text** classification: labelling ~18,846 Usenet posts with
195/// one of 20 newsgroups. The framework-agnostic analogue of scikit-learn's
196/// `fetch_20newsgroups` and the crate's first **multi-class** text loader. Like
197/// [`sms_spam`] it is a text-modality loader (document accessor `texts()`, not
198/// `features()`); `new`/`new_test`/`new_all` mirror scikit-learn's train/test/all
199/// subsets. Sourced from a `.tar.gz` archive (decompressed with `untar_gz`).
200pub mod newsgroups20;
201
202/// Palmer Penguins dataset module.
203///
204/// Contains the Palmer Penguins dataset for classifying penguins into three
205/// species (Adelie, Chinstrap, Gentoo) based on bill and flipper measurements,
206/// body mass, and categorical island/sex features. A modern alternative to Iris.
207pub mod palmer_penguins;
208
209/// Sentiment Labelled Sentences dataset module.
210///
211/// Contains the Sentiment Labelled Sentences dataset (UCI, Kotzias et al. 2015)
212/// for binary **text** classification: labelling 3,000 review sentences from
213/// three sites (Amazon, IMDb, Yelp) as `positive` or `negative`. Like
214/// [`sms_spam`]/[`youtube_spam`] it is a text-modality loader (document accessor
215/// `texts()`, not `features()`), but it also carries per-sample **metadata** —
216/// which site each sentence came from — via a `sources()` accessor, making
217/// `SentimentSentencesData` a `(texts, sources, labels)` triple. Sourced from a
218/// ZIP archive of three per-site files.
219pub mod sentiment_sentences;
220
221/// SMS Spam Collection dataset module.
222///
223/// Contains the SMS Spam Collection dataset (UCI, Almeida & Hidalgo 2011) for
224/// binary **text** classification: labelling 5,574 SMS messages as `ham` or
225/// `spam`. The crate's first text-modality loader — there is no feature matrix,
226/// so the document accessor is `texts()` (an `Array1<String>` of raw messages)
227/// rather than `features()`. Sourced from a ZIP archive.
228pub mod sms_spam;
229
230/// Titanic dataset module.
231///
232/// Contains data about Titanic passengers for predicting survival based
233/// on features like passenger class, sex, age, and fare.
234pub mod titanic;
235
236/// Wine Quality dataset module.
237///
238/// Contains wine quality assessment data for predicting quality scores
239/// based on physicochemical properties like acidity, sugar content, and
240/// alcohol percentage.
241pub mod wine_quality;
242
243/// Wine Recognition dataset module.
244///
245/// Contains the scikit-learn Wine recognition dataset for classifying wines
246/// into three cultivars based on 13 chemical constituents. Distinct from
247/// [`wine_quality`], which is a regression task on quality scores.
248pub mod wine_recognition;
249
250/// YouTube Spam Collection dataset module.
251///
252/// Contains the YouTube Spam Collection dataset (UCI, Alberto, Lochter & Almeida
253/// 2017) for binary **text** classification: labelling 1,956 comments from five
254/// popular music videos as `ham` or `spam`. Like [`sms_spam`] (a sibling by the
255/// same authors) it is a text-modality loader — there is no feature matrix, so
256/// the document accessor is `texts()` (an `Array1<String>` of raw comments)
257/// rather than `features()`. Sourced from a ZIP archive of five per-video CSVs.
258pub mod youtube_spam;
259
260pub use abalone::Abalone;
261pub use adult::Adult;
262pub use bank_marketing::BankMarketing;
263pub use boston_housing::BostonHousing;
264pub use breast_cancer::BreastCancer;
265pub use california_housing::CaliforniaHousing;
266pub use car_evaluation::CarEvaluation;
267pub use covtype::Covtype;
268pub use diabetes::Diabetes;
269pub use digits::Digits;
270pub use heart_disease::HeartDisease;
271pub use ionosphere::Ionosphere;
272pub use iris::Iris;
273pub use kddcup99::Kddcup99;
274pub use linnerud::Linnerud;
275pub use movie_review_polarity::MovieReviewPolarity;
276pub use mushroom::Mushroom;
277pub use newsgroups20::Newsgroups20;
278pub use palmer_penguins::PalmerPenguins;
279pub use sentiment_sentences::SentimentSentences;
280pub use sms_spam::SmsSpam;
281pub use titanic::Titanic;
282pub use wine_quality::{red_wine_quality::RedWineQuality, white_wine_quality::WhiteWineQuality};
283pub use wine_recognition::WineRecognition;
284pub use youtube_spam::YoutubeSpam;