Merge pull request #178 from jpintar/use_numpy_random_generator

Switch to using numpy.random.Generator throughout

Author: katosh

README.md

@@ -73,6 +73,11 @@ ____
 Release Notes
 -------------
 
+ ### Version 1.4.5 (future)
+ * Use `numpy.random.Generator` in place of the legacy global `numpy.random.RandomState` and require
+`numpy>=1.17`. Note that since the default PRNG is now [PCG64](https://numpy.org/devdocs/reference/random/bit_generators/pcg64.html) instead of the Mersenne Twister, numerical outputs are expected to differ from
+those in previous versions. If exact reproducibility is required, users should pin the relevant prior version.
+
  ### Version 1.4.4
  * Fix: reorder dependencies to work around uv resolver order-dependence ([astral-sh/uv#5161](https://github.com/astral-sh/uv/issues/5161)), which caused `uv pip install palantir` to resolve to incompatible ancient versions of scanpy/numba/llvmlite
 

pyproject.toml

@@ -38,7 +38,7 @@ dependencies = [
     "igraph>=0.11.8",
     "scikit-learn",
     "matplotlib>=3.8.0",
-    "numpy>=1.14.2",
+    "numpy>=1.17.0",
     "pandas>=0.22.0",
     "scipy>=1.3",
     "networkx>=2.1",

src/palantir/core.py

@@ -2,7 +2,8 @@
 Core functions for running Palantir
 """
 
-from typing import Union, Optional, List, Dict, Tuple
+from __future__ import annotations
+
 import numpy as np
 import pandas as pd
 import networkx as nx
@@ -19,6 +20,7 @@
 from scipy.sparse.csgraph import connected_components
 from scipy.stats import entropy, pearsonr, norm
 from numpy.linalg import inv, pinv, LinAlgError
+from numpy.random import BitGenerator, SeedSequence, RandomState
 import warnings
 from anndata import AnnData
 
@@ -59,9 +61,9 @@ def _get_joblib_backend():
 
 
 def run_palantir(
-    data: Union[pd.DataFrame, AnnData],
-    early_cell,
-    terminal_states: Optional[Union[List, Dict, pd.Series]] = None,
+    data: pd.DataFrame | AnnData,
+    early_cell: str,
+    terminal_states: list | dict | pd.Series | None = None,
     knn: int = 30,
     num_waypoints: int = 1200,
     n_jobs: int = -1,
@@ -72,21 +74,21 @@ def run_palantir(
     pseudo_time_key: str = "palantir_pseudotime",
     entropy_key: str = "palantir_entropy",
     fate_prob_key: str = "palantir_fate_probabilities",
-    save_as_df: bool = None,
+    save_as_df: bool | None = None,
     waypoints_key: str = "palantir_waypoints",
-    seed: int = 20,
-) -> Optional[object]:
+    seed: int | np.ndarray | np.random.Generator | BitGenerator | SeedSequence | RandomState | None = 20,
+) -> object | None:
     """
     Executes the Palantir algorithm to derive pseudotemporal ordering of cells, their fate probabilities, and
     state entropy based on the multiscale diffusion map results.
 
     Parameters
     ----------
-    data : Union[pd.DataFrame, AnnData]
+    data : pd.DataFrame | AnnData
         Either a DataFrame of multiscale space diffusion components or a Scanpy AnnData object.
     early_cell : str
         Start cell for pseudotime construction.
-    terminal_states : List/Series/Dict, optional
+    terminal_states : list | pd.Series | dict, optional
         User-defined terminal states structure in the format {terminal_name:cell_name}. Default is None.
     knn : int, optional
         Number of nearest neighbors for graph construction. Default is 30.
@@ -116,12 +118,12 @@ def run_palantir(
         write h5ad files with DataFrames in ad.obsm. Default is palantir.SAVE_AS_DF = True.
     waypoints_key : str, optional
         Key to store the waypoints in uns of the AnnData object. Default is 'palantir_waypoints'.
-    seed : int, optional
+    seed : int | np.ndarray | np.random.Generator | BitGenerator | SeedSequence | RandomState | None, optional
         The seed for the random number generator used in waypoint sampling. Default is 20.
 
     Returns
     -------
-    Optional[PResults]
+    PResults | None
         PResults object with pseudotime, entropy, branch probabilities, and waypoints.
         If an AnnData object is passed as data, the result is written to its obs, obsm, and uns attributes
         using the provided keys and None is returned.
@@ -250,7 +252,9 @@ def run_palantir(
 
 
 def _max_min_sampling(
-    data: pd.DataFrame, num_waypoints: int, seed: Optional[int] = None
+    data: pd.DataFrame,
+    num_waypoints: int,
+    seed: int | np.ndarray | np.random.Generator | BitGenerator | SeedSequence | RandomState | None = 20,
 ) -> pd.Index:
     """Function for max min sampling of waypoints.
 
@@ -263,8 +267,8 @@ def _max_min_sampling(
         Data matrix along which to sample the waypoints, usually diffusion components.
     num_waypoints : int
         Number of waypoints to sample.
-    seed : Optional[int], default=None
-        Random number generator seed for the initial point selection.
+    seed : int | np.ndarray | np.random.Generator | BitGenerator | SeedSequence | RandomState | None, optional
+        Random number generator seed for the initial point selection. Default is 20
 
     Returns
     -------
@@ -282,16 +286,15 @@ def _max_min_sampling(
         )
         num_waypoints = min_waypoints
     no_iterations = int((num_waypoints) / data.shape[1])
-    if seed is not None:
-        np.random.seed(seed)
+    rng = np.random.default_rng(seed)
 
     N = data.shape[0]
     data_values = data.values
 
     for i, ind in enumerate(data.columns):
         vec = data_values[:, i]
 
-        current_wp = np.random.randint(N)
+        current_wp = rng.integers(N)
         iter_set = [
             current_wp,
         ]
@@ -319,7 +322,7 @@ def _compute_pseudotime(
     waypoints: pd.Index,
     n_jobs: int,
     max_iterations: int = 25,
-) -> Tuple[pd.Series, pd.DataFrame]:
+) -> tuple[pd.Series, pd.DataFrame]:
     """Compute pseudotime and weight matrix using shortest path distances.
 
     This function constructs a kNN graph and computes shortest path distances from
@@ -343,7 +346,7 @@ def _compute_pseudotime(
 
     Returns
     -------
-    Tuple[pd.Series, pd.DataFrame]
+    tuple[pd.Series, pd.DataFrame]
         pseudotime : pd.Series
             Pseudotime ordering of cells.
         W : pd.DataFrame
@@ -408,8 +411,8 @@ def identify_terminal_states(
     num_waypoints: int = 1200,
     n_jobs: int = -1,
     max_iterations: int = 25,
-    seed: int = 20,
-) -> Tuple[np.ndarray, pd.Index]:
+    seed: int | np.ndarray | np.random.Generator | BitGenerator | SeedSequence | RandomState | None = 20,
+) -> tuple[np.ndarray, pd.Index]:
     """
     Identify terminal states from multi-scale data.
     
@@ -430,12 +433,12 @@ def identify_terminal_states(
         Number of jobs for parallel processing. Default is -1.
     max_iterations : int, optional
         Maximum number of iterations for pseudotime convergence. Default is 25.
-    seed : int, optional
+    seed : int | np.ndarray | np.random.Generator | BitGenerator | SeedSequence | RandomState | None, optional
         Random seed for waypoint sampling. Default is 20.
         
     Returns
     -------
-    Tuple[np.ndarray, pd.Index]
+    tuple[np.ndarray, pd.Index]
         terminal_states : np.ndarray
             Array of identified terminal state cells.
         excluded_boundaries : pd.Index
@@ -650,12 +653,12 @@ def _terminal_states_from_markov_chain(
 
 
 def _differentiation_entropy(
-    wp_data: pd.DataFrame, 
-    terminal_states: Optional[np.ndarray], 
-    knn: int, 
-    n_jobs: int, 
-    pseudotime: pd.Series
-) -> Tuple[pd.Series, pd.DataFrame]:
+    wp_data: pd.DataFrame,
+    terminal_states: np.ndarray | None,
+    knn: int,
+    n_jobs: int,
+    pseudotime: pd.Series,
+) -> tuple[pd.Series, pd.DataFrame]:
     """Compute entropy and branch probabilities from a Markov chain.
 
     This function constructs a Markov chain from waypoints data and computes 
@@ -665,7 +668,7 @@ def _differentiation_entropy(
     ----------
     wp_data : pd.DataFrame
         Multi-scale data of the waypoints.
-    terminal_states : Optional[np.ndarray]
+    terminal_states : np.ndarray, optional
         Terminal states to use for probability calculations. If None, they will be
         automatically detected.
     knn : int
@@ -677,7 +680,7 @@ def _differentiation_entropy(
 
     Returns
     -------
-    Tuple[pd.Series, pd.DataFrame]
+    tuple[pd.Series, pd.DataFrame]
         entropy : pd.Series
             Differentiation entropy for each cell.
         branch_probs : pd.DataFrame

src/palantir/plot_utils.py

@@ -281,8 +281,9 @@ def color_generator(exclude):
                     yield clr
             hex_digits = np.array(list("0123456789ABCDEF"))
             # If default cycle is exhausted, generate random colors.
+            rng = np.random.default_rng()
             while True:
-                new_color = "#" + "".join(np.random.choice(hex_digits, size=6))
+                new_color = "#" + "".join(rng.choice(hex_digits, size=6))
                 if new_color not in exclude:
                     yield new_color