deepbox 0.1.0

package/dist/index-D61yaSMY.d.cts

@@ -0,0 +1,483 @@
+import { T as Tensor } from './Tensor-BQLk1ltW.cjs';
+
+type DataLoaderOptions = {
+    batchSize?: number;
+    shuffle?: boolean;
+    dropLast?: boolean;
+    seed?: number;
+};
+/**
+ * Data loader for batching and shuffling datasets.
+ *
+ * Similar to PyTorch's DataLoader. Provides efficient iteration over datasets with support for
+ * batching, shuffling, and deterministic reproducibility.
+ *
+ * @remarks
+ * **Iteration Behavior:**
+ * - Each iteration creates a fresh shuffle (if enabled), so multiple iterations over the same
+ * loader will produce different orderings unless a seed is provided.
+ * - With a seed, all iterations produce identical shuffles (deterministic).
+ * - The underlying tensors are not copied; batches reference the same data via gather operations.
+ *
+ * **Shuffling:**
+ * - Uses Fisher-Yates shuffle algorithm for uniform random permutation.
+ * - When `seed` is provided, shuffling is deterministic and reproducible across runs.
+ * - Shuffle happens per iteration, not per construction.
+ *
+ * @example
+ * ```ts
+ * import { DataLoader } from 'deepbox/datasets';
+ * import { tensor } from 'deepbox/ndarray';
+ *
+ * const X = tensor([[1, 2], [3, 4], [5, 6], [7, 8]]);
+ * const y = tensor([0, 1, 0, 1]);
+ *
+ * // Training loop with shuffling
+ * const loader = new DataLoader(X, y, {
+ * batchSize: 2,
+ * shuffle: true,
+ * seed: 42  // Deterministic shuffling
+ * });
+ *
+ * for (const [xBatch, yBatch] of loader) {
+ * // Train on batch
+ * console.log(xBatch.shape, yBatch.shape);  // [2, 2], [2]
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Inference without labels
+ * const testLoader = new DataLoader(X, undefined, {
+ * batchSize: 4,
+ * shuffle: false
+ * });
+ *
+ * for (const [xBatch] of testLoader) {
+ * // Make predictions
+ * }
+ * ```
+ *
+ * @see {@link https://pytorch.org/docs/stable/data.html#torch.utils.data.DataLoader | PyTorch DataLoader}
+ */
+declare class DataLoader<TTarget extends Tensor | undefined = undefined> {
+    private X;
+    private y;
+    private batchSize;
+    private shuffle;
+    private dropLast;
+    private indices;
+    private seed;
+    private nSamples;
+    constructor(X: Tensor, y: TTarget, options?: DataLoaderOptions);
+    constructor(X: Tensor, options?: DataLoaderOptions);
+    /**
+     * Number of batches in the data loader.
+     */
+    get length(): number;
+    [Symbol.iterator](this: DataLoader<Tensor>): IterableIterator<[Tensor, Tensor]>;
+    [Symbol.iterator](this: DataLoader<undefined>): IterableIterator<[Tensor]>;
+    private prepareIteration;
+    private iterateX;
+    private iterateXY;
+}
+
+/**
+ * Generate a random n-class classification dataset.
+ *
+ * Produces informative features drawn from class-conditional Gaussians,
+ * redundant features as random linear combinations of the informative ones,
+ * and noise features sampled from N(0, 1).
+ *
+ * @param options - Configuration options.
+ * @param options.nSamples - Number of samples (default: 100).
+ * @param options.nFeatures - Total number of features (default: 20).
+ * @param options.nInformative - Number of informative features (default: 2).
+ * @param options.nRedundant - Number of redundant features (default: 2).
+ * @param options.nClasses - Number of classes (default: 2).
+ * @param options.randomState - Seed for reproducibility.
+ * @returns A tuple `[X, y]` where X has shape `[nSamples, nFeatures]` and y has shape `[nSamples]` with dtype `int32`.
+ *
+ * @see {@link https://scikit-learn.org/stable/modules/generated/sklearn.datasets.make_classification.html | sklearn.datasets.make_classification}
+ */
+declare function makeClassification(options?: {
+    nSamples?: number;
+    nFeatures?: number;
+    nInformative?: number;
+    nRedundant?: number;
+    nClasses?: number;
+    randomState?: number;
+}): [Tensor, Tensor];
+/**
+ * Generate a random regression dataset.
+ *
+ * Features are drawn from N(0, 1) and the target is a linear combination
+ * of the features with optional Gaussian noise.
+ *
+ * @param options - Configuration options.
+ * @param options.nSamples - Number of samples (default: 100).
+ * @param options.nFeatures - Number of features (default: 100).
+ * @param options.noise - Standard deviation of Gaussian noise on the target (default: 0).
+ * @param options.randomState - Seed for reproducibility.
+ * @returns A tuple `[X, y]` where X has shape `[nSamples, nFeatures]` and y has shape `[nSamples]`.
+ *
+ * @see {@link https://scikit-learn.org/stable/modules/generated/sklearn.datasets.make_regression.html | sklearn.datasets.make_regression}
+ */
+declare function makeRegression(options?: {
+    nSamples?: number;
+    nFeatures?: number;
+    noise?: number;
+    randomState?: number;
+}): [Tensor, Tensor];
+/**
+ * Generate isotropic Gaussian blobs for clustering.
+ *
+ * Samples are drawn from Gaussian distributions centered at randomly generated
+ * or user-specified locations. Useful for testing clustering algorithms.
+ *
+ * @param options - Configuration options.
+ * @param options.nSamples - Total number of samples (default: 100).
+ * @param options.nFeatures - Number of features per sample (default: 2). Ignored when `centers` is an array.
+ * @param options.centers - Number of cluster centers or explicit center coordinates (default: 3).
+ * @param options.clusterStd - Standard deviation of each cluster (default: 1.0).
+ * @param options.shuffle - Whether to shuffle the samples (default: true).
+ * @param options.randomState - Seed for reproducibility.
+ * @returns A tuple `[X, y]` where X has shape `[nSamples, nFeatures]` and y has shape `[nSamples]` with dtype `int32`.
+ *
+ * @see {@link https://scikit-learn.org/stable/modules/generated/sklearn.datasets.make_blobs.html | sklearn.datasets.make_blobs}
+ */
+declare function makeBlobs(options?: {
+    nSamples?: number;
+    nFeatures?: number;
+    centers?: number | number[][];
+    clusterStd?: number;
+    randomState?: number;
+    shuffle?: boolean;
+}): [Tensor, Tensor];
+/**
+ * Generate two interleaving half-circle (moons) dataset.
+ *
+ * Useful for testing algorithms that handle non-linearly separable data.
+ *
+ * @param options - Configuration options.
+ * @param options.nSamples - Total number of samples, split evenly between the two moons (default: 100).
+ * @param options.noise - Standard deviation of Gaussian noise (default: 0).
+ * @param options.shuffle - Whether to shuffle the samples (default: true).
+ * @param options.randomState - Seed for reproducibility.
+ * @returns A tuple `[X, y]` where X has shape `[nSamples, 2]` and y has shape `[nSamples]` with dtype `int32`.
+ *
+ * @see {@link https://scikit-learn.org/stable/modules/generated/sklearn.datasets.make_moons.html | sklearn.datasets.make_moons}
+ */
+declare function makeMoons(options?: {
+    nSamples?: number;
+    noise?: number;
+    randomState?: number;
+    shuffle?: boolean;
+}): [Tensor, Tensor];
+/**
+ * Generate a large circle containing a smaller circle in 2D.
+ *
+ * Useful for testing algorithms that handle non-linearly separable data.
+ *
+ * @param options - Configuration options.
+ * @param options.nSamples - Total number of samples, split evenly between inner and outer circles (default: 100).
+ * @param options.noise - Standard deviation of Gaussian noise (default: 0).
+ * @param options.factor - Scale factor between inner and outer circle, must be in (0, 1) (default: 0.8).
+ * @param options.shuffle - Whether to shuffle the samples (default: true).
+ * @param options.randomState - Seed for reproducibility.
+ * @returns A tuple `[X, y]` where X has shape `[nSamples, 2]` and y has shape `[nSamples]` with dtype `int32`.
+ *
+ * @see {@link https://scikit-learn.org/stable/modules/generated/sklearn.datasets.make_circles.html | sklearn.datasets.make_circles}
+ */
+declare function makeCircles(options?: {
+    nSamples?: number;
+    noise?: number;
+    factor?: number;
+    randomState?: number;
+    shuffle?: boolean;
+}): [Tensor, Tensor];
+/**
+ * Generate a dataset with classes separated by concentric Gaussian quantile shells.
+ *
+ * Samples are drawn from an isotropic Gaussian and assigned to classes based on
+ * quantile boundaries of their Euclidean distance from the origin.
+ *
+ * @param options - Configuration options.
+ * @param options.nSamples - Number of samples (default: 100).
+ * @param options.nFeatures - Number of features (default: 2).
+ * @param options.nClasses - Number of classes (default: 3).
+ * @param options.randomState - Seed for reproducibility.
+ * @returns A tuple `[X, y]` where X has shape `[nSamples, nFeatures]` and y has shape `[nSamples]` with dtype `int32`.
+ *
+ * @see {@link https://scikit-learn.org/stable/modules/generated/sklearn.datasets.make_gaussian_quantiles.html | sklearn.datasets.make_gaussian_quantiles}
+ */
+declare function makeGaussianQuantiles(options?: {
+    nSamples?: number;
+    nFeatures?: number;
+    nClasses?: number;
+    randomState?: number;
+}): [Tensor, Tensor];
+
+type Dataset = {
+    data: Tensor;
+    target: Tensor;
+    featureNames: string[];
+    targetNames?: string[];
+    description: string;
+};
+/**
+ * Load the synthetic Iris dataset.
+ *
+ * 150 samples, 4 features, 3 classes (setosa, versicolor, virginica).
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[150, 4]` and `target` shape `[150]` (int32).
+ */
+declare function loadIris(): Dataset;
+/**
+ * Load the synthetic Digits dataset.
+ *
+ * 1797 samples, 64 features (8×8 pixel values 0–15), 10 classes (digits 0–9).
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[1797, 64]` and `target` shape `[1797]` (int32).
+ */
+declare function loadDigits(): Dataset;
+/**
+ * Load the synthetic Breast Cancer dataset.
+ *
+ * 569 samples, 30 features, 2 classes (malignant, benign).
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[569, 30]` and `target` shape `[569]` (int32).
+ */
+declare function loadBreastCancer(): Dataset;
+/**
+ * Load the synthetic Diabetes regression dataset.
+ *
+ * 442 samples, 10 features, continuous target.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[442, 10]` and `target` shape `[442]`.
+ */
+declare function loadDiabetes(): Dataset;
+/**
+ * Load the synthetic Linnerud multi-output regression dataset.
+ *
+ * 20 samples, 3 exercise features, 3 physiological targets.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[20, 3]` and `target` shape `[20, 3]`.
+ */
+declare function loadLinnerud(): Dataset;
+/**
+ * Load the synthetic Flowers Extended classification dataset.
+ *
+ * 180 samples, 6 features, 4 species.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[180, 6]` and `target` shape `[180]` (int32).
+ */
+declare function loadFlowersExtended(): Dataset;
+/**
+ * Load the synthetic Leaf Shapes classification dataset.
+ *
+ * 150 samples, 8 geometric features, 5 plant species.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[150, 8]` and `target` shape `[150]` (int32).
+ */
+declare function loadLeafShapes(): Dataset;
+/**
+ * Load the synthetic Fruit Quality classification dataset.
+ *
+ * 150 samples, 5 features, 3 fruit classes.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[150, 5]` and `target` shape `[150]` (int32).
+ */
+declare function loadFruitQuality(): Dataset;
+/**
+ * Load the synthetic Seed Morphology classification dataset.
+ *
+ * 150 samples, 4 features, 3 seed types.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[150, 4]` and `target` shape `[150]` (int32).
+ */
+declare function loadSeedMorphology(): Dataset;
+/**
+ * Load the synthetic Moons-Multi classification dataset.
+ *
+ * 150 samples, 2D, 3 interleaving rotated moon classes.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[150, 2]` and `target` shape `[150]` (int32).
+ */
+declare function loadMoonsMulti(): Dataset;
+/**
+ * Load the synthetic Concentric Rings classification dataset.
+ *
+ * 150 samples, 2D, 3 concentric circle classes.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[150, 2]` and `target` shape `[150]` (int32).
+ */
+declare function loadConcentricRings(): Dataset;
+/**
+ * Load the synthetic Spiral Arms classification dataset.
+ *
+ * 150 samples, 2D, 3 spiral classes.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[150, 2]` and `target` shape `[150]` (int32).
+ */
+declare function loadSpiralArms(): Dataset;
+/**
+ * Load the synthetic Gaussian Islands classification dataset.
+ *
+ * 200 samples, 3D, 4 separated Gaussian clusters.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[200, 3]` and `target` shape `[200]` (int32).
+ */
+declare function loadGaussianIslands(): 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 A {@link Dataset} with `data` shape `[200, 3]` and `target` shape `[200]`.
+ */
+declare function loadPlantGrowth(): 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 A {@link Dataset} with `data` shape `[200, 4]` and `target` shape `[200]`.
+ */
+declare function loadHousingMini(): 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 A {@link Dataset} with `data` shape `[200, 3]` and `target` shape `[200]`.
+ */
+declare function loadEnergyEfficiency(): 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 A {@link Dataset} with `data` shape `[200, 3]` and `target` shape `[200]`.
+ */
+declare function loadCropYield(): 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 A {@link Dataset} with `data` shape `[200, 3]` and `target` shape `[200]` (int32).
+ */
+declare function loadCustomerSegments(): Dataset;
+/**
+ * Load the synthetic Sensor States classification dataset.
+ *
+ * 180 samples, 6 sensor readings, 3 hidden operating modes.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[180, 6]` and `target` shape `[180]` (int32).
+ */
+declare function loadSensorStates(): Dataset;
+/**
+ * Load the synthetic Student Performance classification dataset.
+ *
+ * 150 samples, 3 integer features, 3 outcome classes.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[150, 3]` and `target` shape `[150]` (int32).
+ */
+declare function loadStudentPerformance(): Dataset;
+/**
+ * Load the synthetic Traffic Conditions classification dataset.
+ *
+ * 150 samples, 3 features, 3 traffic level classes.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[150, 3]` and `target` shape `[150]` (int32).
+ */
+declare function loadTrafficConditions(): 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 A {@link Dataset} with `data` shape `[100, 3]` and `target` shape `[100, 3]`.
+ */
+declare function loadFitnessScores(): 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 A {@link Dataset} with `data` shape `[150, 3]` and `target` shape `[150, 2]`.
+ */
+declare function loadWeatherOutcomes(): Dataset;
+/**
+ * Load the synthetic Perfectly Separable classification dataset.
+ *
+ * 100 samples, 4 features, 2 linearly separable classes.
+ * Deterministic — always returns the same data.
+ *
+ * @returns A {@link Dataset} with `data` shape `[100, 4]` and `target` shape `[100]` (int32).
+ */
+declare function loadPerfectlySeparable(): Dataset;
+
+type index_DataLoader<TTarget extends Tensor | undefined = undefined> = DataLoader<TTarget>;
+declare const index_DataLoader: typeof DataLoader;
+type index_DataLoaderOptions = DataLoaderOptions;
+type index_Dataset = Dataset;
+declare const index_loadBreastCancer: typeof loadBreastCancer;
+declare const index_loadConcentricRings: typeof loadConcentricRings;
+declare const index_loadCropYield: typeof loadCropYield;
+declare const index_loadCustomerSegments: typeof loadCustomerSegments;
+declare const index_loadDiabetes: typeof loadDiabetes;
+declare const index_loadDigits: typeof loadDigits;
+declare const index_loadEnergyEfficiency: typeof loadEnergyEfficiency;
+declare const index_loadFitnessScores: typeof loadFitnessScores;
+declare const index_loadFlowersExtended: typeof loadFlowersExtended;
+declare const index_loadFruitQuality: typeof loadFruitQuality;
+declare const index_loadGaussianIslands: typeof loadGaussianIslands;
+declare const index_loadHousingMini: typeof loadHousingMini;
+declare const index_loadIris: typeof loadIris;
+declare const index_loadLeafShapes: typeof loadLeafShapes;
+declare const index_loadLinnerud: typeof loadLinnerud;
+declare const index_loadMoonsMulti: typeof loadMoonsMulti;
+declare const index_loadPerfectlySeparable: typeof loadPerfectlySeparable;
+declare const index_loadPlantGrowth: typeof loadPlantGrowth;
+declare const index_loadSeedMorphology: typeof loadSeedMorphology;
+declare const index_loadSensorStates: typeof loadSensorStates;
+declare const index_loadSpiralArms: typeof loadSpiralArms;
+declare const index_loadStudentPerformance: typeof loadStudentPerformance;
+declare const index_loadTrafficConditions: typeof loadTrafficConditions;
+declare const index_loadWeatherOutcomes: typeof loadWeatherOutcomes;
+declare const index_makeBlobs: typeof makeBlobs;
+declare const index_makeCircles: typeof makeCircles;
+declare const index_makeClassification: typeof makeClassification;
+declare const index_makeGaussianQuantiles: typeof makeGaussianQuantiles;
+declare const index_makeMoons: typeof makeMoons;
+declare const index_makeRegression: typeof makeRegression;
+declare namespace index {
+  export { index_DataLoader as DataLoader, type index_DataLoaderOptions as DataLoaderOptions, type index_Dataset as Dataset, index_loadBreastCancer as loadBreastCancer, index_loadConcentricRings as loadConcentricRings, index_loadCropYield as loadCropYield, index_loadCustomerSegments as loadCustomerSegments, index_loadDiabetes as loadDiabetes, index_loadDigits as loadDigits, index_loadEnergyEfficiency as loadEnergyEfficiency, index_loadFitnessScores as loadFitnessScores, index_loadFlowersExtended as loadFlowersExtended, index_loadFruitQuality as loadFruitQuality, index_loadGaussianIslands as loadGaussianIslands, index_loadHousingMini as loadHousingMini, index_loadIris as loadIris, index_loadLeafShapes as loadLeafShapes, index_loadLinnerud as loadLinnerud, index_loadMoonsMulti as loadMoonsMulti, index_loadPerfectlySeparable as loadPerfectlySeparable, index_loadPlantGrowth as loadPlantGrowth, index_loadSeedMorphology as loadSeedMorphology, index_loadSensorStates as loadSensorStates, index_loadSpiralArms as loadSpiralArms, index_loadStudentPerformance as loadStudentPerformance, index_loadTrafficConditions as loadTrafficConditions, index_loadWeatherOutcomes as loadWeatherOutcomes, index_makeBlobs as makeBlobs, index_makeCircles as makeCircles, index_makeClassification as makeClassification, index_makeGaussianQuantiles as makeGaussianQuantiles, index_makeMoons as makeMoons, index_makeRegression as makeRegression };
+}
+
+export { loadPlantGrowth as A, loadSeedMorphology as B, loadSensorStates as C, type DataLoaderOptions as D, loadSpiralArms as E, loadStudentPerformance as F, loadTrafficConditions as G, loadWeatherOutcomes as H, DataLoader as a, makeCircles as b, makeClassification as c, makeGaussianQuantiles as d, makeMoons as e, makeRegression as f, type Dataset as g, loadConcentricRings as h, index as i, loadCropYield as j, loadCustomerSegments as k, loadBreastCancer as l, makeBlobs as m, loadDiabetes as n, loadDigits as o, loadEnergyEfficiency as p, loadFitnessScores as q, loadFlowersExtended as r, loadFruitQuality as s, loadGaussianIslands as t, loadHousingMini as u, loadIris as v, loadLeafShapes as w, loadLinnerud as x, loadMoonsMulti as y, loadPerfectlySeparable as z };