juniper-data 0.4.2__py3-none-any.whl

juniper_data/generators/mnist/generator.py

@@ -0,0 +1,124 @@
+"""MNIST dataset generator using Hugging Face datasets.
+
+This module provides the MnistGenerator class for loading and preprocessing
+MNIST and Fashion-MNIST datasets from the Hugging Face Hub.
+"""
+
+import numpy as np
+
+from juniper_data.core.split import shuffle_and_split
+
+from .params import MnistParams
+
+VERSION = "1.0.0"
+
+try:
+    from datasets import load_dataset as hf_load_dataset
+
+    HF_AVAILABLE = True
+except ImportError:
+    HF_AVAILABLE = False
+    hf_load_dataset = None  # type: ignore[assignment]
+
+
+class MnistGenerator:
+    """Generator for MNIST and Fashion-MNIST datasets.
+
+    Loads datasets from Hugging Face Hub and converts them to the
+    JuniperData format with train/test splits.
+
+    Requires the `datasets` package: pip install datasets
+
+    All methods are static to ensure the generator is stateless and side-effect free.
+    """
+
+    @staticmethod
+    def generate(params: MnistParams) -> dict[str, np.ndarray]:
+        """Generate a complete MNIST dataset with train/test splits.
+
+        Args:
+            params: MnistParams instance defining generation configuration.
+
+        Returns:
+            Dictionary containing:
+                - X_train: Training features
+                - y_train: Training labels
+                - X_test: Test features
+                - y_test: Test labels
+                - X_full: Full dataset features
+                - y_full: Full dataset labels
+
+        Raises:
+            ImportError: If datasets package is not installed.
+        """
+        if not HF_AVAILABLE:
+            raise ImportError("Hugging Face datasets package not installed. Install with: pip install datasets")
+
+        X, y = MnistGenerator._load_and_preprocess(params)
+
+        split_result = shuffle_and_split(
+            X=X,
+            y=y,
+            train_ratio=params.train_ratio,
+            test_ratio=params.test_ratio,
+            seed=params.seed,
+            shuffle=params.shuffle,
+        )
+
+        return {
+            "X_train": split_result["X_train"],
+            "y_train": split_result["y_train"],
+            "X_test": split_result["X_test"],
+            "y_test": split_result["y_test"],
+            "X_full": X,
+            "y_full": y,
+        }
+
+    @staticmethod
+    def _load_and_preprocess(params: MnistParams) -> tuple[np.ndarray, np.ndarray]:
+        """Load dataset from HuggingFace and preprocess.
+
+        Args:
+            params: MnistParams instance.
+
+        Returns:
+            Tuple of (X, y) arrays.
+        """
+        # assert hf_load_dataset is not None
+
+        # params.dataset is validated by MnistParams (Pydantic) as Literal["mnist", "fashion_mnist"],
+        # so this argument to hf_load_dataset is restricted to these known-safe values.
+        ds = hf_load_dataset(params.dataset, split="train")  # nosec B615
+
+        if params.seed is not None:
+            ds = ds.shuffle(seed=params.seed)
+
+        if params.n_samples is not None:
+            ds = ds.select(range(params.n_samples))
+
+        # Use bulk column access with numpy formatting for efficient conversion
+        ds = ds.with_format("numpy")
+        X = np.array(ds["image"])
+        X = X.astype(np.float32) / 255.0 if params.normalize else X.astype(np.float32)
+        if params.flatten:
+            X = X.reshape(len(X), -1)
+
+        labels = np.array(ds["label"])
+        if params.one_hot_labels:
+            n_classes = 10
+
+            y = np.zeros((len(labels), n_classes), dtype=np.float32)
+            y[np.arange(len(labels)), labels] = 1.0
+        else:
+            y = labels.astype(np.float32).reshape(-1, 1)
+
+        return X, y
+
+
+def get_schema() -> dict:
+    """Return JSON schema describing the generator parameters.
+
+    Returns:
+        JSON schema dictionary for MnistParams.
+    """
+    return MnistParams.model_json_schema()

juniper_data/generators/mnist/params.py

@@ -0,0 +1,39 @@
+"""Parameters for the MNIST dataset generator."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class MnistParams(BaseModel):
+    """Configuration parameters for MNIST dataset generation.
+
+    Loads and preprocesses MNIST or Fashion-MNIST datasets from
+    Hugging Face Hub.
+    """
+
+    dataset: Literal["mnist", "fashion_mnist"] = Field(
+        default="mnist",
+        description="Dataset to load: 'mnist' or 'fashion_mnist'",
+    )
+    n_samples: int | None = Field(
+        default=None,
+        ge=1,
+        description="Limit number of samples (None for full dataset)",
+    )
+    flatten: bool = Field(
+        default=True,
+        description="Flatten images to 1D (784 features) or keep 2D (28x28)",
+    )
+    normalize: bool = Field(
+        default=True,
+        description="Normalize pixel values to [0, 1]",
+    )
+    one_hot_labels: bool = Field(
+        default=True,
+        description="One-hot encode labels (10 classes)",
+    )
+    seed: int | None = Field(default=None, ge=0, description="Random seed for reproducibility")
+    train_ratio: float = Field(default=0.8, gt=0, le=1, description="Fraction of data for training")
+    test_ratio: float = Field(default=0.2, ge=0, le=1, description="Fraction of data for testing")
+    shuffle: bool = Field(default=True, description="Shuffle before splitting")

juniper_data/generators/spiral/__init__.py

@@ -0,0 +1,57 @@
+"""Spiral dataset generator module."""
+
+from .defaults import (
+    MAX_NOISE,
+    MAX_POINTS,
+    MAX_ROTATIONS,
+    MAX_SPIRALS,
+    MIN_NOISE,
+    MIN_POINTS,
+    MIN_ROTATIONS,
+    MIN_SPIRALS,
+    SPIRAL_DEFAULT_CLOCKWISE,
+    SPIRAL_DEFAULT_DISTRIBUTION,
+    SPIRAL_DEFAULT_N_POINTS,
+    SPIRAL_DEFAULT_N_ROTATIONS,
+    SPIRAL_DEFAULT_N_SPIRALS,
+    SPIRAL_DEFAULT_NOISE,
+    SPIRAL_DEFAULT_ORIGIN,
+    SPIRAL_DEFAULT_RADIUS,
+    SPIRAL_DEFAULT_RANDOM_VALUE_SCALE,
+    SPIRAL_DEFAULT_SEED,
+    SPIRAL_DEFAULT_TEST_RATIO,
+    SPIRAL_DEFAULT_TRAIN_RATIO,
+)
+from .generator import VERSION, SpiralGenerator, get_schema
+from .params import SpiralParams
+
+__all__ = [
+    # Generator
+    "SpiralGenerator",
+    "get_schema",
+    "VERSION",
+    # Default constants
+    "SPIRAL_DEFAULT_N_SPIRALS",
+    "SPIRAL_DEFAULT_N_POINTS",
+    "SPIRAL_DEFAULT_N_ROTATIONS",
+    "SPIRAL_DEFAULT_CLOCKWISE",
+    "SPIRAL_DEFAULT_DISTRIBUTION",
+    "SPIRAL_DEFAULT_ORIGIN",
+    "SPIRAL_DEFAULT_RADIUS",
+    "SPIRAL_DEFAULT_NOISE",
+    "SPIRAL_DEFAULT_RANDOM_VALUE_SCALE",
+    "SPIRAL_DEFAULT_SEED",
+    "SPIRAL_DEFAULT_TRAIN_RATIO",
+    "SPIRAL_DEFAULT_TEST_RATIO",
+    # Validation bounds
+    "MIN_SPIRALS",
+    "MAX_SPIRALS",
+    "MIN_POINTS",
+    "MAX_POINTS",
+    "MIN_ROTATIONS",
+    "MAX_ROTATIONS",
+    "MIN_NOISE",
+    "MAX_NOISE",
+    # Pydantic model
+    "SpiralParams",
+]

juniper_data/generators/spiral/defaults.py

@@ -0,0 +1,39 @@
+"""Default constants for spiral dataset generation.
+
+This module defines all default constants and validation bounds for the spiral
+dataset generator, migrated from JuniperCascor constants_problem.py.
+"""
+
+# Spiral Geometry Defaults
+SPIRAL_DEFAULT_N_SPIRALS: int = 2
+SPIRAL_DEFAULT_N_POINTS: int = 97
+SPIRAL_DEFAULT_N_ROTATIONS: float = 3.0
+SPIRAL_DEFAULT_CLOCKWISE: bool = True
+SPIRAL_DEFAULT_DISTRIBUTION: float = 0.80
+SPIRAL_DEFAULT_ORIGIN: tuple[float, float] = (0.0, 0.0)
+SPIRAL_DEFAULT_RADIUS: float = 10.0
+
+# Noise & Randomness Defaults
+SPIRAL_DEFAULT_NOISE: float = 0.25
+SPIRAL_DEFAULT_RANDOM_VALUE_SCALE: float = 0.1
+SPIRAL_DEFAULT_SEED: int = 42
+
+# Dataset Splitting Defaults
+SPIRAL_DEFAULT_TRAIN_RATIO: float = 0.8
+SPIRAL_DEFAULT_TEST_RATIO: float = 0.2
+
+# Validation Bounds - Spirals
+MIN_SPIRALS: int = 2
+MAX_SPIRALS: int = 10
+
+# Validation Bounds - Points
+MIN_POINTS: int = 10
+MAX_POINTS: int = 10000
+
+# Validation Bounds - Rotations
+MIN_ROTATIONS: float = 0.5
+MAX_ROTATIONS: float = 10.0
+
+# Validation Bounds - Noise
+MIN_NOISE: float = 0.0
+MAX_NOISE: float = 2.0

juniper_data/generators/spiral/generator.py

@@ -0,0 +1,206 @@
+"""Core NumPy-only spiral dataset generator.
+
+This module provides the SpiralGenerator class for generating multi-spiral
+classification datasets using only NumPy operations.
+"""
+
+from typing import Literal
+
+import numpy as np
+
+from juniper_data.core.split import shuffle_and_split
+
+from .params import SpiralParams
+
+VERSION = "1.0.0"
+
+
+class SpiralGenerator:
+    """NumPy-only generator for multi-spiral classification datasets.
+
+    All methods are static to ensure the generator is stateless and side-effect free.
+    """
+
+    @staticmethod
+    def generate(params: SpiralParams) -> dict[str, np.ndarray]:
+        """Generate a complete spiral dataset with train/test splits.
+
+        Main public API for spiral dataset generation.
+
+        Args:
+            params: SpiralParams instance defining generation configuration.
+
+        Returns:
+            Dictionary containing:
+                - X_train: Training features (n_train, 2)
+                - y_train: Training labels (n_train, n_spirals)
+                - X_test: Test features (n_test, 2)
+                - y_test: Test labels (n_test, n_spirals)
+                - X_full: Full dataset features (total_points, 2)
+                - y_full: Full dataset labels (total_points, n_spirals)
+        """
+        rng = np.random.default_rng(params.seed)
+
+        X, y = SpiralGenerator._generate_raw(params, rng)
+
+        split_result = shuffle_and_split(
+            X=X,
+            y=y,
+            train_ratio=params.train_ratio,
+            test_ratio=params.test_ratio,
+            seed=params.seed,
+            shuffle=params.shuffle,
+        )
+
+        return {
+            "X_train": split_result["X_train"],
+            "y_train": split_result["y_train"],
+            "X_test": split_result["X_test"],
+            "y_test": split_result["y_test"],
+            "X_full": X,
+            "y_full": y,
+        }
+
+    @staticmethod
+    def _generate_raw(params: SpiralParams, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
+        """Generate raw spiral coordinates and labels.
+
+        Args:
+            params: SpiralParams instance defining generation configuration.
+            rng: NumPy random generator for reproducibility.
+
+        Returns:
+            Tuple of (X, y) where:
+                - X: Feature array of shape (total_points, 2)
+                - y: One-hot label array of shape (total_points, n_spirals)
+        """
+        all_coords = []
+
+        for i in range(params.n_spirals):
+            angle_offset = 2 * np.pi * i / params.n_spirals
+            coords = SpiralGenerator._generate_spiral_coordinates(
+                n_points=params.n_points_per_spiral,
+                radius=params.radius,
+                n_rotations=params.n_rotations,
+                angle_offset=angle_offset,
+                clockwise=params.clockwise,
+                noise=params.noise,
+                rng=rng,
+                algorithm=params.algorithm,
+                origin=params.origin,
+            )
+            all_coords.append(coords)
+
+        X = np.vstack(all_coords).astype(np.float32)
+        y = SpiralGenerator._create_one_hot_labels(
+            n_spirals=params.n_spirals,
+            n_points_per_spiral=params.n_points_per_spiral,
+        )
+
+        return X, y
+
+    @staticmethod
+    def _generate_spiral_coordinates(
+        n_points: int,
+        radius: float,
+        n_rotations: float,
+        angle_offset: float,
+        clockwise: bool,
+        noise: float,
+        rng: np.random.Generator,
+        algorithm: Literal["modern", "legacy_cascor"] = "modern",
+        origin: tuple[float, float] = (0.0, 0.0),
+    ) -> np.ndarray:
+        """Generate coordinates for a single spiral arm.
+
+        Args:
+            n_points: Number of points to generate.
+            radius: Maximum radius of the spiral.
+            n_rotations: Number of full rotations.
+            angle_offset: Angular offset for this spiral arm.
+            clockwise: Whether spiral rotates clockwise.
+            noise: Noise level to apply.
+            rng: NumPy random generator.
+            algorithm: Generation algorithm ('modern' or 'legacy_cascor').
+            origin: Origin point (x, y) for spiral center.
+
+        Returns:
+            Array of shape (n_points, 2) containing x, y coordinates.
+        """
+        direction = 1 if clockwise else -1
+
+        if algorithm == "legacy_cascor":
+            distance = np.sqrt(rng.random(n_points)) * radius
+            theta = direction * (distance + angle_offset)
+            x = np.cos(theta) * distance + SpiralGenerator._make_noise_uniform(n_points, noise, rng)
+            y = np.sin(theta) * distance + SpiralGenerator._make_noise_uniform(n_points, noise, rng)
+        else:
+            radii = np.linspace(0, radius, n_points)
+            theta = np.linspace(0, 2 * np.pi * n_rotations, n_points) + angle_offset
+            x = direction * radii * np.cos(theta) + SpiralGenerator._make_noise(n_points, noise, rng)
+            y = direction * radii * np.sin(theta) + SpiralGenerator._make_noise(n_points, noise, rng)
+
+        x += origin[0]
+        y += origin[1]
+
+        return np.column_stack([x, y]).astype(np.float32)
+
+    @staticmethod
+    def _make_noise(n_points: int, noise: float, rng: np.random.Generator) -> np.ndarray:
+        """Generate random noise array using normal distribution.
+
+        Args:
+            n_points: Number of noise values to generate.
+            noise: Noise scale factor.
+            rng: NumPy random generator.
+
+        Returns:
+            Array of shape (n_points,) containing scaled random noise.
+        """
+        return rng.standard_normal(n_points) * noise
+
+    @staticmethod
+    def _make_noise_uniform(n_points: int, noise: float, rng: np.random.Generator) -> np.ndarray:
+        """Generate uniform random noise in [0, noise).
+
+        Args:
+            n_points: Number of noise values to generate.
+            noise: Noise scale factor.
+            rng: NumPy random generator.
+
+        Returns:
+            Array of shape (n_points,) containing uniform random noise.
+        """
+        return rng.random(n_points) * noise
+
+    @staticmethod
+    def _create_one_hot_labels(n_spirals: int, n_points_per_spiral: int) -> np.ndarray:
+        """Create one-hot encoded labels for spiral classes.
+
+        Args:
+            n_spirals: Number of spiral classes.
+            n_points_per_spiral: Number of points per spiral class.
+
+        Returns:
+            Array of shape (total_points, n_spirals) with one-hot encoding.
+        """
+        total_points = n_spirals * n_points_per_spiral
+        y = np.zeros((total_points, n_spirals), dtype=np.float32)
+
+        for i in range(n_spirals):
+            start_idx = i * n_points_per_spiral
+            end_idx = (i + 1) * n_points_per_spiral
+            y[start_idx:end_idx, i] = 1.0
+
+        return y
+
+
+def get_schema() -> dict:
+    """Return JSON schema describing the generator parameters.
+
+    Useful for API documentation and validation.
+
+    Returns:
+        JSON schema dictionary for SpiralParams.
+    """
+    return SpiralParams.model_json_schema()

juniper_data/generators/spiral/params.py

@@ -0,0 +1,148 @@
+"""Spiral dataset generator parameters.
+
+This module defines the Pydantic model for spiral dataset generation parameters
+with validation and computation methods.
+
+Parameter Aliases:
+    Some consumers (JuniperCascor, JuniperCanopy) use different parameter names.
+    This module supports the following aliases:
+    - `n_points` -> `n_points_per_spiral`
+    - `noise_level` -> `noise`
+"""
+
+from typing import Literal
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, model_validator
+
+from .defaults import (
+    MAX_NOISE,
+    MAX_POINTS,
+    MAX_ROTATIONS,
+    MAX_SPIRALS,
+    MIN_NOISE,
+    MIN_POINTS,
+    MIN_ROTATIONS,
+    MIN_SPIRALS,
+    SPIRAL_DEFAULT_CLOCKWISE,
+    SPIRAL_DEFAULT_N_POINTS,
+    SPIRAL_DEFAULT_N_ROTATIONS,
+    SPIRAL_DEFAULT_N_SPIRALS,
+    SPIRAL_DEFAULT_NOISE,
+    SPIRAL_DEFAULT_RADIUS,
+    SPIRAL_DEFAULT_SEED,
+    SPIRAL_DEFAULT_TEST_RATIO,
+    SPIRAL_DEFAULT_TRAIN_RATIO,
+)
+
+PARAMETER_ALIASES: dict[str, str] = {
+    "n_points": "n_points_per_spiral",
+    "noise_level": "noise",
+}
+
+
+class SpiralParams(BaseModel):
+    """Parameters for spiral dataset generation.
+
+    Defines the configuration for generating multi-spiral classification datasets
+    with support for noise, train/test splitting, and deterministic seeding.
+
+    Attributes:
+        n_spirals: Number of spiral arms to generate.
+        n_points_per_spiral: Number of points per spiral arm.
+        n_rotations: Number of full rotations for each spiral.
+        noise: Noise level applied to point positions.
+        clockwise: Whether spirals rotate clockwise.
+        seed: Random seed for reproducibility.
+        train_ratio: Fraction of data for training set.
+        test_ratio: Fraction of data for test set.
+        shuffle: Whether to shuffle the dataset before splitting.
+
+    Parameter Aliases:
+        For compatibility with JuniperCascor and JuniperCanopy:
+        - `n_points` is accepted as an alias for `n_points_per_spiral`
+        - `noise_level` is accepted as an alias for `noise`
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    n_spirals: int = Field(
+        default=SPIRAL_DEFAULT_N_SPIRALS,
+        ge=MIN_SPIRALS,
+        le=MAX_SPIRALS,
+        description="Number of spiral arms to generate",
+    )
+    n_points_per_spiral: int = Field(
+        default=SPIRAL_DEFAULT_N_POINTS,
+        ge=MIN_POINTS,
+        le=MAX_POINTS,
+        description="Number of points per spiral arm",
+        validation_alias=AliasChoices("n_points_per_spiral", "n_points"),
+    )
+    n_rotations: float = Field(
+        default=SPIRAL_DEFAULT_N_ROTATIONS,
+        ge=MIN_ROTATIONS,
+        le=MAX_ROTATIONS,
+        description="Number of full rotations for each spiral",
+    )
+    noise: float = Field(
+        default=SPIRAL_DEFAULT_NOISE,
+        ge=MIN_NOISE,
+        le=MAX_NOISE,
+        description="Noise level applied to point positions",
+        validation_alias=AliasChoices("noise", "noise_level"),
+    )
+    clockwise: bool = Field(
+        default=SPIRAL_DEFAULT_CLOCKWISE,
+        description="Whether spirals rotate clockwise",
+    )
+    seed: int | None = Field(
+        default=SPIRAL_DEFAULT_SEED,
+        description="Random seed for reproducibility",
+    )
+    train_ratio: float = Field(
+        default=SPIRAL_DEFAULT_TRAIN_RATIO,
+        ge=0.0,
+        le=1.0,
+        description="Fraction of data for training set",
+    )
+    test_ratio: float = Field(
+        default=SPIRAL_DEFAULT_TEST_RATIO,
+        ge=0.0,
+        le=1.0,
+        description="Fraction of data for test set",
+    )
+    shuffle: bool = Field(
+        default=True,
+        description="Whether to shuffle the dataset before splitting",
+    )
+    algorithm: Literal["modern", "legacy_cascor"] = Field(
+        default="modern",
+        description="Generation algorithm: 'modern' (linspace+normal noise) or 'legacy_cascor' (sqrt-uniform radii + uniform noise)",
+    )
+    radius: float = Field(
+        default=SPIRAL_DEFAULT_RADIUS,
+        gt=0.0,
+        le=100.0,
+        description="Maximum radius for modern mode, or max distance parameter for legacy mode",
+    )
+    origin: tuple[float, float] = Field(
+        default=(0.0, 0.0),
+        description="Origin point (x, y) for spiral center",
+    )
+
+    @model_validator(mode="after")
+    def validate_ratios_sum(self) -> "SpiralParams":
+        """Validate that train_ratio + test_ratio <= 1.0."""
+        if self.train_ratio + self.test_ratio > 1.0:
+            raise ValueError(
+                f"train_ratio ({self.train_ratio}) + test_ratio ({self.test_ratio}) must be <= 1.0, got {self.train_ratio + self.test_ratio}"
+            )
+        return self
+
+    def total_points(self) -> int:
+        """Compute the total number of points in the dataset.
+
+        Returns:
+            Total number of points (n_spirals * n_points_per_spiral).
+        """
+        return self.n_spirals * self.n_points_per_spiral

juniper_data/generators/xor/__init__.py

@@ -0,0 +1,11 @@
+"""XOR classification dataset generator."""
+
+from juniper_data.generators.xor.generator import VERSION, XorGenerator, get_schema
+from juniper_data.generators.xor.params import XorParams
+
+__all__ = [
+    "XorGenerator",
+    "XorParams",
+    "VERSION",
+    "get_schema",
+]