feat: Implement deterministic seed management for reproducibility (#6)

Add comprehensive reproducibility support for all random operations:

- Add SeedManager class in core/reproducibility.py for global seed control
- Add seed parameter to GridFIA API constructor and set_seed() method
- Fix parallel processing workers (_bootstrap_worker, _permutation_worker)
  to accept and use deterministic seeds when global seed is set
- Fix statistical analysis (permutation test, bootstrap test) to use
  reproducible random states when global seed is set
- Add comprehensive test suite with 28 tests covering all reproducibility
  scenarios including API, parallel workers, and statistical analysis

Examples:
  # Set seed at API initialization
  api = GridFIA(seed=42)

  # Or set seed after initialization
  api.set_seed(42)

  # Or use SeedManager directly
  from gridfia.core.reproducibility import set_seed
  set_seed(42)

Fixes #6

Author: mihiarc

gridfia/api.py

@@ -85,7 +85,11 @@ class GridFIA:
     >>> api.create_maps("data/nc_forest.zarr", map_type="diversity")
     """
 
-    def __init__(self, config: Optional[Union[str, Path, GridFIASettings]] = None):
+    def __init__(
+        self,
+        config: Optional[Union[str, Path, GridFIASettings]] = None,
+        seed: Optional[int] = None
+    ):
         """
         Initialize GridFIA API.
 
@@ -94,6 +98,18 @@ def __init__(self, config: Optional[Union[str, Path, GridFIASettings]] = None):
         config : str, Path, or GridFIASettings, optional
             Configuration file path or settings object.
             If None, uses default settings.
+        seed : int, optional
+            Random seed for reproducibility. If provided, all random
+            operations (bootstrap, permutation tests, etc.) will be
+            deterministic.
+
+        Examples
+        --------
+        >>> api = GridFIA(seed=42)  # Reproducible results
+        >>> result1 = api.calculate_metrics(zarr_path)
+        >>>
+        >>> api2 = GridFIA(seed=42)  # Same seed = same results
+        >>> result2 = api2.calculate_metrics(zarr_path)
         """
         if config is None:
             self.settings = GridFIASettings()
@@ -102,10 +118,39 @@ def __init__(self, config: Optional[Union[str, Path, GridFIASettings]] = None):
         else:
             self.settings = config
 
+        # Set seed for reproducibility
+        self._seed = seed
+        if seed is not None:
+            from .core.reproducibility import SeedManager
+            SeedManager.set_global_seed(seed)
+
         # Lock for thread-safe lazy initialization of components
         self._init_lock = threading.Lock()
         self._rest_client = None
         self._processor = None
+
+    def set_seed(self, seed: int) -> None:
+        """
+        Set random seed for reproducibility.
+
+        Parameters
+        ----------
+        seed : int
+            Random seed value.
+
+        Examples
+        --------
+        >>> api = GridFIA()
+        >>> api.set_seed(42)
+        """
+        from .core.reproducibility import SeedManager
+        self._seed = seed
+        SeedManager.set_global_seed(seed)
+
+    @property
+    def seed(self) -> Optional[int]:
+        """Get current random seed."""
+        return self._seed
 
     @property
     def rest_client(self) -> BigMapRestClient:

gridfia/core/analysis/statistical_analysis.py

@@ -391,21 +391,39 @@ def _permutation_test(
             # Sequential permutation test implementation
             # Observed difference
             observed_diff = group1.mean() - group2.mean()
-            
+
             # Combine all data
             combined = np.concatenate([group1.values, group2.values])
             n1, n2 = len(group1), len(group2)
-            
+
+            # Check for global seed from SeedManager for reproducibility
+            try:
+                from ..reproducibility import SeedManager
+                global_seed = SeedManager.get_seed()
+            except ImportError:
+                global_seed = None
+
+            # Create random state for reproducibility if seed is set
+            if global_seed is not None:
+                rng = np.random.RandomState(global_seed)
+            else:
+                rng = np.random
+
             # Permutation distribution
             perm_diffs = []
-            for _ in range(n_permutations):
-                # Randomly permute the combined data
-                np.random.shuffle(combined)
-                
+            for i in range(n_permutations):
+                # Randomly permute the combined data (using reproducible RNG if seed set)
+                if global_seed is not None:
+                    # Create iteration-specific seed for reproducibility
+                    iter_rng = np.random.RandomState(global_seed + i)
+                    shuffled = iter_rng.permutation(combined)
+                else:
+                    shuffled = rng.permutation(combined)
+
                 # Split into two groups of original sizes
-                perm_group1 = combined[:n1]
-                perm_group2 = combined[n1:n1+n2]
-                
+                perm_group1 = shuffled[:n1]
+                perm_group2 = shuffled[n1:n1+n2]
+
                 # Calculate difference
                 perm_diff = perm_group1.mean() - perm_group2.mean()
                 perm_diffs.append(perm_diff)
@@ -463,15 +481,27 @@ def _bootstrap_test(
                     logger.debug("Parallel processing not available for bootstrap")
 
             # Sequential bootstrap implementation
+            # Check for global seed from SeedManager for reproducibility
+            try:
+                from ..reproducibility import SeedManager
+                global_seed = SeedManager.get_seed()
+            except ImportError:
+                global_seed = None
+
             # Bootstrap distributions
             group1_boots = []
             group2_boots = []
             diff_boots = []
-            
-            for _ in range(n_bootstrap):
-                # Bootstrap samples
-                boot1 = resample(group1.values, n_samples=len(group1))
-                boot2 = resample(group2.values, n_samples=len(group2))
+
+            for i in range(n_bootstrap):
+                # Bootstrap samples with reproducible random state if seed is set
+                if global_seed is not None:
+                    iter_seed = global_seed + i
+                    boot1 = resample(group1.values, n_samples=len(group1), random_state=iter_seed)
+                    boot2 = resample(group2.values, n_samples=len(group2), random_state=iter_seed + n_bootstrap)
+                else:
+                    boot1 = resample(group1.values, n_samples=len(group1))
+                    boot2 = resample(group2.values, n_samples=len(group2))
 
                 mean1 = np.mean(boot1)
                 mean2 = np.mean(boot2)

gridfia/core/reproducibility.py

@@ -0,0 +1,212 @@
+"""
+Reproducibility utilities for deterministic random operations.
+
+This module provides seed management to ensure reproducible results
+across runs, including support for parallel processing.
+"""
+
+import random
+from contextlib import contextmanager
+from typing import Optional, Generator
+import logging
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+class SeedManager:
+    """
+    Manage random seeds for reproducibility across the package.
+
+    This class provides global seed management that affects all random
+    operations in GridFIA, including parallel processing workers.
+
+    Examples
+    --------
+    >>> from gridfia.core.reproducibility import SeedManager
+    >>>
+    >>> # Set global seed
+    >>> SeedManager.set_global_seed(42)
+    >>>
+    >>> # Use temporary seed for specific operation
+    >>> with SeedManager.temporary_seed(123):
+    ...     result = some_random_operation()
+    """
+
+    _global_seed: Optional[int] = None
+    _random_state: Optional[np.random.RandomState] = None
+
+    @classmethod
+    def set_global_seed(cls, seed: int) -> None:
+        """
+        Set global seed for all random operations.
+
+        Parameters
+        ----------
+        seed : int
+            Seed value for random number generators.
+
+        Notes
+        -----
+        This affects:
+        - Python's random module
+        - NumPy's random module
+        - All GridFIA calculations using random operations
+        """
+        cls._global_seed = seed
+        cls._random_state = np.random.RandomState(seed)
+
+        # Set seeds for standard libraries
+        random.seed(seed)
+        np.random.seed(seed)
+
+        logger.info(f"Global seed set to {seed}")
+
+    @classmethod
+    def get_seed(cls) -> Optional[int]:
+        """
+        Get current global seed.
+
+        Returns
+        -------
+        int or None
+            Current global seed, or None if not set.
+        """
+        return cls._global_seed
+
+    @classmethod
+    def get_random_state(cls) -> Optional[np.random.RandomState]:
+        """
+        Get the global RandomState object.
+
+        Returns
+        -------
+        np.random.RandomState or None
+            RandomState object for reproducible random operations.
+        """
+        return cls._random_state
+
+    @classmethod
+    def derive_seed(cls, offset: int = 0) -> int:
+        """
+        Derive a deterministic seed from the global seed.
+
+        Useful for creating unique but reproducible seeds for
+        parallel workers or nested operations.
+
+        Parameters
+        ----------
+        offset : int
+            Offset to add to the global seed.
+
+        Returns
+        -------
+        int
+            Derived seed value.
+
+        Raises
+        ------
+        ValueError
+            If no global seed has been set.
+        """
+        if cls._global_seed is None:
+            raise ValueError("No global seed set. Call set_global_seed() first.")
+        return cls._global_seed + offset
+
+    @classmethod
+    def get_worker_seed(cls, worker_id: int) -> Optional[int]:
+        """
+        Get a deterministic seed for a parallel worker.
+
+        Parameters
+        ----------
+        worker_id : int
+            Unique identifier for the worker (0, 1, 2, ...).
+
+        Returns
+        -------
+        int or None
+            Seed for the worker, or None if no global seed is set.
+        """
+        if cls._global_seed is None:
+            return None
+        # Use a prime multiplier to spread seeds and avoid collisions
+        return cls._global_seed + (worker_id * 997)
+
+    @classmethod
+    @contextmanager
+    def temporary_seed(cls, seed: int) -> Generator[None, None, None]:
+        """
+        Context manager for temporary seed override.
+
+        Parameters
+        ----------
+        seed : int
+            Temporary seed to use within the context.
+
+        Yields
+        ------
+        None
+
+        Examples
+        --------
+        >>> with SeedManager.temporary_seed(999):
+        ...     # Operations here use seed 999
+        ...     result = np.random.rand()
+        >>> # Original seed is restored here
+        """
+        # Save current state
+        old_random_state = random.getstate()
+        old_numpy_state = np.random.get_state()
+        old_global_seed = cls._global_seed
+
+        try:
+            # Set temporary seed
+            random.seed(seed)
+            np.random.seed(seed)
+            cls._global_seed = seed
+            yield
+        finally:
+            # Restore original state
+            random.setstate(old_random_state)
+            np.random.set_state(old_numpy_state)
+            cls._global_seed = old_global_seed
+
+    @classmethod
+    def reset(cls) -> None:
+        """
+        Reset seed manager to initial state (no global seed).
+        """
+        cls._global_seed = None
+        cls._random_state = None
+        logger.info("Seed manager reset")
+
+
+def set_seed(seed: int) -> None:
+    """
+    Convenience function to set global seed.
+
+    Parameters
+    ----------
+    seed : int
+        Seed value for random number generators.
+
+    Examples
+    --------
+    >>> from gridfia.core.reproducibility import set_seed
+    >>> set_seed(42)
+    """
+    SeedManager.set_global_seed(seed)
+
+
+def get_seed() -> Optional[int]:
+    """
+    Convenience function to get current global seed.
+
+    Returns
+    -------
+    int or None
+        Current global seed.
+    """
+    return SeedManager.get_seed()