juniper-data 0.4.2__py3-none-any.whl

juniper_data/generators/circles/generator.py

@@ -0,0 +1,112 @@
+"""Core NumPy-only concentric circles dataset generator.
+
+This module provides the CirclesGenerator class for generating
+concentric circles classification datasets using only NumPy operations.
+"""
+
+import numpy as np
+
+from juniper_data.core.split import shuffle_and_split
+
+from .params import CirclesParams
+
+VERSION = "1.0.0"
+
+
+class CirclesGenerator:
+    """NumPy-only generator for concentric circles classification datasets.
+
+    Generates a binary classification dataset with points distributed on
+    two concentric circles. The outer circle is class 0, and the inner
+    circle is class 1.
+
+    All methods are static to ensure the generator is stateless and side-effect free.
+    """
+
+    @staticmethod
+    def generate(params: CirclesParams) -> dict[str, np.ndarray]:
+        """Generate a complete concentric circles dataset with train/test splits.
+
+        Args:
+            params: CirclesParams instance defining generation configuration.
+
+        Returns:
+            Dictionary containing:
+                - X_train: Training features (n_train, 2)
+                - y_train: Training labels (n_train, 2)
+                - X_test: Test features (n_test, 2)
+                - y_test: Test labels (n_test, 2)
+                - X_full: Full dataset features (n_samples, 2)
+                - y_full: Full dataset labels (n_samples, 2)
+        """
+        rng = np.random.default_rng(params.seed)
+
+        X, y = CirclesGenerator._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: CirclesParams, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
+        """Generate raw concentric circles coordinates and labels.
+
+        Args:
+            params: CirclesParams instance defining generation configuration.
+            rng: NumPy random generator for reproducibility.
+
+        Returns:
+            Tuple of (X, y) where:
+                - X: Feature array of shape (n_samples, 2)
+                - y: One-hot label array of shape (n_samples, 2)
+        """
+        n_inner = int(params.n_samples * params.inner_ratio)
+        n_outer = params.n_samples - n_inner
+
+        inner_radius = params.outer_radius * params.factor
+
+        outer_angles = rng.uniform(0, 2 * np.pi, n_outer)
+        outer_x = params.outer_radius * np.cos(outer_angles)
+        outer_y = params.outer_radius * np.sin(outer_angles)
+        outer_points = np.column_stack([outer_x, outer_y])
+
+        inner_angles = rng.uniform(0, 2 * np.pi, n_inner)
+        inner_x = inner_radius * np.cos(inner_angles)
+        inner_y = inner_radius * np.sin(inner_angles)
+        inner_points = np.column_stack([inner_x, inner_y])
+
+        X = np.vstack([outer_points, inner_points])
+
+        if params.noise > 0:
+            X += rng.standard_normal(X.shape) * params.noise
+
+        X = X.astype(np.float32)
+
+        y = np.zeros((params.n_samples, 2), dtype=np.float32)
+        y[:n_outer, 0] = 1.0
+        y[n_outer:, 1] = 1.0
+
+        return X, y
+
+
+def get_schema() -> dict:
+    """Return JSON schema describing the generator parameters.
+
+    Returns:
+        JSON schema dictionary for CirclesParams.
+    """
+    return CirclesParams.model_json_schema()

juniper_data/generators/circles/params.py

@@ -0,0 +1,31 @@
+"""Parameters for the concentric circles dataset generator."""
+
+from pydantic import BaseModel, Field
+
+
+class CirclesParams(BaseModel):
+    """Configuration parameters for concentric circles dataset generation.
+
+    Generates a binary classification dataset with points on two concentric
+    circles - an inner circle and an outer circle.
+    """
+
+    n_samples: int = Field(default=100, ge=2, description="Total number of samples")
+    outer_radius: float = Field(default=1.0, gt=0, description="Radius of the outer circle")
+    factor: float = Field(
+        default=0.5,
+        gt=0,
+        lt=1,
+        description="Scale factor between inner and outer circles (inner_radius = outer_radius * factor)",
+    )
+    noise: float = Field(default=0.0, ge=0, description="Gaussian noise level added to coordinates")
+    inner_ratio: float = Field(
+        default=0.5,
+        gt=0,
+        le=1,
+        description="Fraction of samples on the inner circle",
+    )
+    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/csv_import/__init__.py

@@ -0,0 +1,15 @@
+"""CSV/JSON import generator for custom datasets."""
+
+from juniper_data.generators.csv_import.generator import (
+    VERSION,
+    CsvImportGenerator,
+    get_schema,
+)
+from juniper_data.generators.csv_import.params import CsvImportParams
+
+__all__ = [
+    "CsvImportGenerator",
+    "CsvImportParams",
+    "VERSION",
+    "get_schema",
+]

juniper_data/generators/csv_import/generator.py

@@ -0,0 +1,198 @@
+"""CSV/JSON import generator for custom datasets.
+
+This module provides the CsvImportGenerator class for loading
+datasets from CSV and JSON files.
+"""
+
+import csv
+import json
+from pathlib import Path
+
+import numpy as np
+
+from juniper_data.core.split import shuffle_and_split
+
+from .params import CsvImportParams
+
+VERSION = "1.0.0"
+
+
+class CsvImportGenerator:
+    """Generator for importing datasets from CSV/JSON files.
+
+    Loads data from local files and converts them to the
+    JuniperData format with train/test splits.
+
+    All methods are static to ensure the generator is stateless and side-effect free.
+    """
+
+    @staticmethod
+    def generate(params: CsvImportParams) -> dict[str, np.ndarray]:
+        """Generate a dataset from a CSV/JSON file with train/test splits.
+
+        Args:
+            params: CsvImportParams instance defining import 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:
+            FileNotFoundError: If the file does not exist.
+            ValueError: If the file format is unsupported.
+        """
+        X, y = CsvImportGenerator._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: CsvImportParams) -> tuple[np.ndarray, np.ndarray]:
+        """Load data from file and preprocess.
+
+        Args:
+            params: CsvImportParams instance.
+
+        Returns:
+            Tuple of (X, y) arrays.
+        """
+
+        ##########################################################################################################################################################################
+        # TODO:  restrict reads to an explicitly configured allowlisted base directory (e.g., JUNIPER_DATA_IMPORT_DIR) and reject absolute paths and path traversal (..) that escape that directory.
+        ##########################################################################################################################################################################
+        path = Path(params.file_path)
+
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {params.file_path}")
+        ##########################################################################################################################################################################
+
+        file_format = params.file_format
+        if file_format == "auto":
+            suffix = path.suffix.lower()
+            if suffix == ".csv":
+                file_format = "csv"
+            elif suffix in {".json", ".jsonl"}:
+                file_format = "json"
+            else:
+                raise ValueError(f"Cannot auto-detect format for extension: {suffix}")
+
+        if file_format == "csv":
+            data = CsvImportGenerator._load_csv(path, params)
+        else:
+            data = CsvImportGenerator._load_json(path, params)
+
+        return CsvImportGenerator._convert_to_arrays(data, params)
+
+    @staticmethod
+    def _load_csv(path: Path, params: CsvImportParams) -> list[dict]:
+        """Load data from CSV file."""
+        data: list[dict] = []
+        with open(path, newline="", encoding="utf-8") as f:
+            if params.header:
+                reader = csv.DictReader(f, delimiter=params.delimiter)
+            else:
+                csv_reader = csv.reader(f, delimiter=params.delimiter)
+                try:
+                    first_row = next(csv_reader)
+                except StopIteration as e:
+                    raise ValueError("CSV file is empty or contains only a header row") from e
+                f.seek(0)
+                fieldnames = [f"col_{i}" for i in range(len(first_row))]
+                reader = csv.DictReader(f, fieldnames=fieldnames, delimiter=params.delimiter)
+
+            data.extend(iter(reader))
+        return data
+
+    @staticmethod
+    def _load_json(path: Path, params: CsvImportParams) -> list[dict]:
+        """Load data from JSON file."""
+        with open(path, encoding="utf-8") as f:
+            content = f.read().strip()
+
+            if content.startswith("["):
+                data = json.loads(content)
+            else:
+                data = [json.loads(line) for line in content.split("\n") if line.strip()]
+
+        return data
+
+    @staticmethod
+    def _convert_to_arrays(data: list[dict], params: CsvImportParams) -> tuple[np.ndarray, np.ndarray]:
+        """Convert loaded data to numpy arrays."""
+        if not data:
+            raise ValueError("No data found in file")
+
+        all_columns = list(data[0].keys())
+
+        if params.feature_columns is not None:
+            feature_cols = params.feature_columns
+        else:
+            feature_cols = [c for c in all_columns if c != params.label_column]
+
+        features = []
+        labels = []
+
+        for row in data:
+            feature_row = []
+            for col in feature_cols:
+                val = row.get(col, 0)
+                try:
+                    feature_row.append(float(val))
+                except (ValueError, TypeError):
+                    feature_row.append(0.0)
+            features.append(feature_row)
+
+            label_val = row.get(params.label_column)
+            labels.append(label_val)
+
+        X = np.array(features, dtype=np.float32)
+
+        if params.normalize_features:
+            X_min = X.min(axis=0, keepdims=True)
+            X_max = X.max(axis=0, keepdims=True)
+            X_range = X_max - X_min
+            X_range[X_range == 0] = 1
+            X = (X - X_min) / X_range
+
+        unique_labels = sorted([str(lbl) for lbl in set(labels)])
+        label_to_idx = {label: idx for idx, label in enumerate(unique_labels)}
+        n_classes = len(unique_labels)
+
+        label_indices = np.array([label_to_idx[str(lbl)] for lbl in labels])
+
+        if params.one_hot_labels:
+            y = np.zeros((len(labels), n_classes), dtype=np.float32)
+            y[np.arange(len(labels)), label_indices] = 1.0
+        else:
+            y = label_indices.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 CsvImportParams.
+    """
+    return CsvImportParams.model_json_schema()

juniper_data/generators/csv_import/params.py

@@ -0,0 +1,48 @@
+"""Parameters for the CSV/JSON import generator."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class CsvImportParams(BaseModel):
+    """Configuration parameters for CSV/JSON data import.
+
+    Loads and preprocesses data from CSV or JSON files.
+    """
+
+    file_path: str = Field(
+        description="Path to the CSV or JSON file to import",
+    )
+    file_format: Literal["csv", "json", "auto"] = Field(
+        default="auto",
+        description="File format: 'csv', 'json', or 'auto' (detect from extension)",
+    )
+    feature_columns: list[str] | None = Field(
+        default=None,
+        description="Column names for features (None = all except label column)",
+    )
+    label_column: str = Field(
+        default="label",
+        description="Column name for labels",
+    )
+    delimiter: str = Field(
+        default=",",
+        description="CSV delimiter character",
+    )
+    header: bool = Field(
+        default=True,
+        description="Whether the file has a header row",
+    )
+    one_hot_labels: bool = Field(
+        default=True,
+        description="One-hot encode labels",
+    )
+    normalize_features: bool = Field(
+        default=False,
+        description="Normalize features to [0, 1]",
+    )
+    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/gaussian/__init__.py

@@ -0,0 +1,11 @@
+"""Gaussian blobs classification dataset generator."""
+
+from juniper_data.generators.gaussian.generator import VERSION, GaussianGenerator, get_schema
+from juniper_data.generators.gaussian.params import GaussianParams
+
+__all__ = [
+    "GaussianGenerator",
+    "GaussianParams",
+    "VERSION",
+    "get_schema",
+]

juniper_data/generators/gaussian/generator.py

@@ -0,0 +1,149 @@
+"""Core NumPy-only Gaussian blobs dataset generator.
+
+This module provides the GaussianGenerator class for generating
+mixture-of-Gaussians classification datasets using only NumPy operations.
+"""
+
+import numpy as np
+
+from juniper_data.core.split import shuffle_and_split
+
+from .params import GaussianParams
+
+VERSION = "1.0.0"
+
+
+class GaussianGenerator:
+    """NumPy-only generator for Gaussian blobs classification datasets.
+
+    Generates a mixture-of-Gaussians dataset with configurable centers,
+    standard deviations, and noise levels. Each class is sampled from
+    a multivariate Gaussian distribution.
+
+    All methods are static to ensure the generator is stateless and side-effect free.
+    """
+
+    @staticmethod
+    def generate(params: GaussianParams) -> dict[str, np.ndarray]:
+        """Generate a complete Gaussian blobs dataset with train/test splits.
+
+        Args:
+            params: GaussianParams instance defining generation configuration.
+
+        Returns:
+            Dictionary containing:
+                - X_train: Training features (n_train, n_features)
+                - y_train: Training labels (n_train, n_classes)
+                - X_test: Test features (n_test, n_features)
+                - y_test: Test labels (n_test, n_classes)
+                - X_full: Full dataset features (total_points, n_features)
+                - y_full: Full dataset labels (total_points, n_classes)
+        """
+        rng = np.random.default_rng(params.seed)
+
+        X, y = GaussianGenerator._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: GaussianParams, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
+        """Generate raw Gaussian blobs coordinates and labels.
+
+        Args:
+            params: GaussianParams instance defining generation configuration.
+            rng: NumPy random generator for reproducibility.
+
+        Returns:
+            Tuple of (X, y) where:
+                - X: Feature array of shape (total_points, n_features)
+                - y: One-hot label array of shape (total_points, n_classes)
+        """
+        centers = GaussianGenerator._get_centers(params, rng)
+        stds = GaussianGenerator._get_stds(params)
+
+        total_points = params.n_classes * params.n_samples_per_class
+        X = np.zeros((total_points, params.n_features), dtype=np.float32)
+        y = np.zeros((total_points, params.n_classes), dtype=np.float32)
+
+        for i in range(params.n_classes):
+            start_idx = i * params.n_samples_per_class
+            end_idx = start_idx + params.n_samples_per_class
+
+            class_std = stds[i] if len(stds) > i else stds[0]
+            samples = rng.standard_normal((params.n_samples_per_class, params.n_features))
+            X[start_idx:end_idx] = samples * class_std + centers[i]
+
+            y[start_idx:end_idx, i] = 1.0
+
+        if params.noise > 0:
+            X += rng.standard_normal(X.shape).astype(np.float32) * params.noise
+
+        return X, y
+
+    @staticmethod
+    def _get_centers(params: GaussianParams, rng: np.random.Generator) -> np.ndarray:
+        """Get or generate class centers.
+
+        Args:
+            params: GaussianParams instance.
+            rng: NumPy random generator (unused if centers provided).
+
+        Returns:
+            Array of shape (n_classes, n_features) containing class centers.
+        """
+        if params.centers is not None:
+            centers = np.array(params.centers, dtype=np.float32)
+            if centers.shape[0] != params.n_classes:
+                raise ValueError(f"Number of centers ({centers.shape[0]}) must match n_classes ({params.n_classes})")
+            if centers.shape[1] != params.n_features:
+                raise ValueError(f"Center dimensions ({centers.shape[1]}) must match n_features ({params.n_features})")
+            return centers
+
+        centers = np.zeros((params.n_classes, params.n_features), dtype=np.float32)
+        angles = np.linspace(0, 2 * np.pi, params.n_classes, endpoint=False)
+
+        for i, angle in enumerate(angles):
+            centers[i, 0] = params.center_radius * np.cos(angle)
+            if params.n_features > 1:
+                centers[i, 1] = params.center_radius * np.sin(angle)
+
+        return centers
+
+    @staticmethod
+    def _get_stds(params: GaussianParams) -> list[float]:
+        """Get standard deviations for each class.
+
+        Args:
+            params: GaussianParams instance.
+
+        Returns:
+            List of standard deviations, one per class.
+        """
+        if isinstance(params.class_std, list):
+            return params.class_std
+        return [params.class_std] * params.n_classes
+
+
+def get_schema() -> dict:
+    """Return JSON schema describing the generator parameters.
+
+    Returns:
+        JSON schema dictionary for GaussianParams.
+    """
+    return GaussianParams.model_json_schema()

juniper_data/generators/gaussian/params.py

@@ -0,0 +1,53 @@
+"""Parameters for the Gaussian blobs dataset generator."""
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class GaussianParams(BaseModel):
+    """Configuration parameters for Gaussian blobs dataset generation.
+
+    Generates a mixture-of-Gaussians classification dataset with configurable
+    class centers, covariance, and noise levels.
+    """
+
+    n_classes: int = Field(default=2, ge=2, le=10, description="Number of classes/blobs")
+    n_samples_per_class: int = Field(default=50, ge=1, description="Number of samples per class")
+    n_features: int = Field(default=2, ge=1, description="Number of features/dimensions")
+    class_std: float | list[float] = Field(
+        default=1.0,
+        description="Standard deviation for each class. Single value applies to all classes.",
+    )
+    centers: list[list[float]] | None = Field(
+        default=None,
+        description="List of class center coordinates. If None, centers are placed on a circle.",
+    )
+    center_radius: float = Field(
+        default=3.0,
+        gt=0,
+        description="Radius for auto-placed centers when centers is None",
+    )
+    noise: float = Field(default=0.0, ge=0, description="Additional Gaussian noise level")
+    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")
+
+    @field_validator("class_std")
+    @classmethod
+    def validate_class_std(cls, v: float | list[float]) -> float | list[float]:
+        """Validate that class_std values are positive."""
+        if isinstance(v, list):
+            if not all(s > 0 for s in v):
+                raise ValueError("All class_std values must be positive")
+        elif v <= 0:
+            raise ValueError("class_std must be positive")
+        return v
+
+    @field_validator("centers")
+    @classmethod
+    def validate_centers(cls, v: list[list[float]] | None) -> list[list[float]] | None:
+        """Validate centers structure if provided."""
+        if v is not None:
+            if len(v) == 0:
+                raise ValueError("centers list cannot be empty")
+        return v

juniper_data/generators/mnist/__init__.py

@@ -0,0 +1,11 @@
+"""MNIST and Fashion-MNIST dataset generator."""
+
+from juniper_data.generators.mnist.generator import VERSION, MnistGenerator, get_schema
+from juniper_data.generators.mnist.params import MnistParams
+
+__all__ = [
+    "MnistGenerator",
+    "MnistParams",
+    "VERSION",
+    "get_schema",
+]