Struct Digits 

pub struct Digits { /* private fields */ }

A struct that represents the Digits dataset with lazy loading.

The dataset loads only when you call a data accessor method. After the first load, the dataset caches the data for later accesses.

About Dataset

The Optical Recognition of Handwritten Digits dataset contains 8×8 grayscale images of handwritten digits. The source flattens each image into 64 pixel intensities in the range 0..=16. The target is the digit (0–9) that the image shows.

This is the same data scikit-learn exposes through load_digits: it uses the test partition (optdigits.tes) of the UCI archive, with 1797 samples.

Columns

The 64 pixel columns hold the 8×8 image, flattened in row-major order. The name of the pixel of row r and column c is pixel_r_c.

Name	Type	Description
pixel_0_0 … pixel_0_7	Numeric	row 0 pixel intensities (0..=16)
pixel_1_0 … pixel_1_7	Numeric	row 1 pixel intensities (0..=16)
pixel_2_0 … pixel_2_7	Numeric	row 2 pixel intensities (0..=16)
pixel_3_0 … pixel_3_7	Numeric	row 3 pixel intensities (0..=16)
pixel_4_0 … pixel_4_7	Numeric	row 4 pixel intensities (0..=16)
pixel_5_0 … pixel_5_7	Numeric	row 5 pixel intensities (0..=16)
pixel_6_0 … pixel_6_7	Numeric	row 6 pixel intensities (0..=16)
pixel_7_0 … pixel_7_7	Numeric	row 7 pixel intensities (0..=16)
digit	Integer	the handwritten digit, 0–9

The source designates the 64 pixel columns as the inputs (Digits::FEATURE_NAMES) and digit as the label (Digits::TARGET).

Missing values: none.

See more information at https://archive.ics.uci.edu/dataset/80/optical+recognition+of+handwritten+digits

Citation

E. Alpaydin and C. Kaynak. “Optical Recognition of Handwritten Digits,” UCI Machine Learning Repository, [Online]. Available: https://doi.org/10.24432/C50P49

Thread Safety

This struct implements Send and Sync automatically, because all fields implement them. This makes the struct safe to share across threads. The internal Dataset makes lazy initialization thread-safe.

Example

use dataset_ml::Digits;

let download_dir = "./digits"; // the loader creates the directory if it does not exist

let mut dataset = Digits::new(download_dir);
let table = dataset.data().unwrap();

assert_eq!(table.n_samples(), 1797);
assert_eq!(table.n_columns(), 65);

// Ask for the feature matrix when you want it.
let features = table.numeric_matrix(&Digits::FEATURE_NAMES).unwrap();
assert_eq!(features.shape(), &[1797, 64]);

// Reach one column by name.
let digit = table.column(Digits::TARGET).unwrap().as_integer().unwrap();
assert_eq!(digit.len(), 1797);

// `get_data_mut()` edits the table in place. This needs no clone and no
// reload. The change stays cached.
if let Some(table) = dataset.get_data_mut() {
    if let Some(column) = table.column_mut("pixel_0_0") {
        if let dataset_ml::ColumnData::Numeric(values) = column.data_mut() {
            values[0] = 5.0;
        }
    }
}
assert!(dataset.get_data().is_some());

// `take_data()` moves the owned table out with no clone. This leaves the
// instance reusable.
let owned = dataset.take_data().unwrap();
assert_eq!(owned.n_samples(), 1797);

// `into_data()` also returns the owned table with no clone, but it consumes
// the instance.
let owned = dataset.into_data().unwrap();
assert_eq!(owned.n_samples(), 1797);

Implementations

impl Digits

pub const FEATURE_NAMES: [&'static str; 64]

The columns the source designates as the model inputs, in source order. The name of the pixel of row r and column c of the 8×8 image is pixel_r_c.

pub const TARGET: &'static str = "digit"

The column the source designates as the label.

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

Create a new Digits instance without loading data.

The dataset loads lazily, on your first call to a data accessor method. This is a lightweight operation that only stores the storage directory.

Parameters

• storage_dir - The directory that stores the dataset.

Returns

• Self - a Digits instance ready for lazy loading.

pub fn data(&self) -> Result<&Table, DatasetError>

Get a reference to the parsed table.

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

Returns

• &Table - reference to the cached table of 1797 samples and 65 columns.

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)

pub fn get_data(&self) -> Option<&Table>

Get a reference to the parsed table without triggering loading.

Unlike Digits::data, this method never runs the loader. If the data has not loaded yet, it returns None instead of downloading and parsing it.

Returns

• Some(&Table) - reference to the cached table, if loaded.
• None - if the dataset has not loaded yet.

pub fn get_data_mut(&mut self) -> Option<&mut Table>

Get a mutable reference to the parsed table for in-place editing.

This needs no clone, and it does not remove the data from the cache. The changes stay in the cache. Later calls to Digits::data or Digits::get_data see them.

Like Digits::get_data, this does not trigger loading.

Returns

• Some(&mut Table) - mutable reference to the cached table, if loaded.
• None - if the dataset has not loaded yet.

pub fn into_data(self) -> Result<Table, DatasetError>

Consume the dataset and return the owned table.

This consumes self. If you want owned data but need to keep using the instance, use Digits::take_data instead.

Returns

• Table - the owned table of 1797 samples and 65 columns.

Errors

Returns DatasetError if loading fails (network, file I/O, or parsing).

pub fn take_data(&mut self) -> Result<Table, DatasetError>

Take the owned table out of the dataset. This leaves the instance reusable.

This resets the instance to its unloaded state. The next accessor call loads the dataset again.

Returns

• Table - the owned table of 1797 samples and 65 columns.

Errors

Returns DatasetError if loading fails (network, file I/O, or parsing).

Trait Implementations

impl Debug for Digits

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

Formats the value using the given formatter.

impl MlDataset for Digits

const NAME: &'static str = "digits"

The dataset’s identifier, matching the one used in its error messages (for example, "iris", "sms_spam").

fn dataset(&self) -> &Dataset<Table, DatasetError>

Borrow the underlying container.

fn dataset_mut(&mut self) -> &mut Dataset<Table, DatasetError>

Borrow the underlying container mutably.

fn into_dataset(self) -> Dataset<Table, DatasetError>

Consume the loader and return the underlying container.

fn load(&self) -> Result<&Table, DatasetError>

Load the dataset if needed and borrow the table.

fn load_mut(&mut self) -> Result<&mut Table, DatasetError>

Load the dataset if needed and borrow the table mutably.

fn peek(&self) -> Option<&Table>

Borrow the table without triggering loading.

fn unload(&mut self) -> Option<Table>

Move the table out, leaving the loader reusable and unloaded.

fn is_loaded(&self) -> bool

Whether the cache currently holds the table.

fn storage_dir(&self) -> &str

The directory this loader stores its files in.

fn invalidate(&mut self)

Drop the cached table, keeping the loader usable.

fn n_samples(&self) -> Result<usize, DatasetError>

The number of samples in the dataset, loading it if needed.