brisc 0.2.3__tar.gz → 0.2.4__tar.gz

{brisc-0.2.3 → brisc-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brisc
-Version: 0.2.3
+Version: 0.2.4
 Summary: Fast single-cell toolkit
 Author-email: Michael Wainberg <m.wainberg@utoronto.ca>
 License-Expression: MIT

{brisc-0.2.3 → brisc-0.2.4}/brisc/harmonize.pyx

@@ -372,8 +372,7 @@ def harmony(const float[:, ::1] PCs,
     cdef float base, kmeans_error, entropy_term, norm, Rij, \
         diversity_penalty, prev_objective, total, Pr_bi, Eij, Oij, Rkj, \
         objective, last_two, old, new, ridge_lambda, factor, beta, \
-        two_over_sigma = <float> 2 / sigma, half_sigma = sigma / <float> 2, \
-        exp_neg_two_over_sigma = exp(-two_over_sigma)
+        two_over_sigma = <float> 2 / sigma, half_sigma = sigma / <float> 2
     cdef float past_clustering_objectives[3]
     cdef bint compute_objective, compute_Y, converged, cold_start
     cdef str metrics
@@ -471,8 +470,8 @@ def harmony(const float[:, ::1] PCs,
         if tau:
             for i in range(num_batches):
                 Pr_b[i] = <float> N_b[i] / num_cells
-                base = exp(-(<float> N_b[i]) / (num_clusters * tau))
-                theta_batch[i] = theta * (<float> 1 - base * base)
+                base = (<float> N_b[i]) / (num_clusters * tau)
+                theta_batch[i] = theta * (<float> 1 - exp(-base * base))
         else:
             for i in range(num_batches):
                 Pr_b[i] = <float> N_b[i] / num_cells
@@ -568,7 +567,9 @@ def harmony(const float[:, ::1] PCs,
                             kmeans_error = kmeans_error + Rij * (
                                 <float> 1 - half_sigma *
                                 distances[thread_index, i, j])
-                            entropy_term = entropy_term + Rij * log(Rij)
+                            # Skip entries of `R` that underflowed to 0
+                            if Rij > <float> 0:
+                                entropy_term = entropy_term + Rij * log(Rij)
                             distances[thread_index, i, j] = Rij
                     beta = piece > slab_piece_offsets[slab]
                     matrix_multiply(
@@ -667,11 +668,12 @@ def harmony(const float[:, ::1] PCs,
                 # then chunkwise within each block. Note that the full formula
                 # for `R` is: `((E + 1) / (O + E + 1)) ** theta *
                 #              exp(-2 / sigma * (1 - Z @ Y.T))`
-                # which we can calculate as `ratio * exp(distances)` where
-                # `ratio = exp(-2 / sigma) *
-                #          ((E + 1) / (O + E + 1)) ** theta` and
-                # `distances = 2 / sigma * Z @ Y.T`. Calculating `R` this way
-                # saves a few multiplications.
+                # which we calculate as `ratio * exp(distances - 2 / sigma)`
+                # where `ratio = ((E + 1) / (O + E + 1)) ** theta` and
+                # `distances = 2 / sigma * Z @ Y.T`. Since the rows of `Z` and
+                # `Y` have unit norm, the exponent is never positive, so
+                # `exp()` can underflow but never overflow, even when `sigma`
+                # is small.
                 #
                 # If we are done clustering or `early_stopping=True`, also
                 # compute the first two components of the objective function,
@@ -701,8 +703,7 @@ def harmony(const float[:, ::1] PCs,
 
                             # Get the chunk of `Z`, the normalized PCs, to
                             # process. Calculate the observed-to-expected ratio
-                            # `ratio = exp(-2 / sigma) *
-                            #          ((E + 1) / (O + E + 1)) ** theta`
+                            # `ratio = ((E + 1) / (O + E + 1)) ** theta`
                             # for the chunk, subtracting the chunk's own
                             # contributions to `E` and `O`: `Pr_b` times
                             # `R_sums[chunk_index]` and `delta_O[chunk_index]`,
@@ -727,11 +728,10 @@ def harmony(const float[:, ::1] PCs,
                                     Eij = E[i, j] - \
                                         Pr_bi * R_sums[chunk_index, j]
                                     Oij = O[i, j] + delta_O[chunk_index, i, j]
-                                    ratio[chunk_index, i, j] = \
-                                        exp_neg_two_over_sigma * \
-                                        pow((Eij + <float> 1) /
-                                            (Oij + Eij + <float> 1),
-                                            theta_batch[i])
+                                    ratio[chunk_index, i, j] = pow(
+                                        (Eij + <float> 1) /
+                                        (Oij + Eij + <float> 1),
+                                        theta_batch[i])
 
                             # Compute `distances = 2 / sigma * Z @ Y.T`
                             matrix_multiply(
@@ -758,7 +758,8 @@ def harmony(const float[:, ::1] PCs,
                                 norm = 0
                                 for j in range(num_clusters):
                                     R[k, j] = exp(distances[
-                                        thread_index, i, j]) * \
+                                        thread_index, i, j] -
+                                        two_over_sigma) * \
                                         ratio[chunk_index, batch_label, j]
                                     norm += R[k, j]
                                 norm = <float> 1 / norm
@@ -779,8 +780,11 @@ def harmony(const float[:, ::1] PCs,
                                         kmeans_error = kmeans_error + Rkj * (
                                             <float> 1 - half_sigma *
                                             distances[thread_index, i, j])
-                                        entropy_term = \
-                                            entropy_term + Rkj * log(Rkj)
+                                        # Skip entries of `R` that
+                                        # underflowed to 0
+                                        if Rkj > <float> 0:
+                                            entropy_term = entropy_term + \
+                                                Rkj * log(Rkj)
                                 kmeans_errors[slot] = kmeans_error
                                 entropy_terms[slot] = entropy_term
                             if compute_Y:
@@ -889,10 +893,12 @@ def harmony(const float[:, ::1] PCs,
                     with gil:
                         PyErr_CheckSignals()
 
-            # If Harmony has converged, this is the last iteration, so the
-            # embeddings are not normalized. Unless this is the last iteration,
-            # recompute `R`, `O`, and `E` from the corrected embeddings before
-            # the next round of clustering (a "cold start"), as Harmony2 does.
+            # Unless this is the last iteration (because we have converged or
+            # `max_iterations` has been reached), normalize the corrected
+            # embeddings and recompute `R`, `O`, and `E` from them before the
+            # next round of clustering (a "cold start"). On the last
+            # iteration, leave the embeddings unnormalized, so that the
+            # corrected PCs are returned either way.
             converged = prev_objective - objective < \
                 tolerance * abs(prev_objective)
             cold_start = not converged and iteration < max_iterations
@@ -991,10 +997,9 @@ def harmony(const float[:, ::1] PCs,
                             W[i, k, j] = factor * (
                                 W[i, k, j] - O[i, k] * intercepts[k, j])
 
-            # Correct `Z` slab by slab. Unless Harmony has converged, also
-            # normalize each row of `Z`. For a cold start, also recompute `R`,
-            # each slab's contributions to `O`, and each slab's partial sum of
-            # `R.T @ Z` for the next `Y`.
+            # Correct `Z` slab by slab. For a cold start, also normalize each
+            # row of `Z` and recompute `R`, each slab's contributions to `O`,
+            # and each slab's partial sum of `R.T @ Z` for the next `Y`.
             with parallel(num_threads=num_threads_or_chunks):
                 thread_index = threadid()
                 for slab in prange(num_slabs):
@@ -1014,7 +1019,7 @@ def harmony(const float[:, ::1] PCs,
                             W[batch_label], Z_chunk[thread_index],
                             transpose_A=False, transpose_B=False, alpha=-1,
                             beta=1)
-                        if not converged:
+                        if cold_start:
                             for i in range(end_row - start_row):
                                 norm = 0
                                 for j in range(num_PCs):
@@ -1025,7 +1030,6 @@ def harmony(const float[:, ::1] PCs,
                                 for j in range(num_PCs):
                                     Z_chunk[thread_index, i, j] = \
                                         Z_chunk[thread_index, i, j] * norm
-                        if cold_start:
                             matrix_multiply(
                                 Z_chunk[thread_index, :end_row - start_row],
                                 Y, distances[thread_index], transpose_A=False,

{brisc-0.2.3 → brisc-0.2.4}/brisc/norm_factors.pyx

@@ -80,8 +80,7 @@ def calc_norm_factors(const numeric[:, ::1] X,
                       const unsigned ref_sample,
                       float[::1] norm_factors,
                       sum_type[::1] library_size,
-                      unsigned num_threads,
-                      const bint is_win):
+                      unsigned num_threads):
     cdef numeric ref_count, count
     cdef sum_type ref_library_size
     cdef unsigned i, j, n, loL, hiL, loS, hiS, thread_index, start_sample, \
@@ -126,11 +125,9 @@ def calc_norm_factors(const numeric[:, ::1] X,
         log_normalized_X_ref[j] = \
             log2(<float> count * inverse_ref_library_size)
 
-    # Calculate the normalization factor for each sample. Force the parallel
-    # path for Windows for floating-point consistency between 1 and multiple
-    # threads.
+    # Calculate the normalization factor for each sample
     num_threads = min(num_threads, num_samples)
-    if num_threads <= 1 and not is_win:
+    if num_threads <= 1:
         logR_buffer.resize(num_genes)
         absE_buffer.resize(num_genes)
         logR_rank_buffer.resize(num_genes)

{brisc-0.2.3 → brisc-0.2.4}/brisc/pseudobulk.py

@@ -4,7 +4,6 @@ import os
 import polars as pl
 import re
 import shutil
-import sys
 from collections.abc import Iterable
 from itertools import islice, pairwise
 from pathlib import Path
@@ -4252,11 +4251,10 @@ class Pseudobulk:
 
         # Calculate norm factors
         norm_factors = np.empty(num_samples, dtype=np.float32)
-        is_win = sys.platform == 'win32'
         calc_norm_factors(X=X, logratio_trim=logratio_trim, sum_trim=sum_trim,
                           A_cutoff=A_cutoff, ref_sample=ref_sample,
                           norm_factors=norm_factors, library_size=library_size,
-                          num_threads=num_threads, is_win=is_win)
+                          num_threads=num_threads)
 
         return norm_factors  # this is actually `library_size * norm_factors`
 

{brisc-0.2.3 → brisc-0.2.4}/brisc/single_cell.py

@@ -13333,7 +13333,7 @@ class SingleCell:
                   oversampling_factor: int | np.integer | float |
                                        np.floating = 1,
                   chunk_size_kmeans: int | np.integer | None = None,
-                  max_clustering_iterations: int | np.integer = 5,
+                  max_clustering_iterations: int | np.integer = 4,
                   block_proportion: int | float | np.integer |
                                     np.floating = 0.05,
                   tolerance: int | float | np.integer | np.floating = 0.01,
@@ -13355,52 +13355,12 @@ class SingleCell:
         multiple batches of the same dataset, with
         [Harmony2](https://github.com/immunogenomics/harmony).
 
-        Our implementation differs from the original Harmony2 implementation in
-        three key ways:
-
-        First, we parallelize Harmony via an innovative nested block strategy.
-        The original implementation partitions cells randomly into blocks, each
-        containing a fixed fraction (`block_proportion`, 5% by default) of the
-        total cells. It iterates over each block, subtracting the contribution
-        of the cells in the block to the observed and expected cluster-batch
-        co-occurence matrices `O` and `E`, re-calculating the soft-clustering
-        assignments `R` based on the residual `O` and `E`, then adding back the
-        contribution of the cells in the block to `O` and `E` based on the new
-        `R`. This approach resists straightforward parallelization because
-        updates to `R` for future blocks depend on updates to `O` and `E` from
-        previous blocks, leading to convergence failure if naively
-        parallelized. Instead, we parallelize within blocks by dividing them
-        into chunks of `chunk_size_Harmony` cells. We process each chunk in
-        parallel, subtracting only the `O` and `E` contributions of the chunk
-        itself, updating `R` for the chunk, and, after processing all chunks in
-        the block, add back the `O` and `E` contributions for all chunks based
-        on the updated `R`. Updating `O` and `E` at the end of each block
-        (rather than after processing every cell in the dataset) ensures
-        convergence, while the inner chunking enables parallelization without
-        disrupting convergence. To use the original implementation's strategy
-        of updating `R`, `O`, and `E` for each block as a whole, set
-        `chunk_size_Harmony` to at least the block size (`block_proportion`
-        times the total number of cells, rounded up to a multiple of 16), at
-        the cost of no longer parallelizing the update of `R`.
-
-        Second, we reduce the default number of clustering iterations
-        (Harmony's inner loop) from 20 to 5, but always complete all 5
-        iterations without early stopping based on convergence. In practice,
-        the largest changes to the Harmony objective function result from
-        updating the PCs (outer loop), not updating the soft-clustering
-        assignments (inner loop). Our implementation makes updating the PCs
-        sufficiently fast that there are rapidly diminishing returns from
-        performing lots of clustering updates, versus just skipping directly to
-        updating the PCs after a few clustering iterations. To use the original
-        implementation's default of 20 iterations with early stopping, specify
-        `early_stopping=True, max_clustering_iterations=20`.
-
-        Third, we use random k-means initialization, like version 1 of Harmony,
-        rather than Harmony2's kmeans++ initialization. We implement a parallel
-        version of kmeans++ called [k-means||](https://arxiv.org/abs/1203.6402),
-        but find it does not improve the accuracy of label transfer relative to
-        random initialization and increases runtime. kmeans|| initialization can
-        be enabled with `kmeans_barbar=True`.
+        Unlike Harmony2, our implementation parallelizes the clustering step
+        within each block of cells, by dividing each block into chunks of
+        `chunk_size_Harmony` cells that are updated in parallel. It also uses
+        random k-means initialization rather than k-means++ (initialization
+        with k-means||, a parallel version of k-means++, can be enabled with
+        `kmeans_barbar=True`).
 
         Args:
             others: the other SingleCell datasets to harmonize this one with.
@@ -13448,20 +13408,15 @@ class SingleCell:
                           30 and 3000 cells.
             max_iterations: the maximum number of iterations to run Harmony
                             for, if convergence is not achieved. Defaults to
-                            10, like the original Harmony R package,
-                            harmony-pytorch, and harmonypy. Set to `None` to
-                            use as many iterations as necessary to achieve
-                            convergence.
+                            10. Set to `None` to use as many iterations as
+                            necessary to achieve convergence.
             num_kmeans_iterations: the maximum number of iterations of
-                                   k-means clustering to perform before
-                                   starting the nearest-neighbor search,
-                                   stopping early if a relative convergence of
+                                   k-means clustering to perform to
+                                   initialize the cluster centroids, stopping
+                                   early if a relative convergence of
                                    `kmeans_tolerance` is reached. Defaults to
-                                   25, like the original Harmony R package,
-                                   harmony-pytorch, and harmonypy. However,
-                                   unlike these packages, only one
-                                   initialization is tried rather than 10 to
-                                   reduce runtime.
+                                   25, whereas Harmony2 always runs 10
+                                   iterations without early stopping.
             kmeans_tolerance: the relative change in inertia (the sum of
                               squared distances from each cell to its assigned
                               centroid) used to determine whether to stop
@@ -13504,19 +13459,13 @@ class SingleCell:
                                        clustering step within each Harmony
                                        iteration for, or the maximum number of
                                        iterations if `early_stopping=True`.
-                                       Unlike the original Harmony algorithm,
-                                       convergence of the clustering is not
+                                       Convergence of the clustering is not
                                        checked unless `early_stopping=True`.
-                                       Defaults to 5 iterations; this differs
-                                       from the 20 used by the original harmony
-                                       R package and harmonypy and the 200
-                                       iterations used by harmony-pytorch,
-                                       which do have convergence checks.
-                                       Must be 4 or more when
-                                       `early_stopping=True`, since Harmony's
-                                       clustering convergence check requires
-                                       knowing the errors from the past 3
-                                       iterations.
+                                       Defaults to 4 iterations. Must be 4 or
+                                       more when `early_stopping=True`, since
+                                       the clustering convergence check
+                                       requires knowing the errors from the
+                                       past 3 iterations.
             block_proportion: the proportion of cells to use in each batch
                               update in the clustering step; must be greater
                               than zero and less than or equal to 1
@@ -13525,8 +13474,7 @@ class SingleCell:
                        `max_iterations` iterations
             early_stopping: whether to stop clustering before
                             `max_clustering_iterations` iterations if
-                            convergence is reached, like in the original
-                            Harmony algorithm
+                            convergence is reached.
             clustering_tolerance: the relative tolerance used to determine
                                   whether to stop clustering before
                                   `max_clustering_iterations` iterations. Only

{brisc-0.2.3 → brisc-0.2.4}/brisc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brisc
-Version: 0.2.3
+Version: 0.2.4
 Summary: Fast single-cell toolkit
 Author-email: Michael Wainberg <m.wainberg@utoronto.ca>
 License-Expression: MIT

brisc-0.2.4/brisc.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.2.4",
+  "distance": 0,
+  "node": "gba159a34ecfeeba309d63514d0ed75ab859226c3",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-31"
+}

brisc-0.2.3/brisc.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.2.3",
-  "distance": 0,
-  "node": "g7458aedfcaa8dbcfe4436b468bd19a068abbe8ae",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-10-25"
-}