SigProfilerExtractor 1.4.1__tar.gz → 1.5.0__tar.gz

{sigprofilerextractor-1.4.1 → sigprofilerextractor-1.5.0}/CHANGELOG.md

@@ -5,11 +5,36 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.5.0] - 2026-09-28
 
 ### Changed
 - Updated the default COSMIC reference signature version from 3.5 to 3.6.
 - Updated the minimum SigProfilerAssignment version to 1.1.5 for COSMIC v3.6 support.
+- Changed the CLI default for `--maximum_signatures` from 10 to 25 so it matches the Python API.
+- GPU batches now give every NMF replicate its own resampling and initialization generators, sample totals, and convergence stopping point, matching CPU and single-replicate GPU behavior.
+- A seeds file now contains exactly one root seed. All random generators used by a run are derived reproducibly from that seed.
+- Existing results for a mutation context are moved to `<context>_previous_<timestamp>` before a rerun writes new results, preventing files from different runs from being mixed.
+- Importing SigProfilerExtractor no longer suppresses warnings globally or changes the host program's multiprocessing start method.
+
+### Fixed
+- Added a lower bound (1e-16) to W, H and W @ H in the KL multiplicative updates, on CPU and GPU. A multiplicative update cannot move an entry away from exactly zero, so zeros from the NNDSVD initialization (about half of W and H) or from underflow stayed zero for the whole run. The fit could then stall and pass the convergence test early at a worse solution; with `nmf_init="nndsvd"` this could happen at the first allowed convergence check. Results and run times can change, including with the default random initialization.
+- Fixed the KL loss returning NaN when the matrix passed to NMF contains a zero (`0 * log 0`). The extraction pipeline raises every value to at least 1e-4 before NMF, so this affected only direct use of `nmf_cpu` and `nmf_gpu`.
+- If a cell of W @ H reached zero, the update produced inf or NaN that spread to all of W and H with no error. An NMF replicate whose W or H contains NaN or inf now raises `FloatingPointError` instead of entering clustering.
+- CPU extraction now runs the requested number of NMF replicates when `batch_size` is greater than 1. The setting only controls GPU batching.
+- Forwarded `nnls_add_penalty`, `nnls_remove_penalty`, `initial_remove_penalty`, and `collapse_to_SBS96` to SigProfilerAssignment.
+- Recomputed the signature-rank range for each mutation context so a context with fewer samples cannot narrow the range used by subsequent contexts.
+- Seeded the Gaussian mixture model used to choose the normalization cutoff, making it reproducible from `Seeds.txt`.
+- Stopped treating failed silhouette calculations as perfect stability. Rank one remains stable by convention; invalid higher-rank calculations now raise a clear error.
+- Removed two unused per-replicate arrays that could each consume several gigabytes for large mutation matrices.
+- Validated `matrix_normalization`. Accepted values are `"gmm"`, `"100X"`, `"log2"`, `"none"`, or a positive integer cutoff; unsupported values now raise `ValueError`.
+- Samples containing some missing values now raise a clear error instead of being dropped silently. Completely empty columns and samples with zero mutations are reported and removed.
+- Preserved input values as float64 throughout NMF when `precision="double"` is selected.
+- Labelled matrices with unrecognized channel counts as `CH<n>` instead of incorrectly labelling every such matrix as SBS.
+- Fixed loading `Seeds.txt` with current NumPy versions and added clear validation for a missing `Seed` column or more than one root seed.
+- A run now raises an error instead of reporting success when none of the requested mutation contexts can be analyzed.
+- Rounded exported NMF activities to the nearest integer instead of truncating them.
+- Made the `SV_Matrices` output location independent of whether a BEDPE input directory has a trailing slash.
+- Unified CPU and GPU per-replicate diagnostics so both paths calculate them from the matrix actually fitted by NMF.
 
 ## [1.2.7] - 2026-01-22
 

{sigprofilerextractor-1.4.1 → sigprofilerextractor-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SigProfilerExtractor
-Version: 1.4.1
+Version: 1.5.0
 Summary: Extracts mutational signatures from mutational catalogues
 Home-page: https://github.com/SigProfilerSuite/SigProfilerExtractor.git
 Author: S Mishu Ashiqul Islam
@@ -121,7 +121,7 @@ Extracts mutational signatures from an array of samples.
 
 ```python 
 sigProfilerExtractor(input_type, out_put, input_data, reference_genome="GRCh37", opportunity_genome = "GRCh37", cosmic_version=3.6, context_type = "default", exome = False,
-                         minimum_signatures=1, maximum_signatures=10, nmf_replicates=100, resample = True, batch_size=1, cpu=-1, gpu=False, 
+                         minimum_signatures=1, maximum_signatures=25, nmf_replicates=100, resample = True, batch_size=1, cpu=-1, gpu=False,
                          nmf_init="random", precision= "single", matrix_normalization= "gmm", seeds= "random", 
                          min_nmf_iterations= 10000, max_nmf_iterations=1000000, nmf_test_conv= 10000, nmf_tolerance= 1e-15, get_all_signature_matrices= False)
 ```
@@ -141,9 +141,9 @@ sigProfilerExtractor(input_type, out_put, input_data, reference_genome="GRCh37",
 |  | **maximum_signatures** | Positive Integer | The maximum number of signatures to be extracted (default: `25`). |
 |  | **nmf_replicates** | Positive Integer | The number of iteration to be performed to extract each number signature (default: `100`). |
 |  | **resample** | Boolean | If `True`, add poisson noise to samples by resampling (default: `True`). |
-|  | **seeds** | String | Ensures reproducible NMF replicate resamples. Provide the path to the `Seeds.txt` file (found in the results folder from a previous analysis) to reproduce results (default: `"random"`). |
+|  | **seeds** | String | Ensures reproducible NMF resampling and initialization. Provide the path to a `Seeds.txt` file containing exactly one root seed in the `Seed` column (the file generated by a previous analysis can be reused) to reproduce results (default: `"random"`). |
 | **NMF Engines** |  |  |  | 
-|  | **matrix_normalization** | String | Method of normalizing the genome matrix before it is analyzed by NMF (default: `"gmm"`). Options are, `"log2"`, `"custom"` or `"none"`. |
+|  | **matrix_normalization** | String | Method of normalizing the genome matrix before it is analyzed by NMF (default: `"gmm"`). Options are `"100X"`, `"log2"`, `"none"`, or a positive integer used as a manual cutoff (for example `5000`). |
 |  | **nmf_init** | String | The initialization algorithm for W and H matrix of NMF (default: `"random"`). Options are `"random"`, `"nndsvd"`, `"nndsvda"`, `"nndsvdar"` and `"nndsvd_min"`. |
 |  | **precision** | String | Values should be single or double (default: `"single"`). |
 |  | **min_nmf_iterations** | Integer | Value defines the minimum number of iterations to be completed before NMF converges (default: `10000`). |
@@ -154,7 +154,7 @@ sigProfilerExtractor(input_type, out_put, input_data, reference_genome="GRCh37",
 |  | **cpu** | Integer | The number of processors to be used to extract the signatures (default: all processors). |
 |  | **assignment_cpu** | Integer | Number of processors to be used by SigProfilerAssignment for the final signature assignment step (default: all available). This is independent of the `cpu` parameter. |
 |  | **gpu** | Boolean | Defines if the GPU resource will used if available (default: `False`). If `True`, the GPU resources will be used in the computation. *Note: All available CPU processors are used by default, which may cause a memory error. This error can be resolved by reducing the number of CPU processes through the `cpu` parameter.*|
-|  | **batch_size** | Integer | Will be effective only if the GPU is used. Defines the number of NMF replicates to be performed by each CPU during the parallel processing (default: `1`). *Note: For `batch_size` values greater than 1, each NMF replicate will update until `max_nmf_iterations` is reached.*|
+|  | **batch_size** | Integer | Effective only when the GPU is used. Defines how many NMF replicates are grouped into each GPU batch (default: `1`). Every replicate has its own resampling and initialization generators, sample totals, and convergence stopping point, whether it runs alone or in a batch. |
 | **Solution Estimation Thresholds** |  |  |  | 
 |  | **stability** | Float | The cutoff thresh-hold of the average stability (default: `0.8`). Solutions with average stabilities below this thresh-hold will not be considered. |
 |  | **min_stability** | Float | The cutoff thresh-hold of the minimum stability (default: `0.2`). Solutions with minimum stabilities below this thresh-hold will not be considered.  |

{sigprofilerextractor-1.4.1 → sigprofilerextractor-1.5.0}/README.md

@@ -89,7 +89,7 @@ Extracts mutational signatures from an array of samples.
 
 ```python 
 sigProfilerExtractor(input_type, out_put, input_data, reference_genome="GRCh37", opportunity_genome = "GRCh37", cosmic_version=3.6, context_type = "default", exome = False,
-                         minimum_signatures=1, maximum_signatures=10, nmf_replicates=100, resample = True, batch_size=1, cpu=-1, gpu=False, 
+                         minimum_signatures=1, maximum_signatures=25, nmf_replicates=100, resample = True, batch_size=1, cpu=-1, gpu=False,
                          nmf_init="random", precision= "single", matrix_normalization= "gmm", seeds= "random", 
                          min_nmf_iterations= 10000, max_nmf_iterations=1000000, nmf_test_conv= 10000, nmf_tolerance= 1e-15, get_all_signature_matrices= False)
 ```
@@ -109,9 +109,9 @@ sigProfilerExtractor(input_type, out_put, input_data, reference_genome="GRCh37",
 |  | **maximum_signatures** | Positive Integer | The maximum number of signatures to be extracted (default: `25`). |
 |  | **nmf_replicates** | Positive Integer | The number of iteration to be performed to extract each number signature (default: `100`). |
 |  | **resample** | Boolean | If `True`, add poisson noise to samples by resampling (default: `True`). |
-|  | **seeds** | String | Ensures reproducible NMF replicate resamples. Provide the path to the `Seeds.txt` file (found in the results folder from a previous analysis) to reproduce results (default: `"random"`). |
+|  | **seeds** | String | Ensures reproducible NMF resampling and initialization. Provide the path to a `Seeds.txt` file containing exactly one root seed in the `Seed` column (the file generated by a previous analysis can be reused) to reproduce results (default: `"random"`). |
 | **NMF Engines** |  |  |  | 
-|  | **matrix_normalization** | String | Method of normalizing the genome matrix before it is analyzed by NMF (default: `"gmm"`). Options are, `"log2"`, `"custom"` or `"none"`. |
+|  | **matrix_normalization** | String | Method of normalizing the genome matrix before it is analyzed by NMF (default: `"gmm"`). Options are `"100X"`, `"log2"`, `"none"`, or a positive integer used as a manual cutoff (for example `5000`). |
 |  | **nmf_init** | String | The initialization algorithm for W and H matrix of NMF (default: `"random"`). Options are `"random"`, `"nndsvd"`, `"nndsvda"`, `"nndsvdar"` and `"nndsvd_min"`. |
 |  | **precision** | String | Values should be single or double (default: `"single"`). |
 |  | **min_nmf_iterations** | Integer | Value defines the minimum number of iterations to be completed before NMF converges (default: `10000`). |
@@ -122,7 +122,7 @@ sigProfilerExtractor(input_type, out_put, input_data, reference_genome="GRCh37",
 |  | **cpu** | Integer | The number of processors to be used to extract the signatures (default: all processors). |
 |  | **assignment_cpu** | Integer | Number of processors to be used by SigProfilerAssignment for the final signature assignment step (default: all available). This is independent of the `cpu` parameter. |
 |  | **gpu** | Boolean | Defines if the GPU resource will used if available (default: `False`). If `True`, the GPU resources will be used in the computation. *Note: All available CPU processors are used by default, which may cause a memory error. This error can be resolved by reducing the number of CPU processes through the `cpu` parameter.*|
-|  | **batch_size** | Integer | Will be effective only if the GPU is used. Defines the number of NMF replicates to be performed by each CPU during the parallel processing (default: `1`). *Note: For `batch_size` values greater than 1, each NMF replicate will update until `max_nmf_iterations` is reached.*|
+|  | **batch_size** | Integer | Effective only when the GPU is used. Defines how many NMF replicates are grouped into each GPU batch (default: `1`). Every replicate has its own resampling and initialization generators, sample totals, and convergence stopping point, whether it runs alone or in a batch. |
 | **Solution Estimation Thresholds** |  |  |  | 
 |  | **stability** | Float | The cutoff thresh-hold of the average stability (default: `0.8`). Solutions with average stabilities below this thresh-hold will not be considered. |
 |  | **min_stability** | Float | The cutoff thresh-hold of the minimum stability (default: `0.2`). Solutions with minimum stabilities below this thresh-hold will not be considered.  |

sigprofilerextractor-1.5.0/SigProfilerExtractor/_version.py

@@ -0,0 +1 @@
+version = '1.5.0'

{sigprofilerextractor-1.4.1 → sigprofilerextractor-1.5.0}/SigProfilerExtractor/controllers/cli_controller.py

@@ -77,8 +77,11 @@ def parse_arguments_extractor(args: List[str], description: str) -> argparse.Nam
     parser.add_argument(
         "--maximum_signatures",
         type=int,
-        default=10,
-        help="Maximum number of signatures to be extracted (default: 10).",
+        default=sigpro.DEFAULT_MAXIMUM_SIGNATURES,
+        help=(
+            "Maximum number of signatures to be extracted "
+            f"(default: {sigpro.DEFAULT_MAXIMUM_SIGNATURES})."
+        ),
     )
     parser.add_argument(
         "--nmf_replicates",
@@ -97,13 +100,21 @@ def parse_arguments_extractor(args: List[str], description: str) -> argparse.Nam
     parser.add_argument(
         "--seeds",
         default="random",
-        help="Seeds for reproducible resamples, file path or 'random' (default: 'random').",
+        help=(
+            "Root seed source for reproducible NMF resampling and initialization: "
+            "a path to a Seeds.txt file containing one root seed in the Seed "
+            "column, or 'random' (default: 'random')."
+        ),
     )
     parser.add_argument(
         "--batch_size",
         type=int,
         default=1,
-        help="Batch size is for GPU only and defines the number of NMF replicates to be performed by each CPU during parallel processing (default: 1).",
+        help=(
+            "Number of NMF replicates grouped into each GPU batch. GPU only; "
+            "replicates keep independent resampling and initialization generators, "
+            "sample totals, and convergence stopping points (default: 1)."
+        ),
     )
     parser.add_argument(
         "--cpu",
@@ -138,7 +149,7 @@ def parse_arguments_extractor(args: List[str], description: str) -> argparse.Nam
     parser.add_argument(
         "--matrix_normalization",
         default="gmm",
-        help="Method of normalizing the genome matrix before it is analyzed by NMF (default: 'gmm'). Options are 'custom', 'gmm', 'log2', or 'none'.",
+        help="Method of normalizing the genome matrix before it is analyzed by NMF (default: 'gmm'). Options are 'gmm', '100X', 'log2', 'none', or a positive integer used as a manual cutoff (for example 5000).",
     )
     parser.add_argument(
         "--min_nmf_iterations",

{sigprofilerextractor-1.4.1 → sigprofilerextractor-1.5.0}/SigProfilerExtractor/nmf_cpu.py

@@ -17,6 +17,15 @@ import torch
 import torch.nn
 from torch import nn
 
+# Lower bound for W, H and W @ H in the KL multiplicative updates. A multiplicative
+# update cannot move an entry away from exactly zero, so zeros from the NNDSVD
+# initialization or from underflow stay locked for the whole run; the fit can then
+# stall and pass the convergence test early at a worse solution. If a cell of W @ H
+# reaches zero, V / (W @ H) gives inf (NaN where V is also zero), which the next
+# matrix product spreads to every entry of W and H. The original CPU engine (nimfa)
+# applied an equivalent floor after every iteration.
+EPSILON = 1e-16
+
 
 class NMF:
     def __init__(
@@ -178,10 +187,13 @@ class NMF:
     @property
     def _kl_loss(self):
         # calculate kl_loss in double precision for better convergence criteria
+        # xlogy gives 0 where V == 0, where V * log(V / WH) would give NaN. pnmf()
+        # raises V to at least 1e-4, so this matters only when NMF is called directly.
+        reconstruction = self.reconstruction.clamp(min=EPSILON)
         return (
-            (self._V * (self._V / self.reconstruction).log()).sum(dtype=torch.float64)
+            torch.xlogy(self._V, self._V / reconstruction).sum(dtype=torch.float64)
             - self._V.sum(dtype=torch.float64)
-            + self.reconstruction.sum(dtype=torch.float64)
+            + reconstruction.sum(dtype=torch.float64)
         )
 
     @property
@@ -245,15 +257,17 @@ class NMF:
                 ones = torch.ones(self._V.shape).type(self._tensor_type)
                 for self._iter in range(self.max_iterations):
                     ht = self.H.transpose(1, 2)
-                    numerator = (self._V / (self.W @ self.H)) @ ht
+                    numerator = (self._V / (self.W @ self.H).clamp(min=EPSILON)) @ ht
 
-                    denomenator = ones @ ht
+                    denomenator = (ones @ ht).clamp(min=EPSILON)
                     self._W *= numerator / denomenator
+                    self._W.clamp_(min=EPSILON)
 
                     wt = self.W.transpose(1, 2)
-                    numerator = wt @ (self._V / (self.W @ self.H))
-                    denomenator = wt @ ones
+                    numerator = wt @ (self._V / (self.W @ self.H).clamp(min=EPSILON))
+                    denomenator = (wt @ ones).clamp(min=EPSILON)
                     self._H *= numerator / denomenator
+                    self._H.clamp_(min=EPSILON)
                     if stop_iterations()[0]:
                         self._conv = stop_iterations()[1]
                         break

{sigprofilerextractor-1.4.1 → sigprofilerextractor-1.5.0}/SigProfilerExtractor/nmf_gpu.py

@@ -10,6 +10,15 @@ import torch
 import torch.nn
 from torch import nn
 
+# Lower bound for W, H and W @ H in the KL multiplicative updates. A multiplicative
+# update cannot move an entry away from exactly zero, so zeros from the NNDSVD
+# initialization or from underflow stay locked for the whole run; the fit can then
+# stall and pass the convergence test early at a worse solution. If a cell of W @ H
+# reaches zero, V / (W @ H) gives inf (NaN where V is also zero), which the next
+# matrix product spreads to every entry of W and H. The original CPU engine (nimfa)
+# applied an equivalent floor after every iteration.
+EPSILON = 1e-16
+
 
 class NMF:
     def __init__(
@@ -79,7 +88,32 @@ class NMF:
         """
         Initialise basis and coefficient matrices according to `init_method`
         """
-        if init_method == "random":
+        if init_method == "random" and isinstance(self._generator, (list, tuple)):
+            # each replicate draws its W and then its H from its own generator, in
+            # the same order as nmf_cpu, so it starts from the same point on CPU
+            # and GPU however it is batched
+            if len(self._generator) != self._V.shape[0]:
+                raise ValueError("One generator per replicate is required.")
+            W = np.stack(
+                [
+                    g.random((self._V.shape[1], self._rank), dtype=np.float64)
+                    for g in self._generator
+                ]
+            )
+            H = np.stack(
+                [
+                    g.random((self._rank, self._V.shape[2]), dtype=np.float64)
+                    for g in self._generator
+                ]
+            )
+            W = torch.from_numpy(W).cuda()
+            H = torch.from_numpy(H).cuda()
+            if self._np_dtype is np.float32:
+                W = W.float()
+                H = H.float()
+            return W, H
+
+        elif init_method == "random":
             W = torch.from_numpy(
                 self._generator.random(
                     (self._V.shape[0], self._V.shape[1], self._rank), dtype=np.float64
@@ -102,7 +136,7 @@ class NMF:
             for i in range(self._V.shape[0]):
                 vin = self._V.cpu().numpy()[i]
                 W[i, :, :], H[i, :, :] = nv.initialize(
-                    vin, self._rank, options={"flag": 0, "generator": self._generator}
+                    vin, self._rank, options={"flag": 0, "generator": self._replicate_generator(i)}
                 )
 
         elif init_method == "nndsvda":
@@ -112,7 +146,7 @@ class NMF:
             for i in range(self._V.shape[0]):
                 vin = self._V.cpu().numpy()[i]
                 W[i, :, :], H[i, :, :] = nv.initialize(
-                    vin, self._rank, options={"flag": 1, "generator": self._generator}
+                    vin, self._rank, options={"flag": 1, "generator": self._replicate_generator(i)}
                 )
 
         elif init_method == "nndsvdar":
@@ -122,7 +156,7 @@ class NMF:
             for i in range(self._V.shape[0]):
                 vin = self._V.cpu().numpy()[i]
                 W[i, :, :], H[i, :, :] = nv.initialize(
-                    vin, self._rank, options={"flag": 2, "generator": self._generator}
+                    vin, self._rank, options={"flag": 2, "generator": self._replicate_generator(i)}
                 )
         elif init_method == "nndsvd_min":
             W = np.zeros([self._V.shape[0], self._V.shape[1], self._rank])
@@ -130,7 +164,7 @@ class NMF:
             nv = Nndsvd()
             for i in range(self._V.shape[0]):
                 vin = self._V.cpu().numpy()[i]
-                w, h = nv.initialize(vin, self._rank, options={"flag": 2, "generator": self._generator})
+                w, h = nv.initialize(vin, self._rank, options={"flag": 2, "generator": self._replicate_generator(i)})
                 min_X = np.min(vin[vin > 0])
                 h[h <= min_X] = min_X
                 w[w <= min_X] = min_X
@@ -143,6 +177,12 @@ class NMF:
         H = torch.from_numpy(H).type(self._tensor_type).cuda(self._gpu_id)
         return W, H
 
+    def _replicate_generator(self, i):
+        """Generator of replicate i: its own one, or the one shared by the batch."""
+        if isinstance(self._generator, (list, tuple)):
+            return self._generator[i]
+        return self._generator
+
     @property
     def reconstruction(self):
         return self.W @ self.H
@@ -169,10 +209,13 @@ class NMF:
     @property
     def _kl_loss(self):
         # calculate kl_loss in double precision for better convergence criteria
+        # xlogy gives 0 where V == 0, where V * log(V / WH) would give NaN. pnmf()
+        # raises V to at least 1e-4, so this matters only when NMF is called directly.
+        reconstruction = self.reconstruction.clamp(min=EPSILON)
         return (
-            (self._V * (self._V / self.reconstruction).log()).sum(dtype=torch.float64)
+            torch.xlogy(self._V, self._V / reconstruction).sum(dtype=torch.float64)
             - self._V.sum(dtype=torch.float64)
-            + self.reconstruction.sum(dtype=torch.float64)
+            + reconstruction.sum(dtype=torch.float64)
         )
 
     @property
@@ -187,6 +230,47 @@ class NMF:
         self._prev_loss = self._kl_loss
         return False
 
+    def _replicate_kl_loss(self, i):
+        # _kl_loss of replicate i alone (the same expression, on a batch of one)
+        V = self._V[i : i + 1]
+        reconstruction = (self.W[i : i + 1] @ self.H[i : i + 1]).clamp(min=EPSILON)
+        return (
+            torch.xlogy(V, V / reconstruction).sum(dtype=torch.float64)
+            - V.sum(dtype=torch.float64)
+            + reconstruction.sum(dtype=torch.float64)
+        )
+
+    def _stop_converged_replicates(self):
+        """
+        The single-replicate stopping rule of _loss_converged, applied to every
+        replicate of the batch: every test_conv iterations, a replicate stops when
+        its relative loss change is below the tolerance and more than
+        min_iterations have run. A stopped replicate keeps its W and H, so each
+        replicate ends where it would have ended on its own.
+        """
+        if self._iter % self._test_conv != 0:
+            return
+        loss = torch.stack(
+            [self._replicate_kl_loss(i) for i in range(self._V.shape[0])]
+        )
+        if not self._iter:
+            self._loss_init = loss
+            self._prev_loss = loss
+            return
+        converged = ((self._prev_loss - loss) / self._loss_init) < self._tolerance
+        self._prev_loss = torch.where(converged, self._prev_loss, loss)
+        stop = converged & self._active & (self._iter > self.min_iterations)
+        self._replicate_conv[stop.cpu()] = self._iter
+        self._active &= ~stop
+
+    @property
+    def replicate_conv(self):
+        """Iteration at which each replicate converged (0 if it did not)."""
+        try:
+            return [int(c) for c in self._replicate_conv]
+        except AttributeError:
+            return [int(self.conv)] * self._V.shape[0]
+
     def fit(self, beta=1):
         """
         Fit the basis (W) and coefficient (H) matrices to the input matrix (V) using multiplicative updates and
@@ -232,20 +316,31 @@ class NMF:
                 ones = (
                     torch.ones(self._V.shape).type(self._tensor_type).cuda(self._gpu_id)
                 )
+                self._active = torch.ones(
+                    self._V.shape[0], dtype=torch.bool, device=self._V.device
+                )
+                self._replicate_conv = torch.zeros(self._V.shape[0], dtype=torch.long)
                 for self._iter in range(self.max_iterations):
+                    # replicates that have already converged keep their W and H
+                    active = self._active[:, None, None]
                     ht = self.H.transpose(1, 2)
-                    numerator = (self._V / (self.W @ self.H)) @ ht
+                    numerator = (self._V / (self.W @ self.H).clamp(min=EPSILON)) @ ht
 
-                    denomenator = ones @ ht
-                    self._W *= numerator / denomenator
+                    denomenator = (ones @ ht).clamp(min=EPSILON)
+                    W = (self.W * (numerator / denomenator)).clamp(min=EPSILON)
+                    self._W = torch.where(active, W, self._W)
 
                     wt = self.W.transpose(1, 2)
-                    numerator = wt @ (self._V / (self.W @ self.H))
-                    denomenator = wt @ ones
-                    self._H *= numerator / denomenator
-                    if stop_iterations()[0]:
-                        self._conv = stop_iterations()[1]
+                    numerator = wt @ (self._V / (self.W @ self.H).clamp(min=EPSILON))
+                    denomenator = (wt @ ones).clamp(min=EPSILON)
+                    H = (self.H * (numerator / denomenator)).clamp(min=EPSILON)
+                    self._H = torch.where(active, H, self._H)
+
+                    self._stop_converged_replicates()
+                    if not self._active.any():
                         break
+                if self._V.shape[0] == 1 and self._replicate_conv[0] > 0:
+                    self._conv = int(self._replicate_conv[0])
 
             else:
                 for self._iter in range(self.max_iterations):