deepbox/datasets
Built-in & External Datasets
Bundled reference datasets such as Iris and Wine, CSV, text and image loaders that use the network, and Kaggle helpers.
- Data sources
Overview
loadIris(),loadWine(),loadDigits(),loadBreastCancer(),loadDiabetes()andloadLinnerud()are bundled and need no network. Each returns{ data, target, featureNames, targetNames, description }.datafollows the global default dtype (float32), so pass{ dtype: "float64" }to get the exact reference values, as scikit-learn returns them. Classification targets areint32. The page also lists smaller teaching datasets such asloadHousingMiniandloadStudentPerformance.- Remote helpers need network access and throw when the download fails:
fetchCSVDataset,fetchMNIST,fetchCIFAR10,fetch20Newsgroups,fetchIMDBand the Kaggle functions, which read credentials withreadKaggleCredentials.fetch20NewsgroupsandfetchIMDBdownload the official archives (the default timeout is 10 minutes). PassallowSyntheticFallback: trueto get placeholder text instead of an error. fetchCSVDataset({ url, targetColumn })andparseCSV(text)accept numeric CSV only. Every data cell must be a finite number, so text columns and empty cells are rejected. The target is the last column unless you settargetColumn.fetchCSVDatasetstops atmaxBytes(100 MB) andtimeout(30 seconds) by default.
ImageDataset
typeResult of an image dataset fetch.
readonly data: TensorFlattened image tensor of shape
(nSamples, nPixels), dtypefloat32, pixel values scaled to [0, 1].readonly target: TensorClass index tensor of shape
(nSamples,), dtypeint32.readonly nClasses: numberNumber of classes
readonly classNames: string[]Class label names
readonly imageDims: readonly [ number, number, number ]Image dimensions [height, width, channels]
readonly description: stringDataset description
ImageFetchOptions
typeOptions shared by fetchMNIST and fetchCIFAR10.
readonly baseUrl?: stringBase URL override for custom mirrors.
readonly maxSamples?: numberMaximum number of samples to load (positive integer).
readonly split?: "train" | "test"Which split to load: 'train' or 'test'.
readonly signal?: AbortSignalAbort signal forwarded to
fetch.
KaggleCredentials
typeKaggle API credentials.
readonly username: stringKaggle username.
readonly key: stringKaggle API key.
KaggleDatasetInfo
typeMetadata about a Kaggle dataset.
readonly id: stringreadonly title: stringreadonly subtitle: stringreadonly totalBytes: numberreadonly fileCount: numberreadonly lastUpdated: stringreadonly downloadCount: numberreadonly usabilityRating: number
KaggleDownloadResult
typeResult of a Kaggle dataset download.
readonly data: Uint8ArrayRaw file data as Uint8Array (may be a ZIP archive).
readonly filename: stringThe filename.
readonly contentType: stringContent type from the response.
readonly totalBytes: numberNumber of bytes in
data(at mostmaxByteswhen that option is set).
KaggleFetchOptions
typeOptions for fetching a Kaggle dataset.
readonly credentials?: KaggleCredentialsAPI credentials.
readonly file?: stringSpecific file within the dataset to download.
readonly maxBytes?: numberMaximum number of bytes to keep (non-negative integer).
readonly apiBaseUrl?: stringAPI base URL override (mirrors, proxies, tests).
readonly signal?: AbortSignalAbort signal forwarded to
fetch.
Dataset
typeStandard dataset structure returned by all built-in dataset loaders.
data: Tensortarget: TensorfeatureNames: string[]targetNames?: string[]description: stringimages?: Tensor
DatasetLoadOptions
typeOptions accepted by the loaders for the bundled reference datasets (loadIris, loadWine, loadDigits, loadBreastCancer, loadDiabetes and loadLinnerud).
readonly dtype?: "float32" | "float64"Floating-point dtype of
data(and oftargetfor regression datasets).
FetchCSVDatasetOptions
typeOptions for fetchCSVDataset.
readonly url: stringURL of the CSV file to fetch.
readonly targetColumn?: number0-based column index to use as the target variable.
readonly header?: booleanWhether the first row is a header.
readonly separator?: stringSingle-character column separator.
readonly maxBytes?: numberMaximum bytes to download (streaming limit).
readonly timeout?: numberFetch timeout in milliseconds.
readonly abortSignal?: AbortSignalAbortSignal for cancellation.
RemoteDataset
typeResult of a remote dataset fetch.
readonly data: Tensorreadonly target: Tensorreadonly featureNames: string[]readonly targetName: stringreadonly description: string
TextDataset
typeResult of a text dataset fetch.
readonly texts: string[]Array of text documents
readonly target: TensorInteger (
int32) label tensor of shape (nSamples,)readonly nClasses: numberNumber of classes
readonly classNames: string[]Class label names
readonly description: stringDataset description
readonly isSynthetic: booleanWhether this is synthetic/fallback data (true when remote fetch failed)
TextFetchOptions
typeOptions shared by fetch20Newsgroups and fetchIMDB.
readonly subset?: "train" | "test" | "all"Which subset: 'train', 'test', or 'all' (default: 'all')
readonly maxSamples?: numberMaximum number of samples to load (a positive integer).
readonly baseUrl?: stringBase URL of a JSON mirror; the file name is appended to it.
readonly archiveUrl?: stringURL of a gzip-compressed tar archive with the official layout (for example a local mirror of the default archive).
readonly allowSyntheticFallback?: booleanWhen true, return synthetic placeholder data on fetch failure.
readonly timeout?: numberFetch timeout in milliseconds (
0disables the timeout).
fetchCIFAR10
function fetchCIFAR10(options?: ImageFetchOptions): Promise<ImageDataset>;Fetch the CIFAR-10 image classification dataset.
Downloads the binary version from a public mirror and returns images (32×32×3 RGB) with labels across 10 categories. Each row of data keeps the CIFAR channel-major layout (1024 red values, then 1024 green, then 1024 blue).
Parameters
optionsoptionalImageFetchOptions- Configuration options
Returns
Promise<ImageDataset>ImageDataset with CIFAR-10 data (float32 pixels in [0, 1], int32 labels)
Throws
import { fetchCIFAR10 } from 'deepbox/datasets'; const cifar = await fetchCIFAR10();console.log(cifar.data.shape); // [50000, 3072]console.log(cifar.target.shape); // [50000]fetchMNIST
function fetchMNIST(options?: ImageFetchOptions): Promise<ImageDataset>;Fetch the MNIST handwritten digits dataset.
Downloads the dataset from a public mirror and returns 60,000 training images (28×28 grayscale) with labels 0-9.
Parameters
optionsoptionalImageFetchOptions- Configuration options
Returns
Promise<ImageDataset>ImageDataset with MNIST data (float32 pixels in [0, 1], int32 labels)
Throws
import { fetchMNIST } from 'deepbox/datasets'; const mnist = await fetchMNIST();console.log(mnist.data.shape); // [60000, 784]console.log(mnist.target.shape); // [60000]fetchKaggleDataset
function fetchKaggleDataset(datasetId: string, options?: KaggleFetchOptions): Promise<KaggleDownloadResult>;Download a Kaggle dataset or specific file.
Without file the result is the whole dataset as a ZIP archive.
Parameters
datasetIdstring- Dataset identifier in "owner/dataset-name" format
optionsoptionalKaggleFetchOptions- Fetch options
Returns
Promise<KaggleDownloadResult>Download result with raw data
Throws
import { fetchKaggleDataset } from 'deepbox/datasets'; const result = await fetchKaggleDataset('zillow/zecon', { credentials: { username: 'myuser', key: 'mykey' }, file: 'Zip_zhvi_uc_sfrcondo_tier_0.33_0.67_sm_sa_month.csv'});console.log(result.totalBytes);fetchKaggleDatasetInfo
function fetchKaggleDatasetInfo(datasetId: string, options?: KaggleFetchOptions): Promise<KaggleDatasetInfo>;Fetch metadata for a Kaggle dataset.
Parameters
datasetIdstring- Dataset identifier in "owner/dataset-name" format
optionsoptionalKaggleFetchOptions- Fetch options (credentials)
Returns
Promise<KaggleDatasetInfo>Dataset metadata
Throws
import { fetchKaggleDatasetInfo } from 'deepbox/datasets'; const info = await fetchKaggleDatasetInfo('zillow/zecon', { credentials: { username: 'myuser', key: 'mykey' }});console.log(info.title, info.totalBytes);listKaggleFiles
function listKaggleFiles(datasetId: string, options?: KaggleFetchOptions): Promise<{ name: string; totalBytes: number; }[]>;List files in a Kaggle dataset.
Parameters
datasetIdstring- Dataset identifier in "owner/dataset-name" format
optionsoptionalKaggleFetchOptions- Fetch options
Returns
Promise<{ name: string; totalBytes: number; }[]>Array of file names and sizes
Throws
readKaggleCredentials
function readKaggleCredentials(): Promise<KaggleCredentials | undefined>;Read Kaggle credentials.
Looks, in order, at the KAGGLE_USERNAME / KAGGLE_KEY environment variables, then at kaggle.json in $KAGGLE_CONFIG_DIR (if set) or in ~/.kaggle. File access needs Node.js; in browsers the result is undefined.
Returns
Promise<KaggleCredentials | undefined>Credentials if found, undefined otherwise
searchKaggleDatasets
function searchKaggleDatasets(query: string, options?: KaggleFetchOptions): Promise<KaggleDatasetInfo[]>;Search Kaggle datasets.
Parameters
querystring- Search query string
optionsoptionalKaggleFetchOptions- Fetch options (credentials)
Returns
Promise<KaggleDatasetInfo[]>Array of dataset metadata
Throws
loadBreastCancer
function loadBreastCancer(options?: DatasetLoadOptions): Dataset;Load the Breast Cancer Wisconsin (Diagnostic) dataset (UCI).
The real, canonical measurements: 569 samples, 30 features, 2 classes (212 malignant, 357 benign). Deterministic: the committed reference values are always returned unchanged.
Parameters
optionsoptionalDatasetLoadOptions- Optional DatasetLoadOptions (e.g.
{ dtype: "float64" }).
Returns
DatasetA Dataset with data shape [569, 30] and target shape [569] (int32).
Throws
InvalidParameterErrorIfoptions.dtypeis not"float32"or"float64".
loadConcentricRings
function loadConcentricRings(): Dataset;Load the synthetic Concentric Rings classification dataset.
150 samples, 2D, 3 concentric circle classes. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [150, 2] and target shape [150] (int32).
loadCropYield
function loadCropYield(): Dataset;Load the synthetic Crop Yield regression dataset.
200 samples, 3 features (rainfall, fertilizer, temperature), target: yield (tons/ha). Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [200, 3] and target shape [200].
loadCustomerSegments
function loadCustomerSegments(): Dataset;Load the synthetic Customer Segments clustering dataset.
200 samples, 3 features (age, income, spending score), 4 natural clusters. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [200, 3] and target shape [200] (int32).
loadDiabetes
function loadDiabetes(options?: DatasetLoadOptions): Dataset;Load the Diabetes regression dataset (Efron et al., 2004).
The real, canonical data: 442 samples, 10 baseline features (age, sex, BMI, blood pressure, and six blood-serum measurements; each column mean-centered and scaled to unit L2 norm), with a continuous disease-progression target (real values, genuinely correlated with the features). Deterministic: the committed reference values are always returned unchanged.
Parameters
optionsoptionalDatasetLoadOptions- Optional DatasetLoadOptions (e.g.
{ dtype: "float64" }).
Returns
DatasetA Dataset with data shape [442, 10] and target shape [442].
Throws
InvalidParameterErrorIfoptions.dtypeis not"float32"or"float64".
loadDigits
function loadDigits(options?: DatasetLoadOptions): Dataset;Load the Optical Recognition of Handwritten Digits dataset (UCI).
The real, canonical data: 1797 samples, 64 features (8×8 pixels, integer intensities in [0, 16]), 10 classes (digits 0–9). Deterministic: the committed reference values are always returned unchanged.
Parameters
optionsoptionalDatasetLoadOptions- Optional DatasetLoadOptions (e.g.
{ dtype: "float64" }).
Returns
DatasetA Dataset with data shape [1797, 64], target shape [1797] (int32), and images shape [1797, 8, 8] (a view of data).
Throws
InvalidParameterErrorIfoptions.dtypeis not"float32"or"float64".
loadEnergyEfficiency
function loadEnergyEfficiency(): Dataset;Load the synthetic Energy Efficiency regression dataset.
200 samples, 3 features (insulation, window area, orientation), target: energy usage (kWh). Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [200, 3] and target shape [200].
loadFitnessScores
function loadFitnessScores(): Dataset;Load the synthetic Fitness Scores multi-output regression dataset.
100 samples, 3 exercise features, 3 fitness targets (strength, endurance, flexibility). Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [100, 3] and target shape [100, 3].
loadFlowersExtended
function loadFlowersExtended(): Dataset;Load the synthetic Flowers Extended classification dataset.
180 samples, 6 features, 4 species. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [180, 6] and target shape [180] (int32).
loadFruitQuality
function loadFruitQuality(): Dataset;Load the synthetic Fruit Quality classification dataset.
150 samples, 5 features, 3 fruit classes. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [150, 5] and target shape [150] (int32).
loadGaussianIslands
function loadGaussianIslands(): Dataset;Load the synthetic Gaussian Islands classification dataset.
200 samples, 3D, 4 separated Gaussian clusters. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [200, 3] and target shape [200] (int32).
loadHousingMini
function loadHousingMini(): Dataset;Load the synthetic Housing-Mini regression dataset.
200 samples, 4 features (size, rooms, age, distance), target: price (thousands). Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [200, 4] and target shape [200].
loadIris
function loadIris(options?: DatasetLoadOptions): Dataset;Load the Iris dataset (R. A. Fisher, 1936).
The real, canonical measurements: 150 samples, 4 features, 3 classes (50 setosa, 50 versicolor, 50 virginica). Deterministic: the committed reference values are always returned unchanged.
Parameters
optionsoptionalDatasetLoadOptions- Optional DatasetLoadOptions (e.g.
{ dtype: "float64" }).
Returns
DatasetA Dataset with data shape [150, 4] and target shape [150] (int32).
Throws
InvalidParameterErrorIfoptions.dtypeis not"float32"or"float64".
loadLeafShapes
function loadLeafShapes(): Dataset;Load the synthetic Leaf Shapes classification dataset.
150 samples, 8 geometric features, 5 plant species. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [150, 8] and target shape [150] (int32).
loadLinnerud
function loadLinnerud(options?: DatasetLoadOptions): Dataset;Load the Linnerud multi-output regression dataset (Tenenhaus, 1998).
The real, canonical data: 20 middle-aged men, 3 exercise features (chin-ups, sit-ups, jumps) and 3 physiological targets (weight, waist, pulse). Deterministic: the committed reference values are always returned unchanged.
Parameters
optionsoptionalDatasetLoadOptions- Optional DatasetLoadOptions (e.g.
{ dtype: "float64" }).
Returns
DatasetA Dataset with data shape [20, 3] and target shape [20, 3].
Throws
InvalidParameterErrorIfoptions.dtypeis not"float32"or"float64".
loadMoonsMulti
function loadMoonsMulti(): Dataset;Load the synthetic Moons-Multi classification dataset.
150 samples, 2D, 3 interleaving rotated moon classes. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [150, 2] and target shape [150] (int32).
loadPerfectlySeparable
function loadPerfectlySeparable(): Dataset;Load the synthetic Perfectly Separable classification dataset.
100 samples, 4 features, 2 linearly separable classes. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [100, 4] and target shape [100] (int32).
loadPlantGrowth
function loadPlantGrowth(): Dataset;Load the synthetic Plant Growth regression dataset.
200 samples, 3 features (sunlight, water, soil quality), target: height (cm). Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [200, 3] and target shape [200].
loadSeedMorphology
function loadSeedMorphology(): Dataset;Load the synthetic Seed Morphology classification dataset.
150 samples, 4 features, 3 seed types. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [150, 4] and target shape [150] (int32).
loadSensorStates
function loadSensorStates(): Dataset;Load the synthetic Sensor States classification dataset.
180 samples, 6 sensor readings, 3 hidden operating modes. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [180, 6] and target shape [180] (int32).
loadSpiralArms
function loadSpiralArms(): Dataset;Load the synthetic Spiral Arms classification dataset.
150 samples, 2D, 3 spiral classes. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [150, 2] and target shape [150] (int32).
loadStudentPerformance
function loadStudentPerformance(): Dataset;Load the synthetic Student Performance classification dataset.
150 samples, 3 integer features, 3 outcome classes. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [150, 3] and target shape [150] (int32).
loadTrafficConditions
function loadTrafficConditions(): Dataset;Load the synthetic Traffic Conditions classification dataset.
150 samples, 3 features, 3 traffic level classes. Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [150, 3] and target shape [150] (int32).
loadWeatherOutcomes
function loadWeatherOutcomes(): Dataset;Load the synthetic Weather Outcomes multi-output regression dataset.
150 samples, 3 features, 2 targets (rain probability, wind speed). Deterministic: always returns the same data.
Returns
DatasetA Dataset with data shape [150, 3] and target shape [150, 2].
loadWine
function loadWine(options?: DatasetLoadOptions): Dataset;Load the Wine recognition dataset (UCI).
The real, canonical measurements: 178 samples, 13 chemical-analysis features, 3 cultivar classes (59 / 71 / 48). Deterministic: the committed reference values are always returned unchanged.
Parameters
optionsoptionalDatasetLoadOptions- Optional DatasetLoadOptions (e.g.
{ dtype: "float64" }).
Returns
DatasetA Dataset with data shape [178, 13] and target shape [178] (int32).
Throws
InvalidParameterErrorIfoptions.dtypeis not"float32"or"float64".
fetchCSVDataset
function fetchCSVDataset(options: FetchCSVDatasetOptions): Promise<RemoteDataset>;Fetch a CSV dataset from a remote URL and parse it into tensors.
The file must be numeric: every cell has to be a finite decimal number. See parseCSV for the accepted format.
Parameters
optionsFetchCSVDatasetOptions- Fetch configuration
Returns
Promise<RemoteDataset>Parsed remote dataset
Throws
InvalidParameterErrorIf an option is invalidDeepboxErrorIf the request fails, times out, is aborted or exceedsmaxBytesDataValidationErrorIf the CSV is malformed or contains non-numeric or missing values
import { fetchCSVDataset } from 'deepbox/datasets'; const ds = await fetchCSVDataset({ url: 'https://example.com/iris.csv', targetColumn: 4, timeout: 5000, maxBytes: 10 * 1024 * 1024, // 10 MB});console.log(ds.data.shape, ds.target.shape);parseCSV
function parseCSV(text: string, options?: { readonly targetColumn?: number; readonly header?: boolean; readonly separator?: string; }): RemoteDataset;Parse a CSV string into a RemoteDataset.
Details
Supports quoted fields (including embedded separators, line breaks and doubled quotes) and \n, \r\n or \r line endings. Blank lines are skipped. Every data cell must be a finite decimal number (12, -0.5, 1e-3); empty cells, NaN, Infinity, hexadecimal and text are rejected. Every row must have as many cells as the header (or as the first row when header is false).
Exported for testing and for users who already have CSV text.
Parameters
textstring- CSV text
optionsoptional{ readonly targetColumn?: number; readonly header?: boolean; readonly separator?: string; }
Returns
RemoteDatasetThe features, the target column and the column names
Throws
InvalidParameterErrorIf an option is invalid ortargetColumnis out of rangeDataValidationErrorIf the text is empty, a row has the wrong number of cells, or a cell is missing or non-numeric
fetch20Newsgroups
function fetch20Newsgroups(options?: TextFetchOptions): Promise<TextDataset>;Fetch the 20 Newsgroups text classification dataset.
Details
By default the official "bydate" archive (the one scikit-learn downloads, about 14 MB) is fetched from https://ndownloader.figshare.com/files/5975967 and unpacked: 11 314 training and 7 532 test posts in 20 newsgroups. Labels follow the alphabetical order of the newsgroup names; posts are ordered by newsgroup and then by file name, the training split before the test split for subset: 'all', and decoded as ISO-8859-1. Headers, footers and quotes are kept (scikit-learn's remove=()) and nothing is shuffled. With maxSamples the same number of posts is taken from every newsgroup.
Pass archiveUrl to read the same archive from another location. Pass baseUrl to read a JSON mirror instead: <baseUrl>/20newsgroups_<subset>.json, an object with data (array of strings), target (array of integer labels) and target_names (array of class names), of which the first maxSamples documents are kept.
Parameters
optionsoptionalTextFetchOptions- Configuration options
Returns
Promise<TextDataset>TextDataset with newsgroup texts and int32 labels
Throws
InvalidParameterErrorIf an option is invalidDeepboxErrorIf the download fails or the response has the wrong layout, andallowSyntheticFallbackis not set
import { fetch20Newsgroups } from 'deepbox/datasets'; const news = await fetch20Newsgroups({ subset: 'train' });console.log(news.texts.length); // 11314console.log(news.classNames[0]); // 'alt.atheism'fetchIMDB
function fetchIMDB(options?: TextFetchOptions): Promise<TextDataset>;Fetch the IMDB movie review sentiment dataset.
Details
By default the official archive (about 80 MB) is fetched from https://ai.stanford.edu/~amaas/data/sentiment/aclImdb_v1.tar.gz and unpacked: 25 000 training and 25 000 test reviews, half of them negative (label 0) and half positive (label 1). The unlabeled unsup reviews are not read. Reviews are ordered train before test for subset: 'all', negative before positive, then by file name, and decoded as UTF-8 (the HTML line breaks of the original files are kept). With maxSamples the same number of reviews is taken from each class.
Pass archiveUrl to read the same archive from another location. Pass baseUrl to read a JSON mirror instead: <baseUrl>/imdb_<subset>.json, an object with data (array of review strings) and target (array of labels, 0 = negative, 1 = positive), of which the first maxSamples documents are kept.
Parameters
optionsoptionalTextFetchOptions- Configuration options
Returns
Promise<TextDataset>TextDataset with review texts and int32 labels
Throws
InvalidParameterErrorIf an option is invalidDeepboxErrorIf the download fails or the response has the wrong layout, andallowSyntheticFallbackis not set
import { fetchIMDB } from 'deepbox/datasets'; const imdb = await fetchIMDB({ subset: 'train', maxSamples: 1000 });console.log(imdb.texts.length); // 1000console.log(imdb.classNames); // ['negative', 'positive']import { loadDigits, loadIris, parseCSV } from "deepbox/datasets"; const iris = loadIris({ dtype: "float64" });console.log(iris.data.shape, iris.target.shape, iris.target.dtype);console.log(iris.featureNames, iris.targetNames);console.log(loadDigits().data.shape); // parseCSV reads numeric CSV text that you already have.const parsed = parseCSV("x1,x2,label\n1,2,0\n3,4,1");console.log(parsed.data.shape, parsed.target.toString()); // Remote loaders need network access:// const remote = await fetchCSVDataset({ url: "https://example.com/data.csv" });// const news = await fetch20Newsgroups({ subset: "train" });Found a mistake? Open an issue.