separatix 0.1.0a1__tar.gz

separatix-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

separatix-0.1.0a1/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: separatix
+Version: 0.1.0a1
+Summary: Diagnostic profiling of labeled embeddings for classification model complexity guidance.
+License: MIT
+License-File: LICENSE
+Author: Niklas Melton
+Author-email: niklas@example.com
+Requires-Python: >=3.9,<3.15
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: examples
+Provides-Extra: pandas
+Provides-Extra: tda
+Requires-Dist: matplotlib (>=3.6) ; extra == "examples"
+Requires-Dist: numpy (>=1.23)
+Requires-Dist: pandas (>=1.5) ; extra == "pandas" or extra == "examples"
+Requires-Dist: ripser (>=0.6) ; extra == "tda"
+Requires-Dist: scikit-learn (>=1.2)
+Requires-Dist: scipy (>=1.9)
+Description-Content-Type: text/markdown
+
+[![separatix logo](https://raw.githubusercontent.com/NiklasMelton/Separatix/develop/img/separatix_logo.png)](https://github.com/NiklasMelton/Separatix)
+
+# separatix
+
+`separatix` profiles labeled feature spaces before classifier training and
+returns transparent, confidence-aware guidance about apparent classification
+complexity.
+
+The intended use case includes learned embeddings, but the package is not
+restricted to embeddings. It also works on raw feature matrices when you want a
+coarse diagnostic of whether the observed class geometry looks mostly linear,
+smoothly nonlinear, local or kernel-like, fragmented, bottlenecked, or too
+unreliable to trust.
+
+`separatix` does not claim to pick the optimal classifier. It is a pretraining
+diagnostic and auditing tool designed to make its reasoning visible.
+
+## Installation
+
+```bash
+pip install separatix
+```
+
+To install the latest development version directly from GitHub:
+
+```bash
+pip install "git+https://github.com/NiklasMelton/Separatix.git@develop"
+```
+
+## Quick start
+
+```python
+from separatix import diagnose
+
+recommendation = diagnose(X, y, random_state=0)
+print(recommendation)
+```
+
+For a structured audit:
+
+```python
+from separatix import diagnose
+
+report = diagnose(X, y, return_report=True, random_state=0)
+print(report.recommendation_text)
+print(report.decision_path)
+print(report.scores)
+print(report.to_json())
+```
+
+## What It Accepts
+
+- Dense NumPy arrays
+- SciPy sparse matrices
+- pandas DataFrames and Series when pandas is installed
+- Binary and multiclass classification targets
+- String or numeric labels treated as categorical class identifiers
+
+Regression, multilabel classification, and multioutput classification are not
+supported.
+
+## What It Returns
+
+By default, `diagnose(...)` returns a plain-text recommendation. With
+`return_report=True`, it returns a `DiagnosticReport` that includes:
+
+- the recommendation label
+- plain-text recommendation text
+- confidence level
+- underlying metric groups
+- normalized summary scores
+- a visible decision path
+- warnings and skipped diagnostics
+- sampling and densification events
+- preprocessing and runtime metadata
+
+The report is JSON-serializable through `report.to_dict()` and `report.to_json()`.
+
+## Recommendation Categories
+
+- `linear_likely_sufficient`
+- `smooth_nonlinear_recommended`
+- `kernel_or_local_recommended`
+- `high_capacity_or_partitioning_recommended`
+- `feature_or_label_bottleneck_likely`
+- `insufficient_data_or_unreliable_geometry`
+- `inconclusive`
+
+These categories are intentionally coarse. They describe the apparent geometry
+and difficulty of the labeled feature space, not a guaranteed best model choice.
+
+## Decision Pipeline
+
+The recommendation is produced by a fixed, inspectable pipeline:
+
+1. Validate inputs and encode labels.
+2. Audit class counts, imbalance, sparsity, and basic dataset conditions.
+3. Compute geometry, neighborhood, and boundary-related diagnostics.
+4. Run simple probe models and compare them to a dummy baseline.
+5. Aggregate the raw metrics into normalized scores such as signal,
+   linearity, nonlinearity, overlap, fragmentation, and reliability.
+6. Apply explicit rule-based branching to map those scores to a recommendation
+   category and confidence level.
+7. Render both a plain-language summary and a structured report.
+
+The full rationale and decision rules are documented in
+[docs/decision_pipeline.md](/Users/niklasmelton/code/Separatix/docs/decision_pipeline.md).
+
+## Sparse Inputs And Memory Behavior
+
+Sparse matrices are accepted directly. Diagnostics that need dense data use a
+shared densification policy rather than a separate dense-only code path. When a
+step would require densification, `separatix` can fail, skip, or warn and
+subsample before densifying, depending on configuration. These events are
+recorded in the report.
+
+## Examples
+
+- [examples/basic_breast_cancer.py](/Users/niklasmelton/code/Separatix/examples/basic_breast_cancer.py)
+- [examples/linear_hyperplane_visual.py](/Users/niklasmelton/code/Separatix/examples/linear_hyperplane_visual.py)
+- [examples/curvilinear_boundary_visual.py](/Users/niklasmelton/code/Separatix/examples/curvilinear_boundary_visual.py)
+- [examples/high_dimensional_linear_hyperplane.py](/Users/niklasmelton/code/Separatix/examples/high_dimensional_linear_hyperplane.py)
+- [examples/high_dimensional_curvilinear_hyperplane.py](/Users/niklasmelton/code/Separatix/examples/high_dimensional_curvilinear_hyperplane.py)
+- [examples/moons_vs_linear.py](/Users/niklasmelton/code/Separatix/examples/moons_vs_linear.py)
+- [examples/circles_kernel_signal.py](/Users/niklasmelton/code/Separatix/examples/circles_kernel_signal.py)
+- [examples/multiclass_wine.py](/Users/niklasmelton/code/Separatix/examples/multiclass_wine.py)
+- [examples/sparse_text_like_embeddings.py](/Users/niklasmelton/code/Separatix/examples/sparse_text_like_embeddings.py)
+
+## Related Work
+
+This package is not an implementation of a published dataset-complexity
+procedure, but the project is adjacent to and inspired by prior work on
+classification complexity and data geometry. In particular, would like to acknowledge:
+
+- Ho and Basu, "Complexity Measures of Supervised Classification Problems"
+  ([PDF](https://sci2s.ugr.es/keel/pdf/algorithm/articulo/2002-IEEE-TPAMI-Ho-DC.pdf))
+- Lorena, Garcia, Lehmann, Souto, and Ho, "How Complex Is Your
+  Classification Problem? A Survey on Measuring Classification Complexity"
+  ([DOI](https://doi.org/10.1145/3347711),
+  [PDF](https://dl.acm.org/doi/epdf/10.1145/3347711))
+
+We do not follow those procedures directly, but they are relevant background
+for why geometry-aware pretraining diagnostics are useful.
+

separatix-0.1.0a1/README.md

@@ -0,0 +1,143 @@
+[![separatix logo](https://raw.githubusercontent.com/NiklasMelton/Separatix/develop/img/separatix_logo.png)](https://github.com/NiklasMelton/Separatix)
+
+# separatix
+
+`separatix` profiles labeled feature spaces before classifier training and
+returns transparent, confidence-aware guidance about apparent classification
+complexity.
+
+The intended use case includes learned embeddings, but the package is not
+restricted to embeddings. It also works on raw feature matrices when you want a
+coarse diagnostic of whether the observed class geometry looks mostly linear,
+smoothly nonlinear, local or kernel-like, fragmented, bottlenecked, or too
+unreliable to trust.
+
+`separatix` does not claim to pick the optimal classifier. It is a pretraining
+diagnostic and auditing tool designed to make its reasoning visible.
+
+## Installation
+
+```bash
+pip install separatix
+```
+
+To install the latest development version directly from GitHub:
+
+```bash
+pip install "git+https://github.com/NiklasMelton/Separatix.git@develop"
+```
+
+## Quick start
+
+```python
+from separatix import diagnose
+
+recommendation = diagnose(X, y, random_state=0)
+print(recommendation)
+```
+
+For a structured audit:
+
+```python
+from separatix import diagnose
+
+report = diagnose(X, y, return_report=True, random_state=0)
+print(report.recommendation_text)
+print(report.decision_path)
+print(report.scores)
+print(report.to_json())
+```
+
+## What It Accepts
+
+- Dense NumPy arrays
+- SciPy sparse matrices
+- pandas DataFrames and Series when pandas is installed
+- Binary and multiclass classification targets
+- String or numeric labels treated as categorical class identifiers
+
+Regression, multilabel classification, and multioutput classification are not
+supported.
+
+## What It Returns
+
+By default, `diagnose(...)` returns a plain-text recommendation. With
+`return_report=True`, it returns a `DiagnosticReport` that includes:
+
+- the recommendation label
+- plain-text recommendation text
+- confidence level
+- underlying metric groups
+- normalized summary scores
+- a visible decision path
+- warnings and skipped diagnostics
+- sampling and densification events
+- preprocessing and runtime metadata
+
+The report is JSON-serializable through `report.to_dict()` and `report.to_json()`.
+
+## Recommendation Categories
+
+- `linear_likely_sufficient`
+- `smooth_nonlinear_recommended`
+- `kernel_or_local_recommended`
+- `high_capacity_or_partitioning_recommended`
+- `feature_or_label_bottleneck_likely`
+- `insufficient_data_or_unreliable_geometry`
+- `inconclusive`
+
+These categories are intentionally coarse. They describe the apparent geometry
+and difficulty of the labeled feature space, not a guaranteed best model choice.
+
+## Decision Pipeline
+
+The recommendation is produced by a fixed, inspectable pipeline:
+
+1. Validate inputs and encode labels.
+2. Audit class counts, imbalance, sparsity, and basic dataset conditions.
+3. Compute geometry, neighborhood, and boundary-related diagnostics.
+4. Run simple probe models and compare them to a dummy baseline.
+5. Aggregate the raw metrics into normalized scores such as signal,
+   linearity, nonlinearity, overlap, fragmentation, and reliability.
+6. Apply explicit rule-based branching to map those scores to a recommendation
+   category and confidence level.
+7. Render both a plain-language summary and a structured report.
+
+The full rationale and decision rules are documented in
+[docs/decision_pipeline.md](/Users/niklasmelton/code/Separatix/docs/decision_pipeline.md).
+
+## Sparse Inputs And Memory Behavior
+
+Sparse matrices are accepted directly. Diagnostics that need dense data use a
+shared densification policy rather than a separate dense-only code path. When a
+step would require densification, `separatix` can fail, skip, or warn and
+subsample before densifying, depending on configuration. These events are
+recorded in the report.
+
+## Examples
+
+- [examples/basic_breast_cancer.py](/Users/niklasmelton/code/Separatix/examples/basic_breast_cancer.py)
+- [examples/linear_hyperplane_visual.py](/Users/niklasmelton/code/Separatix/examples/linear_hyperplane_visual.py)
+- [examples/curvilinear_boundary_visual.py](/Users/niklasmelton/code/Separatix/examples/curvilinear_boundary_visual.py)
+- [examples/high_dimensional_linear_hyperplane.py](/Users/niklasmelton/code/Separatix/examples/high_dimensional_linear_hyperplane.py)
+- [examples/high_dimensional_curvilinear_hyperplane.py](/Users/niklasmelton/code/Separatix/examples/high_dimensional_curvilinear_hyperplane.py)
+- [examples/moons_vs_linear.py](/Users/niklasmelton/code/Separatix/examples/moons_vs_linear.py)
+- [examples/circles_kernel_signal.py](/Users/niklasmelton/code/Separatix/examples/circles_kernel_signal.py)
+- [examples/multiclass_wine.py](/Users/niklasmelton/code/Separatix/examples/multiclass_wine.py)
+- [examples/sparse_text_like_embeddings.py](/Users/niklasmelton/code/Separatix/examples/sparse_text_like_embeddings.py)
+
+## Related Work
+
+This package is not an implementation of a published dataset-complexity
+procedure, but the project is adjacent to and inspired by prior work on
+classification complexity and data geometry. In particular, would like to acknowledge:
+
+- Ho and Basu, "Complexity Measures of Supervised Classification Problems"
+  ([PDF](https://sci2s.ugr.es/keel/pdf/algorithm/articulo/2002-IEEE-TPAMI-Ho-DC.pdf))
+- Lorena, Garcia, Lehmann, Souto, and Ho, "How Complex Is Your
+  Classification Problem? A Survey on Measuring Classification Complexity"
+  ([DOI](https://doi.org/10.1145/3347711),
+  [PDF](https://dl.acm.org/doi/epdf/10.1145/3347711))
+
+We do not follow those procedures directly, but they are relevant background
+for why geometry-aware pretraining diagnostics are useful.

separatix-0.1.0a1/pyproject.toml

@@ -0,0 +1,49 @@
+[tool.poetry]
+name = "separatix"
+version = "0.1.0a1"
+description = "Diagnostic profiling of labeled embeddings for classification model complexity guidance."
+authors = ["Niklas Melton <niklas@example.com>"]
+readme = "README.md"
+license = "MIT"
+packages = [{ include = "separatix" }]
+
+[tool.poetry.dependencies]
+python = ">=3.9,<3.15"
+numpy = ">=1.23"
+scipy = ">=1.9"
+scikit-learn = ">=1.2"
+pandas = { version = ">=1.5", optional = true }
+matplotlib = { version = ">=3.6", optional = true }
+ripser = { version = ">=0.6", optional = true }
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=7"
+pytest-cov = ">=4"
+ruff = ">=0.5"
+mypy = ">=1"
+build = ">=1"
+twine = ">=5"
+
+[tool.poetry.extras]
+pandas = ["pandas"]
+tda = ["ripser"]
+examples = ["matplotlib", "pandas"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.mypy]
+python_version = "3.12"
+warn_unused_configs = true
+ignore_missing_imports = true
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

separatix-0.1.0a1/separatix/__init__.py

@@ -0,0 +1,8 @@
+"""Public package exports for separatix."""
+
+from separatix.api import diagnose
+from separatix.config import ProfilerConfig
+from separatix.profiler import ComplexityProfiler
+from separatix.report import DiagnosticReport
+
+__all__ = ["ComplexityProfiler", "DiagnosticReport", "ProfilerConfig", "diagnose"]

separatix-0.1.0a1/separatix/api.py

@@ -0,0 +1,37 @@
+"""Functional API for separatix."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from separatix.profiler import ComplexityProfiler
+from separatix.report import DiagnosticReport
+
+
+def diagnose(
+    X: Any,
+    y: Any,
+    *,
+    return_report: bool = False,
+    budget: Literal["fast", "standard", "extended"] = "standard",
+    topology: Literal["off", "auto", "graph", "persistent"] = "auto",
+    densify_policy: Literal["fail", "warn_and_sample", "skip"] = ("warn_and_sample"),
+    max_dense_mb: int = 512,
+    max_samples: int | None = None,
+    random_state: int | None = None,
+    warn_on_densify: bool = True,
+) -> str | DiagnosticReport:
+    """Diagnose apparent classification complexity from embeddings and labels."""
+    profiler = ComplexityProfiler(
+        budget=budget,
+        topology=topology,
+        densify_policy=densify_policy,
+        max_dense_mb=max_dense_mb,
+        max_samples=max_samples,
+        random_state=random_state,
+        warn_on_densify=warn_on_densify,
+    )
+    report = profiler.fit(X, y).report_
+    if report is None:
+        raise RuntimeError("Profiler did not produce a report.")
+    return report if return_report else report.recommendation_text

separatix-0.1.0a1/separatix/config.py

@@ -0,0 +1,42 @@
+"""Configuration objects for separatix."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Literal
+
+from separatix.constants import BUDGETS
+
+
+@dataclass
+class ProfilerConfig:
+    """Configuration for the separatix diagnostic profiler."""
+
+    budget: Literal["fast", "standard", "extended"] = "standard"
+    topology: Literal["off", "auto", "graph", "persistent"] = "auto"
+    densify_policy: Literal["fail", "warn_and_sample", "skip"] = "warn_and_sample"
+    max_dense_mb: int = 512
+    max_samples: int | None = None
+    min_dense_samples: int = 200
+    random_state: int | None = None
+    warn_on_densify: bool = True
+    n_jobs: int | None = None
+
+    def __post_init__(self) -> None:
+        """Validate configuration values."""
+        if self.budget not in BUDGETS:
+            raise ValueError(f"Unsupported budget: {self.budget!r}")
+        if self.topology not in {"off", "auto", "graph", "persistent"}:
+            raise ValueError(f"Unsupported topology mode: {self.topology!r}")
+        if self.densify_policy not in {"fail", "warn_and_sample", "skip"}:
+            raise ValueError(f"Unsupported densify policy: {self.densify_policy!r}")
+        if self.max_dense_mb <= 0:
+            raise ValueError("max_dense_mb must be positive.")
+        if self.max_samples is not None and self.max_samples <= 0:
+            raise ValueError("max_samples must be positive when provided.")
+        if self.min_dense_samples <= 0:
+            raise ValueError("min_dense_samples must be positive.")
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a JSON-serializable configuration dictionary."""
+        return asdict(self)

separatix-0.1.0a1/separatix/constants.py

@@ -0,0 +1,57 @@
+"""Constants used across the separatix package."""
+
+from __future__ import annotations
+
+LINEAR_LIKELY_SUFFICIENT = "linear_likely_sufficient"
+SMOOTH_NONLINEAR_RECOMMENDED = "smooth_nonlinear_recommended"
+KERNEL_OR_LOCAL_RECOMMENDED = "kernel_or_local_recommended"
+HIGH_CAPACITY_OR_PARTITIONING_RECOMMENDED = "high_capacity_or_partitioning_recommended"
+FEATURE_OR_LABEL_BOTTLENECK_LIKELY = "feature_or_label_bottleneck_likely"
+INSUFFICIENT_DATA_OR_UNRELIABLE_GEOMETRY = "insufficient_data_or_unreliable_geometry"
+INCONCLUSIVE = "inconclusive"
+
+RECOMMENDATION_LABELS = {
+    LINEAR_LIKELY_SUFFICIENT: "Linear model likely sufficient.",
+    SMOOTH_NONLINEAR_RECOMMENDED: "Smooth nonlinear model likely useful.",
+    KERNEL_OR_LOCAL_RECOMMENDED: "Kernel or local model likely useful.",
+    HIGH_CAPACITY_OR_PARTITIONING_RECOMMENDED: (
+        "Higher-capacity or partitioning model likely useful."
+    ),
+    FEATURE_OR_LABEL_BOTTLENECK_LIKELY: "Feature or label bottleneck likely.",
+    INSUFFICIENT_DATA_OR_UNRELIABLE_GEOMETRY: (
+        "Insufficient data or unreliable geometry."
+    ),
+    INCONCLUSIVE: "Diagnostic result is inconclusive.",
+}
+
+BUDGETS = {
+    "fast": {
+        "max_probe_samples": 5000,
+        "max_neighbor_samples": 5000,
+        "max_boundary_samples": 2000,
+        "cv_folds": 3,
+        "bootstrap_repeats": 0,
+        "run_kernel_probe": False,
+        "run_persistent_topology": False,
+    },
+    "standard": {
+        "max_probe_samples": 20000,
+        "max_neighbor_samples": 10000,
+        "max_boundary_samples": 3000,
+        "cv_folds": 5,
+        "bootstrap_repeats": 3,
+        "run_kernel_probe": True,
+        "run_persistent_topology": "auto",
+    },
+    "extended": {
+        "max_probe_samples": 50000,
+        "max_neighbor_samples": 20000,
+        "max_boundary_samples": 5000,
+        "cv_folds": 5,
+        "bootstrap_repeats": 10,
+        "run_kernel_probe": True,
+        "run_persistent_topology": "auto",
+    },
+}
+
+CONFIDENCE_LEVELS = ("low", "medium", "high")

separatix-0.1.0a1/separatix/densify.py

@@ -0,0 +1,106 @@
+"""Dense conversion helpers."""
+
+from __future__ import annotations
+
+from math import floor
+from typing import Any
+
+import numpy as np
+from scipy import sparse
+
+from separatix.config import ProfilerConfig
+from separatix.exceptions import DensificationError, DensificationWarning
+from separatix.sampling import stratified_subsample_indices
+from separatix.utils.warnings import record_warning
+
+
+def ensure_dense_or_sample(
+    X: Any,
+    y: np.ndarray,
+    *,
+    reason: str,
+    config: ProfilerConfig,
+    report_context: dict[str, Any],
+) -> dict[str, Any]:
+    """Return a dense matrix, optionally after stratified subsampling."""
+    densification_events = report_context.setdefault("densification_events", [])
+    warnings_list = report_context.setdefault("warnings", [])
+    skipped = report_context.setdefault("skipped_diagnostics", [])
+
+    if not sparse.issparse(X):
+        return {"X": np.asarray(X), "y": y, "performed": False, "skipped": False}
+
+    dtype = X.dtype if X.dtype is not None else np.dtype(float)
+    estimated_mb = X.shape[0] * X.shape[1] * np.dtype(dtype).itemsize / 1024**2
+    event = {
+        "operation": "densify",
+        "reason": reason,
+        "input_shape": [int(X.shape[0]), int(X.shape[1])],
+        "estimated_full_dense_mb": float(estimated_mb),
+        "max_dense_mb": config.max_dense_mb,
+        "policy": config.densify_policy,
+        "sampling_used": False,
+        "n_original": int(X.shape[0]),
+        "n_used": int(X.shape[0]),
+        "status": "performed",
+    }
+
+    if estimated_mb <= config.max_dense_mb:
+        dense = X.toarray()
+        densification_events.append(event)
+        if config.warn_on_densify:
+            record_warning(
+                f"Sparse input densified for {reason}.",
+                warnings_list,
+                DensificationWarning,
+            )
+        return {"X": dense, "y": y, "performed": True, "skipped": False}
+
+    if config.densify_policy == "fail":
+        message = (
+            f"Dense conversion for {reason} would exceed "
+            f"max_dense_mb={config.max_dense_mb}."
+        )
+        raise DensificationError(message)
+
+    if config.densify_policy == "skip":
+        event["status"] = "skipped"
+        densification_events.append(event)
+        skipped.append(
+            {
+                "name": reason,
+                "reason": "dense conversion exceeds configured memory budget",
+            }
+        )
+        return {"X": None, "y": y, "performed": False, "skipped": True}
+
+    max_rows = floor(
+        (config.max_dense_mb * 1024**2) / (X.shape[1] * np.dtype(dtype).itemsize)
+    )
+    n_used = min(X.shape[0], max_rows, config.max_samples or X.shape[0])
+    if n_used < min(config.min_dense_samples, X.shape[0]):
+        skipped.append({"name": reason, "reason": "dense subsample would be too small"})
+        event["status"] = "skipped_too_small"
+        event["n_used"] = int(max(n_used, 0))
+        densification_events.append(event)
+        if config.densify_policy == "warn_and_sample":
+            return {"X": None, "y": y, "performed": False, "skipped": True}
+        raise DensificationError(f"Unable to densify enough samples for {reason}.")
+
+    indices = stratified_subsample_indices(
+        y,
+        n_samples=n_used,
+        random_state=config.random_state,
+    )
+    dense = X[indices, :].toarray()
+    event["sampling_used"] = True
+    event["n_used"] = int(indices.shape[0])
+    event["status"] = "performed_on_subsample"
+    densification_events.append(event)
+    if config.warn_on_densify:
+        record_warning(
+            f"Sparse input was stratified-subsampled then densified for {reason}.",
+            warnings_list,
+            DensificationWarning,
+        )
+    return {"X": dense, "y": y[indices], "performed": True, "skipped": False}

separatix-0.1.0a1/separatix/exceptions.py

@@ -0,0 +1,13 @@
+"""Custom exceptions and warnings for separatix."""
+
+
+class SeparatixError(Exception):
+    """Base exception for separatix."""
+
+
+class DensificationError(SeparatixError):
+    """Raised when dense conversion is required but disallowed or impossible."""
+
+
+class DensificationWarning(UserWarning):
+    """Warning emitted when sparse data are densified or subsampled."""

separatix-0.1.0a1/separatix/metrics/__init__.py

@@ -0,0 +1 @@
+"""Diagnostic metric modules."""