neurospatial 0.1.0__py3-none-any.whl

neurospatial/__init__.py

@@ -0,0 +1,35 @@
+import logging
+
+from neurospatial.alignment import (
+    get_2d_rotation_matrix,
+    map_probabilities_to_nearest_target_bin,
+)
+from neurospatial.distance import distance_field, pairwise_distances
+from neurospatial.environment import Environment
+from neurospatial.layout.factories import (
+    get_layout_parameters,
+    list_available_layouts,
+)
+from neurospatial.layout.validation import validate_environment
+from neurospatial.spatial import map_points_to_bins
+from neurospatial.transforms import (
+    apply_transform_to_environment,
+    estimate_transform,
+)
+
+# Add NullHandler to prevent "No handler found" warnings if user doesn't configure logging
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "Environment",
+    "apply_transform_to_environment",
+    "distance_field",
+    "estimate_transform",
+    "get_2d_rotation_matrix",
+    "get_layout_parameters",
+    "list_available_layouts",
+    "map_points_to_bins",
+    "map_probabilities_to_nearest_target_bin",
+    "pairwise_distances",
+    "validate_environment",
+]

neurospatial/_constants.py

@@ -0,0 +1,75 @@
+"""Numerical constants and tolerances for neurospatial.
+
+This module defines all numerical tolerances used throughout the package
+for consistent behavior across geometric operations, equality checks, and
+numerical stability.
+
+All magic numbers should be imported from this module to ensure consistency
+and make it easier to tune parameters globally.
+"""
+
+import numpy as np
+
+# Geometric tolerances
+# --------------------
+# Used for: point-in-polygon tests, boundary detection, polygon simplification
+
+#: Geometric tolerance for distance comparisons (meters/cm)
+#: Points within this distance are considered coincident
+GEOMETRIC_TOLERANCE = 1e-9
+
+#: Relative tolerance for np.isclose() comparisons
+RELATIVE_TOLERANCE = 1e-9
+
+#: Absolute tolerance for np.isclose() comparisons
+ABSOLUTE_TOLERANCE = 1e-9
+
+#: Point tolerance for region operations (polygon vertices, boundary detection)
+#: Used to determine if two points should be considered the same location
+POINT_TOLERANCE = 1e-8
+
+# Numerical stability
+# -------------------
+# Used for: division by zero prevention, log(0) prevention
+
+#: Small epsilon to prevent division by zero
+EPSILON = 1e-10
+
+#: Minimum denominator for inverse distance weighting
+#: Prevents division by zero when query point equals a data point
+IDW_MIN_DISTANCE = 1e-8
+
+# Angle conventions
+# -----------------
+
+#: Angle range for 2D edge angles (radians)
+ANGLE_2D_RANGE = (-np.pi, np.pi)
+
+#: Tolerance for angle wraparound comparisons
+ANGLE_TOLERANCE = 1e-8
+
+# KDTree configuration
+# --------------------
+
+#: Default leaf size for scipy/sklearn KDTree queries
+#: Smaller values = faster queries, slower construction
+#: Larger values = slower queries, faster construction
+#: 16 is a good balance for typical spatial queries
+KDTREE_LEAF_SIZE = 16
+
+#: Leaf size for composite environment KDTrees (larger for merged data)
+#: Composite environments have more bins, so we use a larger leaf size
+KDTREE_COMPOSITE_LEAF_SIZE = 40
+
+# Distance thresholds
+# -------------------
+
+#: Maximum distance multiplier for bin containment checks
+#: Points further than (bin_size * BIN_CONTAINMENT_FACTOR) from bin center
+#: are considered outside the bin
+#: Conservative value of 0.7 works well for rectangular grid cells
+BIN_CONTAINMENT_FACTOR = 0.7
+
+#: Maximum distance multiplier for nearest neighbor queries
+#: Used to detect when a point is outside all bins
+NEAREST_BIN_DISTANCE_THRESHOLD = 2.0

neurospatial/_logging.py

@@ -0,0 +1,202 @@
+"""Structured logging infrastructure for neurospatial.
+
+This module provides a centralized logging system for the neurospatial package.
+By default, logging is disabled (NullHandler), but users can enable it by
+configuring the root logger.
+
+Examples
+--------
+Enable logging to console::
+
+    import logging
+
+    logging.basicConfig(level=logging.INFO)
+
+    from neurospatial import Environment
+
+    env = Environment.from_samples(data, bin_size=2.0)
+    # INFO:neurospatial:Building layout: regular_grid
+    # INFO:neurospatial:Environment created: 245 bins, 2 dims
+
+Enable logging with more detail::
+
+    import logging
+
+    logging.basicConfig(
+        level=logging.DEBUG,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+
+Filter to only neurospatial logs::
+
+    import logging
+
+    neurospatial_logger = logging.getLogger("neurospatial")
+    neurospatial_logger.setLevel(logging.INFO)
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
+    neurospatial_logger.addHandler(handler)
+"""
+
+import logging
+from typing import Any
+
+# Create package logger
+logger = logging.getLogger("neurospatial")
+
+# Add NullHandler to prevent "No handler found" warnings
+# Users must explicitly enable logging
+logger.addHandler(logging.NullHandler())
+
+
+def log_layout_build(layout_type: str, params: dict[str, Any]) -> None:
+    """Log layout engine build operation.
+
+    Parameters
+    ----------
+    layout_type : str
+        Type of layout being built (e.g., 'regular_grid', 'hexagonal').
+    params : dict
+        Parameters used to build the layout.
+    """
+    logger.info(
+        f"Building layout: {layout_type}",
+        extra={"layout_type": layout_type, "params": params},
+    )
+
+
+def log_graph_validation(n_nodes: int, n_edges: int, n_dims: int) -> None:
+    """Log graph validation operation.
+
+    Parameters
+    ----------
+    n_nodes : int
+        Number of nodes in the connectivity graph.
+    n_edges : int
+        Number of edges in the connectivity graph.
+    n_dims : int
+        Number of spatial dimensions.
+    """
+    logger.debug(
+        f"Validating connectivity graph: {n_nodes} nodes, {n_edges} edges, {n_dims}D",
+        extra={"n_nodes": n_nodes, "n_edges": n_edges, "n_dims": n_dims},
+    )
+
+
+def log_environment_created(
+    env_type: str, n_bins: int, n_dims: int, env_name: str | None = None
+) -> None:
+    """Log environment creation.
+
+    Parameters
+    ----------
+    env_type : str
+        Type of environment (layout type tag).
+    n_bins : int
+        Number of bins in the environment.
+    n_dims : int
+        Number of spatial dimensions.
+    env_name : str or None
+        Optional name of the environment.
+    """
+    name_str = f" '{env_name}'" if env_name else ""
+    logger.info(
+        f"Environment created{name_str}: {n_bins} bins, {n_dims}D",
+        extra={
+            "type": env_type,
+            "n_bins": n_bins,
+            "n_dims": n_dims,
+            "env_name": env_name,
+        },
+    )
+
+
+def log_composite_build(n_subenvs: int, total_bins: int, n_bridges: int) -> None:
+    """Log composite environment construction.
+
+    Parameters
+    ----------
+    n_subenvs : int
+        Number of sub-environments merged.
+    total_bins : int
+        Total number of bins in composite.
+    n_bridges : int
+        Number of bridge edges created.
+    """
+    logger.info(
+        f"CompositeEnvironment created: {n_subenvs} sub-envs, "
+        f"{total_bins} total bins, {n_bridges} bridges",
+        extra={
+            "n_subenvs": n_subenvs,
+            "total_bins": total_bins,
+            "n_bridges": n_bridges,
+        },
+    )
+
+
+def log_region_added(
+    region_name: str, region_kind: str, env_name: str | None = None
+) -> None:
+    """Log region addition to environment.
+
+    Parameters
+    ----------
+    region_name : str
+        Name of the region added.
+    region_kind : str
+        Type of region ('point' or 'polygon').
+    env_name : str or None
+        Optional name of the environment.
+    """
+    env_str = f" to '{env_name}'" if env_name else ""
+    logger.debug(
+        f"Region '{region_name}' ({region_kind}) added{env_str}",
+        extra={
+            "region_name": region_name,
+            "region_kind": region_kind,
+            "env_name": env_name,
+        },
+    )
+
+
+def log_spatial_query(query_type: str, n_points: int, n_results: int) -> None:
+    """Log spatial query operation.
+
+    Parameters
+    ----------
+    query_type : str
+        Type of query ('bin_at', 'contains', 'neighbors', etc.).
+    n_points : int
+        Number of points queried.
+    n_results : int
+        Number of results returned.
+    """
+    logger.debug(
+        f"Spatial query '{query_type}': {n_points} points -> {n_results} results",
+        extra={"query_type": query_type, "n_points": n_points, "n_results": n_results},
+    )
+
+
+def log_performance_warning(
+    operation: str, duration_ms: float, threshold_ms: float
+) -> None:
+    """Log performance warning when operation exceeds threshold.
+
+    Parameters
+    ----------
+    operation : str
+        Name of the operation.
+    duration_ms : float
+        Actual duration in milliseconds.
+    threshold_ms : float
+        Expected threshold in milliseconds.
+    """
+    logger.warning(
+        f"Performance warning: {operation} took {duration_ms:.1f}ms "
+        f"(expected <{threshold_ms:.1f}ms)",
+        extra={
+            "operation": operation,
+            "duration_ms": duration_ms,
+            "threshold_ms": threshold_ms,
+        },
+    )