Struct BanknoteAuthentication 

pub struct BanknoteAuthentication { /* private fields */ }

This struct represents the Banknote Authentication dataset and loads it lazily.

Nothing loads until you call a data accessor method. After loading, the data stays cached for later accesses.

About Dataset

Researchers extracted the data from images of genuine and forged banknote-like specimens. They digitized the images with an industrial camera normally used for print inspection. This camera produced 400×400 pixel grayscale images at a resolution of about 660 dpi. Researchers then used a Wavelet Transform tool to extract four continuous statistics from each image. These statistics are the variance, skewness, curtosis, and entropy of the transformed image. Together they form a compact, pure-numeric feature matrix over 1372 specimens.

Feature columns

All 4 features are quantitative, stored in one (1372, 4) Array2<f64> matrix. By 0-based column index:

Column	Attribute	Description
0	variance	variance of the Wavelet-Transformed image
1	skewness	skewness of the Wavelet-Transformed image
2	curtosis	curtosis of the Wavelet-Transformed image
3	entropy	entropy of the image

curtosis keeps the source’s spelling (UCI names the attribute that way) so the schema matches the source exactly.

Labels

• class (shape (1372,)): the Array1<u8> holds the raw integer code from the source (0 or 1). UCI does not document which code corresponds to genuine vs forged notes, so the loader exposes it verbatim.

See more information at https://archive.ics.uci.edu/dataset/267/banknote+authentication.

Citation

V. Lohweg. “Banknote Authentication,” UCI Machine Learning Repository, [Online]. Available: https://doi.org/10.24432/C55P57

Thread Safety

Every field implements Send and Sync, so this struct implements them too. It is safe to share across threads. The internal Dataset makes initialization thread-safe and lazy.

Example

use dataset_ml::banknote_authentication::BanknoteAuthentication;

let download_dir = "./banknote_authentication"; // creates the directory if it is missing

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

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

// `get_data()` borrows the cached arrays without reloading. `get_data_mut()`
// edits them in place. It needs no clone and no reload, and the change
// stays cached. Prefer this method over cloning with `.to_owned()` when
// you only need to change values.
if let Some((features, labels)) = dataset.get_data_mut() {
    features[[0, 0]] = 0.5;
    labels[0] = 1;
}
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(), &[1372, 4]);
assert_eq!(owned_labels.len(), 1372);

// `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(), &[1372, 4]);
assert_eq!(owned_labels.len(), 1372);

Implementations

impl BanknoteAuthentication

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

Create a new BanknoteAuthentication instance without loading data.

This does not load the dataset. The dataset loads on the first call to a data accessor method. This is a lightweight operation: it only stores the storage directory.

Parameters

• storage_dir - Directory used to store the dataset.

Returns

• Self - BanknoteAuthentication 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. Later calls return the cached data instantly.

Returns

• &Array2<f64> - Reference to the numeric feature matrix with shape (1372, 4): the variance, skewness, curtosis, and entropy of each Wavelet-Transformed image.

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 does not match the expected dimensions (1372 samples, 4 features)

pub fn labels(&self) -> Result<&Array1<u8>, DatasetError>

Get a reference to the labels vector.

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

Returns

• &Array1<u8> - Reference to labels vector with shape (1372,) containing the raw class codes (0 or 1).

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 does not match the expected dimensions (1372 samples)

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

Get both features and labels as references.

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

Returns

• &BanknoteAuthenticationData - reference to the cached (features, labels) tuple: the feature matrix has shape (1372, 4) and the label vector has shape (1372,) containing the raw class codes (0 or 1).

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 does not match the expected dimensions (1372 samples, 4 features)

pub fn get_data(&self) -> Option<&(Array2<f64>, Array1<u8>)>

Get both features and labels as references, without triggering loading.

Unlike BanknoteAuthentication::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 this method when you want the data only if it is already cached. This avoids the download and parse cost when the data is not cached.

Returns

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

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

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

This lets you change the cached arrays directly (e.g. normalize features, replace label values). It needs no to_owned() clone, and the arrays stay in the cache. The changes persist, so later calls to BanknoteAuthentication::features, BanknoteAuthentication::data, or BanknoteAuthentication::get_data see them.

Like BanknoteAuthentication::get_data, this does not trigger loading. It returns None if the dataset has not been loaded. If you need to make sure the data is present, call a loading accessor first (e.g. BanknoteAuthentication::data).

Returns

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

pub fn into_data(self) -> Result<(Array2<f64>, Array1<u8>), DatasetError>

Consume the dataset and return owned features and labels.

Unlike BanknoteAuthentication::data, which borrows the cached data, this moves it out and returns owned arrays directly. It needs no to_owned() clone. 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 BanknoteAuthentication::take_data instead. It takes &mut self and leaves the instance reusable.

Returns

• (Array2<f64>, Array1<u8>) - owned feature matrix with shape (1372, 4) and owned label vector with shape (1372,).

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<u8>), DatasetError>

Take owned features and labels out of the dataset. The instance stays reusable.

Like BanknoteAuthentication::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. This resets the instance to its unloaded state. The next accessor call (e.g. BanknoteAuthentication::features or BanknoteAuthentication::data) loads the dataset again.

If you are done with the instance, use BanknoteAuthentication::into_data instead.

Returns

• (Array2<f64>, Array1<u8>) - owned feature matrix with shape (1372, 4) and owned label vector with shape (1372,).

Errors

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

Trait Implementations

impl Debug for BanknoteAuthentication

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

Formats the value using the given formatter.

impl MlDataset for BanknoteAuthentication

const NAME: &'static str = "banknote_authentication"

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

type Data = (ArrayBase<OwnedRepr<f64>, Dim<[usize; 2]>>, ArrayBase<OwnedRepr<u8>, Dim<[usize; 1]>>)

What this loader parses into: the module’s …Data type alias.

fn dataset(&self) -> &Dataset<Self::Data, DatasetError>

Borrow the underlying container.

fn dataset_mut(&mut self) -> &mut Dataset<Self::Data, DatasetError>

Borrow the underlying container mutably.

fn into_dataset(self) -> Dataset<Self::Data, DatasetError>

Consume the loader and return the underlying container.

fn load(&self) -> Result<&Self::Data, DatasetError>

Load the dataset if needed and borrow the parsed data.

fn load_mut(&mut self) -> Result<&mut Self::Data, DatasetError>

Load the dataset if needed and borrow the parsed data mutably.

fn peek(&self) -> Option<&Self::Data>

Borrow the parsed data without triggering loading.

fn unload(&mut self) -> Option<Self::Data>

Move the parsed data out, leaving the loader reusable and unloaded.

fn is_loaded(&self) -> bool

Whether the cache currently holds the data.

fn storage_dir(&self) -> &str

The directory this loader stores its files in.

fn invalidate(&mut self)

Drop the cached data, keeping the loader usable.

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

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