Struct Iris 

pub struct Iris { /* private fields */ }

A struct representing the Iris dataset with lazy loading.

The dataset is not loaded until you call one of the data accessor methods. Once loaded, the data is cached for subsequent accesses.

About Dataset

The Iris dataset is a classic dataset for classification tasks. It includes three iris species with 50 samples each as well as some properties about each flower. One flower species is linearly separable from the other two, but the other two are not linearly separable from each other.

Features:

• sepal length in cm
• sepal width in cm
• petal length in cm
• petal width in cm

Labels:

• species name (in &str): "setosa", "versicolor", "virginica"

See more information at https://archive.ics.uci.edu/dataset/53/iris

Citation

R. A. Fisher. “Iris,” UCI Machine Learning Repository, [Online]. Available: https://doi.org/10.24432/C56C76

Thread Safety

This struct automatically implements Send and Sync (All fields implement them), making it safe to share across threads. The internal Dataset ensures thread-safe lazy initialization.

Example

use dataset_ml::iris::Iris;

let download_dir = "./iris"; // the code will create the directory if it doesn't exist

let mut dataset = Iris::new(download_dir);
let features = dataset.features().unwrap();
let labels = dataset.labels().unwrap();

let (features, labels) = dataset.data().unwrap(); // this is also a way to get features and labels
assert_eq!(features.shape(), &[150, 4]);
assert_eq!(labels.len(), 150);

// `get_data()` borrows the cached arrays without reloading; `get_data_mut()`
// edits them in place — no clone, no reload, the change stays cached. Prefer
// this over cloning with `.to_owned()` when you only need to tweak values.
if let Some((features, labels)) = dataset.get_data_mut() {
    features[[0, 0]] = 5.5;
    labels[0] = "setosa-modified";
}
assert!(dataset.get_data().is_some());

// `take_data()` moves owned arrays out (no `to_owned()` clone) and leaves the
// instance reusable — the next access reloads from the cached file.
let (owned_features, owned_labels) = dataset.take_data().unwrap();
assert_eq!(owned_features.shape(), &[150, 4]);
assert_eq!(owned_labels.len(), 150);

// `into_data()` also returns owned arrays with no clone, but consumes the
// instance (use it when you are done with the dataset).
let (owned_features, owned_labels) = dataset.into_data().unwrap();
assert_eq!(owned_features.shape(), &[150, 4]);
assert_eq!(owned_labels.len(), 150);

Implementations

impl Iris

pub fn new(storage_dir: &str) -> Self

Create a new Iris instance without loading data.

The dataset will be loaded lazily when you first call any data accessor method. This is a lightweight operation that only stores the storage directory.

Parameters

• storage_dir - Directory where the dataset will be stored.

Returns

• Self - Iris instance ready for lazy loading.

pub fn features(&self) -> Result<&Array2<f64>, DatasetError>

Get a reference to the feature matrix.

This method triggers lazy loading on first call. Subsequent calls return the cached data instantly.

Returns

• &Array2<f64> - Reference to feature matrix with shape (150, 4) containing:
  • sepal length in cm
  • sepal width in cm
  • petal length in cm
  • petal width in cm

Errors

Returns DatasetError if:

• Download fails due to network issues
• File extraction or I/O operations fail
• Data format is invalid (wrong number of columns, unparseable values, or invalid labels)
• Dataset size doesn’t match expected dimensions (150 samples, 4 features)

pub fn labels(&self) -> Result<&Array1<&'static str>, DatasetError>

Get a reference to the labels vector.

This method triggers lazy loading on first call. Subsequent calls return the cached data instantly.

Returns

• &Array1<&'static str> - Reference to labels vector with shape (150,) containing species names ("setosa", "versicolor", "virginica")

Errors

Returns DatasetError if:

• Download fails due to network issues
• File extraction or I/O operations fail
• Data format is invalid (wrong number of columns, unparseable values, or invalid labels)
• Dataset size doesn’t match expected dimensions (150 samples)

pub fn data(&self) -> Result<&(Array2<f64>, Array1<&'static str>), DatasetError>

Get both features and labels as references.

This method triggers lazy loading on first call. Subsequent calls return the cached data instantly.

Returns

• &IrisData - reference to the cached (features, labels) tuple: the feature matrix has shape (150, 4) (sepal length/width, petal length/width, all in cm) and the label vector has shape (150,) containing species names ("setosa", "versicolor", "virginica").

Errors

Returns DatasetError if:

• Download fails due to network issues
• File extraction or I/O operations fail
• Data format is invalid (wrong number of columns, unparseable values, or invalid labels)
• Dataset size doesn’t match expected dimensions (150 samples, 4 features)

pub fn get_data(&self) -> Option<&(Array2<f64>, Array1<&'static str>)>

Get both features and labels as references without triggering loading.

Unlike Iris::data, which loads the dataset on first call, this never runs the loader: if the data has not been loaded yet, it returns None instead of downloading and parsing. Use it when you only want the data if it is already cached and want to avoid paying the download/parse cost otherwise.

Returns

• Some(&IrisData) - reference to the cached (features, labels) tuple (feature matrix (150, 4), label vector (150,)), if loaded.
• None - if the dataset has not been loaded yet.

pub fn get_data_mut( &mut self, ) -> Option<&mut (Array2<f64>, Array1<&'static str>)>

Get mutable references to features and labels for in-place editing.

This lets you modify the cached arrays directly (e.g. normalize features, replace label values) with no to_owned() clone and without removing them from the cache: the changes persist, so later Iris::features, Iris::data, or Iris::get_data calls observe them.

Like Iris::get_data, this does not trigger loading: it returns None if the dataset has not been loaded. Call a loading accessor (e.g. Iris::data) first if you need to ensure the data is present.

Returns

• Some(&mut IrisData) - mutable reference to the cached (features, labels) tuple (feature matrix (150, 4), label vector (150,)), if loaded.
• None - if the dataset has not been loaded yet.

pub fn into_data( self, ) -> Result<(Array2<f64>, Array1<&'static str>), DatasetError>

Consume the dataset and return owned features and labels.

Unlike Iris::data, which borrows the cached data, this moves it out and returns owned arrays directly — no to_owned() clone needed. The dataset is loaded on first access if it has not been loaded yet.

This consumes self, so the instance cannot be used afterwards. If you want owned data but need to keep using the instance, use Iris::take_data instead — it takes &mut self and leaves the instance reusable.

Returns

• (Array2<f64>, Array1<&'static str>) - owned feature matrix with shape (150, 4) and owned label vector with shape (150,).

Errors

Returns DatasetError if loading fails (network, file I/O, parsing, invalid labels, or a dimension mismatch).

pub fn take_data( &mut self, ) -> Result<(Array2<f64>, Array1<&'static str>), DatasetError>

Take owned features and labels out of the dataset, leaving it reusable.

Like Iris::into_data, this returns owned arrays with no to_owned() clone. But instead of consuming the instance, it takes &mut self and moves the cached data out, resetting the instance to its unloaded state: the next accessor call (e.g. Iris::features or Iris::data) loads the dataset again.

Use Iris::into_data instead if you are done with the instance.

Returns

• (Array2<f64>, Array1<&'static str>) - owned feature matrix with shape (150, 4) and owned label vector with shape (150,).

Errors

Returns DatasetError if loading fails (network, file I/O, parsing, invalid labels, or a dimension mismatch).

Trait Implementations

impl Debug for Iris

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.