Merge pull request #182 from AlexandrovLab/spa-sep25-cleanup

Merge spa-sep25-cleanup into main for v1.0.0 update

Author: mdbarnesUCSD

CHANGELOG.md

@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [1.0.0] - 2025-10-07
+
+### Added
+- Parallel execution of SPA runs for improved performance on multi-core systems.
+- `cpu` parameter to control the number of processor cores used during assignment. Defaults to `-1` to use all available cores.
+
+### Documentation
+- Updated README to document the new `cpu` parameter.
+
 ## [0.2.6] - 2025-09-17
 
 ### Added

README.md

@@ -74,10 +74,12 @@ Analyze.cosmic_fit(samples, output, input_type="matrix", context_type="96",
 | make_plots | Boolean | Toggle on and off for making and saving plots. The default value is True. |
 | sample_reconstruction_plots | String | Select the output format for sample reconstruction plots. Valid inputs are {'pdf', 'png', 'both', 'none'}. The default value is 'none'. If set to 'png' or 'both', the external binary `poppler` must be installed. Install via `conda install -c conda-forge poppler` or `brew install poppler` on macOS. |
 | verbose | Boolean | Prints detailed statements. The default value is False. |
+| cpu | Integer | Number of processor cores to use during assignment. The default value is -1, which uses all available cores. |
 | volume | String | Path to SigProfilerAssignment volumes. Used for Docker/Singularity. Environmental variable "SIGPROFILERASSIGNMENT_VOLUME" takes precedence. Default value is None. |
 
 
 
+
 ### <a name="subgroups"></a> Signature Subgroups
 
 When using COSMIC reference signatures, some subgroups of signatures can be removed to improve the refitting analysis. To use this feature, the `exclude_signature_subgroups` parameter should be added, following the sintax below:

SigProfilerAssignment/Analyzer.py

@@ -24,6 +24,7 @@ def decompose_fit(
     export_probabilities=True,
     export_probabilities_per_mutation=False,
     volume=None,
+    cpu=-1,
 ):
     decomp.spa_analyze(
         samples=samples,
@@ -51,6 +52,7 @@ def decompose_fit(
         export_probabilities=export_probabilities,
         export_probabilities_per_mutation=export_probabilities_per_mutation,
         volume=volume,
+        cpu=cpu,
     )
 
 
@@ -76,6 +78,7 @@ def denovo_fit(
     export_probabilities=True,
     export_probabilities_per_mutation=False,
     volume=None,
+    cpu=-1,
 ):
     decomp.spa_analyze(
         samples=samples,
@@ -102,6 +105,7 @@ def denovo_fit(
         export_probabilities=export_probabilities,
         export_probabilities_per_mutation=export_probabilities_per_mutation,
         volume=volume,
+        cpu=cpu,
     )
 
 
@@ -128,6 +132,7 @@ def cosmic_fit(
     export_probabilities_per_mutation=False,
     sample_reconstruction_plots=False,
     volume=None,
+    cpu=-1,
 ):
     decomp.spa_analyze(
         samples=samples,
@@ -155,4 +160,5 @@ def cosmic_fit(
         export_probabilities_per_mutation=export_probabilities_per_mutation,
         sample_reconstruction_plots=sample_reconstruction_plots,
         volume=volume,
+        cpu=cpu,
     )

SigProfilerAssignment/DecompositionPlots/PlotDecomposition.py

@@ -281,16 +281,22 @@ def calculate_similarities(denovo, denovo_name, est_denovo):
     if denovo.shape[0] == 1536:
         denovo["IndexKey"] = denovo.iloc[:, 0].astype(str)
         denovo["GroupKey"] = denovo["IndexKey"].str[1:8]
-        denovo_grouped = denovo.groupby("GroupKey", as_index=False).sum(numeric_only=True)
+        denovo_grouped = denovo.groupby("GroupKey", as_index=False).sum(
+            numeric_only=True
+        )
         denovo_grouped.rename(columns={"GroupKey": "MutationType"}, inplace=True)
         denovo = denovo_grouped.reset_index(drop=True)
 
     elif denovo.shape[0] == 288:
         denovo["MutationType"] = denovo["MutationType"].astype(str)  # Ensure strings
-        denovo["GroupKey"] = denovo["MutationType"].str[2:9]  # Extract substring for grouping
-        denovo_grouped = denovo.groupby("GroupKey", as_index=False).sum(numeric_only=True)
+        denovo["GroupKey"] = denovo["MutationType"].str[
+            2:9
+        ]  # Extract substring for grouping
+        denovo_grouped = denovo.groupby("GroupKey", as_index=False).sum(
+            numeric_only=True
+        )
         denovo_grouped.rename(columns={"GroupKey": "MutationType"}, inplace=True)
-        denovo = denovo_grouped.reset_index(drop=True) # updated pandas 2.0.0
+        denovo = denovo_grouped.reset_index(drop=True)  # updated pandas 2.0.0
     sample_names = [denovo_name]
 
     if sample_names is False:

SigProfilerAssignment/DecompositionPlots/PlotDecomposition_SV32.py

@@ -128,6 +128,7 @@
 PLOT_NAME = 0
 CONTRIBUTION = 1
 
+
 # Helper functions for plotting the layout of a graph with 1-5 basis signatures
 # Parameters:
 #   bases 		- (List of Strings) The list of basis names

SigProfilerAssignment/controllers/cli_controller.py

@@ -85,6 +85,12 @@ def parse_arguments_common(args: List[str], description: str) -> argparse.Namesp
         default=False,
         help="Verbose output (default: False).",
     )
+    parser.add_argument(
+        "--cpu",
+        type=int,
+        default=-1,
+        help="Number of processor cores to use during assignment (default: -1 = all cores).",
+    )
     parser.add_argument(
         "--new_signature_thresh_hold",
         type=float,
@@ -146,8 +152,9 @@ def parse_arguments_common(args: List[str], description: str) -> argparse.Namesp
             "'pdf' (generate only PDF), "
             "'both' (PDF + PNG), or "
             "'png' (PNG only, PDF removed)."
-        )
+        ),
     )
+    
 
     return parser.parse_args(args)
 
@@ -170,6 +177,7 @@ def dispatch_decompose_fit(self, user_args: List[str]) -> None:
             make_plots=parsed_args.make_plots,
             collapse_to_SBS96=parsed_args.collapse_to_SBS96,
             connected_sigs=parsed_args.connected_sigs,
+            cpu=parsed_args.cpu,
             verbose=parsed_args.verbose,
             decompose_fit_option=True,
             denovo_refit_option=False,
@@ -202,6 +210,7 @@ def dispatch_denovo_fit(self, user_args: List[str]) -> None:
             collapse_to_SBS96=parsed_args.collapse_to_SBS96,
             connected_sigs=parsed_args.connected_sigs,
             verbose=parsed_args.verbose,
+            cpu=parsed_args.cpu,
             decompose_fit_option=False,
             denovo_refit_option=True,
             cosmic_fit_option=False,
@@ -230,6 +239,7 @@ def dispatch_cosmic_fit(self, user_args: List[str]) -> None:
             collapse_to_SBS96=parsed_args.collapse_to_SBS96,
             connected_sigs=parsed_args.connected_sigs,
             verbose=parsed_args.verbose,
+            cpu=parsed_args.cpu,
             decompose_fit_option=False,
             denovo_refit_option=False,
             cosmic_fit_option=True,