# dataset-ml
Ready-to-use loaders for classic machine learning datasets, built on [`dataset-core`](https://crates.io/crates/dataset-core).
[](https://www.rust-lang.org/)
[](https://opensource.org/licenses/MIT)
[](https://crates.io/crates/dataset-ml)
## Overview
`dataset-ml` ships with loaders for ten classic ML datasets. Each loader:
- Downloads the source file on first access (with `ureq`).
- Verifies a pinned SHA-256 hash to detect corruption or upstream changes.
- Parses the CSV into [`ndarray`](https://crates.io/crates/ndarray) `Array1` / `Array2`.
- Caches the parsed result in memory via `dataset_core::Dataset<T, E>` — subsequent accesses return a `&` reference with zero I/O.
Each module is also a complete reference implementation of the pattern for wrapping `Dataset<T, E>` for a concrete data source.
## Installation
```toml
[dependencies]
dataset-ml = "0.2"
```
## Datasets
| `Iris` | `dataset_ml::iris` | 150 | 4 | Classification | UCI ML Repository |
| `BreastCancer` | `dataset_ml::breast_cancer` | 569 | 30 | Classification | UCI ML Repository |
| `BostonHousing` | `dataset_ml::boston_housing` | 506 | 13 | Regression | UCI ML Repository |
| `CaliforniaHousing` | `dataset_ml::california_housing` | 20,640 | 8 | Regression | StatLib (1990 census) |
| `Diabetes` | `dataset_ml::diabetes` | 768 | 8 | Classification | Kaggle |
| `Titanic` | `dataset_ml::titanic` | 891 | 11 | Classification | Kaggle |
| `PalmerPenguins` | `dataset_ml::palmer_penguins` | 344 | 7 | Classification | palmerpenguins |
| `WineRecognition` | `dataset_ml::wine_recognition` | 178 | 13 | Classification | UCI ML Repository |
| `RedWineQuality` | `dataset_ml::wine_quality::red_wine_quality` | 1,599 | 11 | Regression | UCI ML Repository |
| `WhiteWineQuality` | `dataset_ml::wine_quality::white_wine_quality` | 4,898 | 11 | Regression | UCI ML Repository |
All structs are also re-exported at the crate root, so `dataset_ml::Iris`, `dataset_ml::RedWineQuality`, etc. work too.
## Usage
```rust
use dataset_ml::iris::Iris;
fn main() {
let iris = Iris::new("./data");
// Lazy: downloads and parses on first access, then cached.
let features = iris.features().unwrap(); // &Array2<f64>
let labels = iris.labels().unwrap(); // &Array1<String>
// Or get both at once:
let (features, labels) = iris.data().unwrap();
assert_eq!(features.shape(), &[150, 4]);
assert_eq!(labels.len(), 150);
// Call .to_owned() when you need a mutable copy.
let mut owned = features.to_owned();
owned[[0, 0]] = 5.5;
}
```
Each dataset struct follows the same pattern:
- `new(storage_dir)` — create instance (no I/O)
- `features()` — reference to feature matrix
- `labels()` / `targets()` — reference to label/target vector
- `data()` — all references at once
> **Note**: Titanic and Palmer Penguins are mixed-type: `features()` returns `(&Array2<String>, &Array2<f64>)` (string + numeric features), and `data()` returns a triple. Palmer Penguins also represents missing values as `NaN` (numeric) or `""` (string).
>
> **Note**: California Housing reproduces scikit-learn's `fetch_california_housing` features by deriving them from the raw census columns (e.g. `AveRooms = total_rooms / households`) and scaling the target by `1/100000`. Its 207 missing `total_bedrooms` values surface as `NaN` in `AveBedrms`.
## Migration from `dataset-core` 0.1.x
If you used the `datasets` feature of `dataset-core` 0.1.x, switch to this crate:
```diff
- dataset-core = { version = "0.1", features = ["datasets"] }
+ dataset-ml = "0.2"
```
| Old path | New path |
|------------------------------------------------------------------------------|------------------------------------------------------------------|
| `dataset_core::datasets::iris::Iris` | `dataset_ml::iris::Iris` |
| `dataset_core::datasets::boston_housing::BostonHousing` | `dataset_ml::boston_housing::BostonHousing` |
| `dataset_core::datasets::diabetes::Diabetes` | `dataset_ml::diabetes::Diabetes` |
| `dataset_core::datasets::titanic::Titanic` | `dataset_ml::titanic::Titanic` |
| `dataset_core::datasets::wine_quality::red_wine_quality::RedWineQuality` | `dataset_ml::wine_quality::red_wine_quality::RedWineQuality` |
| `dataset_core::datasets::wine_quality::white_wine_quality::WhiteWineQuality` | `dataset_ml::wine_quality::white_wine_quality::WhiteWineQuality` |
`dataset_core::utils::*` and `dataset_core::DatasetError` are unchanged — they remain in [`dataset-core`](https://crates.io/crates/dataset-core) under the `utils` feature.
## Performance Considerations
- **First access**: downloads the file (if not on disk), validates SHA-256, parses, caches in memory.
- **Subsequent accesses**: return a reference to the cached data — zero allocation, zero I/O.
- **`.to_owned()`**: clones cached data into a new owned value — use only when mutation is needed.
- **Offline**: once downloaded, datasets stay on disk; no network needed on subsequent runs.
## License
This project is licensed under the MIT License — see [LICENSE](../../LICENSE) for details.
## Datasets Attribution
The bundled datasets are classic machine learning datasets widely used for educational and research purposes:
- **Iris**: Fisher's Iris dataset (1936)
- **Breast Cancer Wisconsin (Diagnostic)**: Wolberg, Mangasarian, Street & Street (1995)
- **Boston Housing**: Harrison & Rubinfeld (1978)
- **California Housing**: Pace & Barry (1997), from the 1990 U.S. census
- **Diabetes**: Pima Indians Diabetes Database
- **Titanic**: Kaggle Titanic dataset
- **Palmer Penguins**: Horst, Hill & Gorman (2020); data by Gorman, Williams & Fraser (2014)
- **Wine Recognition**: Aeberhard & Forina (1991), UCI Machine Learning Repository
- **Wine Quality**: UCI Machine Learning Repository
## Author
**SomeB1oody** — [stanyin64@gmail.com](mailto:stanyin64@gmail.com)