SigProfilerExtractor 1.4.0__tar.gz → 1.5.0__tar.gz

{sigprofilerextractor-1.4.0 → sigprofilerextractor-1.5.0}/.github/workflows/ci.yml

@@ -70,7 +70,11 @@ jobs:
     - name: Install genome
       run: |
         python install_genome.py ${{ github.workspace }}/src/
-    
+
+    - name: Run unit tests
+      run: |
+        python -m unittest discover -s tests -v
+
     - name: Run tests
       run: |
         python3 test.py

sigprofilerextractor-1.5.0/CHANGELOG.md

@@ -0,0 +1,109 @@
+
+# Changelog
+
+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).
+
+## [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
+
+### Fixed
+- Fixed NumPy 2.0 compatibility issue by removing the `nimfa` dependency, which was incompatible with NumPy 2.0 due to use of deprecated `np.mat()` function.
+- Fixed pandas 3.12 compatibility issues:
+  - Updated `to_csv()` calls to use `sep` as keyword argument instead of positional argument
+  - Fixed `set_index()` calls to work with pandas 3.12's stricter type checking by converting StringArray to list
+  - Fixed `iloc` assignment for string conversion operations
+  - Fixed Series indexing to use `.iloc[0]` for positional access instead of `[0]` for label-based access
+- Fixed compatibility issues in SigProfilerAssignment and SigProfilerPlotting packages for pandas 3.12
+
+### Changed
+- Removed `nimfa` dependency and implemented NNDSVD initialization directly in the codebase.
+- Updated `sigProfilerPlotting` dependency to >=1.4.3 for pandas 3.12 compatibility.
+- Removed TMB debug file output.
+- Migrated CI/CD pipeline from Travis CI to GitHub Actions for improved reliability and modern workflow management.
+
+### Added
+- Added `SigProfilerExtractor/nndsvd.py` with standalone NNDSVD implementation supporting all variants (nndsvd, nndsvda, nndsvdar, nndsvd_min).
+
+## [1.2.6] - 2026-01-06
+
+### Changed
+- Updated default COSMIC version from 3.4 to 3.5. Added support for COSMIC v3.5 signatures in the `cosmic_version` parameter.
+- Updated SigProfilerAssignment dependency requirement from >=1.0.1 to >=1.1.0 to support COSMIC v3.5 signatures.
+
+## [1.2.5] - 2025-10-28
+
+### Added
+- Implemented a CI/CD pipeline with Travis CI to automate the building and publishing of Docker images to Docker Hub.
+- Added a Dockerfile to the repository for containerization. Documentation on how to use the Dockerfile needs to be added to the README.
+
+## [1.2.4] - 2025-10-20
+
+### Added
+- Added the `assignment_cpu` parameter to independently control the number of CPU cores used for the signature assignment step. This change enables full support for the parallel processing enhancements in **SigProfilerAssignment v1.0.0**, allowing for significant performance improvements and more granular resource control.
+
+## [1.2.3] - 2025-09-19
+
+### Added
+- Added support for rn7 and mm39 genomes in SigProfilerExtractor.
+
+## [1.2.2] - 2025-08-11
+
+### Added
+- Added mutation count and stability to 4608 plots in All_Solutions
+- Add a stop parameter to the CLI to stop after de novo extraction.
+
+## [1.2.1] - 2025-05-14
+
+### Fixed
+- Fixed an issue where the CLI was returning a non-zero exit code when the `--help` flag was passed.
+
+ ### Added
+- Added `pyproject.toml` for modern Python packaging support.
+
+## [1.2.0] - 2025-02-11
+
+### Changed
+- Updated dependencies: Now requires **Pandas >= 2.0.0**, **NumPy >= 2.0.0**, and **Python >= 3.9**.
+- Dropped support for **Python 3.8**
+- **Intel-based MacBooks are no longer supported** due to upstream changes in **PyTorch**, which has dropped support for macOS x86_64. Users with Intel-based MacBooks will need to migrate to Apple Silicon (M1/M2) or use a Linux-based development environment.
+
+## [1.1.25] - 2024-12-09
+
+### Added
+- Introduced a Command-Line Interface (CLI) for SigProfilerExtractor, enabling users to interact with the tool via terminal commands.
+
+### Updated
+- Improved the formatting of the parameter table for sigProfilerExtractor function for better readability and consistency.
+- The CI/CD badge link has been fixed.

{sigprofilerextractor-1.4.0 → sigprofilerextractor-1.5.0}/Dockerfile

@@ -9,6 +9,9 @@ RUN apt-get update && apt-get install -y \
     python3-pip python3-dev git && \
     apt-get clean && rm -rf /var/lib/apt/lists/*
 
+# Upgrade Ubuntu's packaging tools before invoking the PEP 517 build backend.
+RUN python3 -m pip install --no-cache-dir --upgrade pip setuptools wheel
+
 WORKDIR /usr/src/app
 
 # Install GPU-enabled PyTorch wheels

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SigProfilerExtractor
-Version: 1.4.0
+Version: 1.5.0
 Summary: Extracts mutational signatures from mutational catalogues
 Home-page: https://github.com/SigProfilerSuite/SigProfilerExtractor.git
 Author: S Mishu Ashiqul Islam
@@ -15,7 +15,7 @@ Requires-Dist: numpy>=2.0.0
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: sigProfilerPlotting>=1.4.3
 Requires-Dist: SigProfilerMatrixGenerator>=1.3.5
-Requires-Dist: SigProfilerAssignment>=1.1.3
+Requires-Dist: SigProfilerAssignment>=1.1.5
 Requires-Dist: statsmodels>=0.9.0
 Requires-Dist: scikit-learn>=0.24.2
 Requires-Dist: psutil>=5.6.1
@@ -120,8 +120,8 @@ help(sig.importdata)
 Extracts mutational signatures from an array of samples.
 
 ```python 
-sigProfilerExtractor(input_type, out_put, input_data, reference_genome="GRCh37", opportunity_genome = "GRCh37", context_type = "default", exome = False, 
-                         minimum_signatures=1, maximum_signatures=10, nmf_replicates=100, resample = True, batch_size=1, cpu=-1, gpu=False, 
+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=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,14 +154,14 @@ 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.  |
 |  | **combined_stability** | Float | The cutoff thresh-hold of the combined stability (sum of average and minimum stability) (default: `1.0`). Solutions with combined stabilities below this thresh-hold will not be considered. |
 |  | **allow_stability_drop** | Boolean | Defines if solutions with a drop in stability with respect to the highest stable number of signatures will be considered (default: `False`). |
 | **Decomposition** |  |  |  | 
-|  | **cosmic_version** | Float | Defines the version of the COSMIC reference signatures (default: `3.5`). Takes a positive float among `1`, `2`, `3`, `3.1`, `3.2`, `3.3`, `3.4`, and `3.5`.|
+|  | **cosmic_version** | Float | Defines the version of the COSMIC reference signatures (default: `3.6`). Takes a positive float among `1`, `2`, `3`, `3.1`, `3.2`, `3.3`, `3.4`, `3.5`, and `3.6`.|
 |  | **make_decomposition_plots** | Boolean | Generate de novo to COSMIC signature decomposition plots as part of the results (default: `True`). Set to `False` to skip generating these plots. |
 |  | **collapse_to_SBS96** | Boolean | If `True`, SBS288 and SBS1536 de novo signatures will be mapped to SBS96 reference signatures (default: `True`). If `False`, those will be mapped to reference signatures of the same context.
 | **Others** |  |  |  | 

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

@@ -88,8 +88,8 @@ help(sig.importdata)
 Extracts mutational signatures from an array of samples.
 
 ```python 
-sigProfilerExtractor(input_type, out_put, input_data, reference_genome="GRCh37", opportunity_genome = "GRCh37", context_type = "default", exome = False, 
-                         minimum_signatures=1, maximum_signatures=10, nmf_replicates=100, resample = True, batch_size=1, cpu=-1, gpu=False, 
+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=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,14 +122,14 @@ 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.  |
 |  | **combined_stability** | Float | The cutoff thresh-hold of the combined stability (sum of average and minimum stability) (default: `1.0`). Solutions with combined stabilities below this thresh-hold will not be considered. |
 |  | **allow_stability_drop** | Boolean | Defines if solutions with a drop in stability with respect to the highest stable number of signatures will be considered (default: `False`). |
 | **Decomposition** |  |  |  | 
-|  | **cosmic_version** | Float | Defines the version of the COSMIC reference signatures (default: `3.5`). Takes a positive float among `1`, `2`, `3`, `3.1`, `3.2`, `3.3`, `3.4`, and `3.5`.|
+|  | **cosmic_version** | Float | Defines the version of the COSMIC reference signatures (default: `3.6`). Takes a positive float among `1`, `2`, `3`, `3.1`, `3.2`, `3.3`, `3.4`, `3.5`, and `3.6`.|
 |  | **make_decomposition_plots** | Boolean | Generate de novo to COSMIC signature decomposition plots as part of the results (default: `True`). Set to `False` to skip generating these plots. |
 |  | **collapse_to_SBS96** | Boolean | If `True`, SBS288 and SBS1536 de novo signatures will be mapped to SBS96 reference signatures (default: `True`). If `False`, those will be mapped to reference signatures of the same context.
 | **Others** |  |  |  | 

sigprofilerextractor-1.5.0/SigProfilerExtractor/_version.py

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

{sigprofilerextractor-1.4.0 → 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",
@@ -209,8 +220,12 @@ def parse_arguments_extractor(args: List[str], description: str) -> argparse.Nam
     parser.add_argument(
         "--cosmic_version",
         type=float,
-        default=3.5,
-        help="COSMIC version for reference signatures. Valid values are 1, 2, 3, 3.1, 3.2, 3.3, 3.4, and 3.5 (default: 3.5).",
+        default=sigpro.DEFAULT_COSMIC_VERSION,
+        help=(
+            "COSMIC version for reference signatures. Valid values are "
+            f"{', '.join(map(str, sigpro.SUPPORTED_COSMIC_VERSIONS))} "
+            f"(default: {sigpro.DEFAULT_COSMIC_VERSION})."
+        ),
     )
     parser.add_argument(
         "--make_decomposition_plots",

{sigprofilerextractor-1.4.0 → 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.0 → 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):