Merge pull request #167 from AlexandrovLab/replace-fitz

v0.2.2: Refactor reconstruction plot generation to support PNG output…

Author: mdbarnesUCSD

.travis.yml

@@ -10,6 +10,11 @@ cache:
   branch:
     - master
 
+addons:
+  apt:
+    packages:
+      - poppler-utils
+
 before_install:
   - pip install --upgrade pip setuptools packaging
   - if ! [ -f ./src/GRCh37.tar.gz ]; then wget --connect-timeout=10 --tries=20 ftp://alexandrovlab-ftp.ucsd.edu/pub/tools/SigProfilerMatrixGenerator/GRCh37.tar.gz -P ./src/; fi
@@ -21,7 +26,5 @@ before_script:
   - python3 install_genome.py $TRAVIS_BUILD_DIR/src/
 
 script: 
-  # run unit tests
   - pytest tests
-  # run integration tests
   - python3 test.py

CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [0.2.2] - 2025-05-02
+
+### Changed
+- Replaced PDF-to-PNG conversion backend from `PyMuPDF` to `pdf2image` for compatibility with Conda and improved portability.
+- Added new CLI parameter: `--sample_reconstruction_plots` with options `'none'` (default), `'pdf'`, `'png'`, and `'both'`.
+- Updated `spa_analyze` and CLI dispatch logic to support format-based sample reconstruction plot output.
+- Default behavior now skips sample reconstruction plots unless explicitly requested.
+- Removed `fitz` dependency; added system requirement note for `poppler` in `setup.py` and README.
+
+### Added
+- Added a pyproject.toml file to the repository for better project management and configuration.
+
 ## [0.2.1] - 2025-04-29
 
 ### Fixed

README.md

@@ -34,6 +34,12 @@ $ python
 from SigProfilerMatrixGenerator import install as genInstall
 genInstall.install('GRCh37')
 ```
+
+If you plan to use `sample_reconstruction_plots='png'` or `'both'`, the external `poppler` binary is required. You can install it using one of the following commands:
+
+- For Conda-based environments:
+  `conda install -c conda-forge poppler`
+
 ## <a name="running"></a> Running
 
 Assignment of known mutational signatures to individual samples is performed using the `cosmic_fit` function. Input samples are provided using the `samples` parameter in the form of mutation calling files (VCFs, MAFs, or simple text files), segmentation files or mutational matrices. COSMIC mutational signatures v3.4 are used as the default reference signatures, although previous COSMIC versions and custom signature databases are also supported using the `cosmic_version` and `signature_database` parameters. Results will be found in the folder specified in the `output` parameter.
@@ -66,7 +72,7 @@ Analyze.cosmic_fit(samples, output, input_type="matrix", context_type="96",
 | export_probabilities | Boolean | Defines if the probability matrix per mutational context for all samples is created. The default value is True. |
 | export_probabilities_per_mutation | Boolean | Defines if the probability matrices per mutation for all samples are created. Only available when `input_type` is "vcf". The default value is False. |
 | 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. |
+| 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. |
 | volume | String | Path to SigProfilerAssignment volumes. Used for Docker/Singularity. Environmental variable "SIGPROFILERASSIGNMENT_VOLUME" takes precedence. Default value is None. |
 

SigProfilerAssignment/controllers/cli_controller.py

@@ -135,6 +135,19 @@ def parse_arguments_common(args: List[str], description: str) -> argparse.Namesp
         default=None,
         help="User specified directory for saving/loading template files. Note: The environment variable SIGPROFILERASSIGNMENT_VOLUME takes precedence over this parameter.",
     )
+    parser.add_argument(
+        "--sample_reconstruction_plots",
+        type=str.lower,
+        choices=["none", "pdf", "both", "png"],
+        default="none",
+        help=(
+            "Output format for sample reconstruction plots. "
+            "Options: 'none' (default, disables plotting), "
+            "'pdf' (generate only PDF), "
+            "'both' (PDF + PNG), or "
+            "'png' (PNG only, PDF removed)."
+        )
+    )
 
     return parser.parse_args(args)
 
@@ -226,5 +239,5 @@ def dispatch_cosmic_fit(self, user_args: List[str]) -> None:
             context_type=parsed_args.context_type,
             export_probabilities=parsed_args.export_probabilities,
             export_probabilities_per_mutation=parsed_args.export_probabilities_per_mutation,
-            sample_reconstruction_plots=False,
+            sample_reconstruction_plots=parsed_args.sample_reconstruction_plots,
         )

SigProfilerAssignment/decomposition.py

@@ -25,7 +25,7 @@
 import sigProfilerPlotting
 import os, sys
 from pypdf import PdfWriter, PdfReader
-import fitz
+from pdf2image import convert_from_path
 import time
 from pathlib import Path
 
@@ -60,21 +60,32 @@ def get_storage_dir(volume=None):
 
 
 def convert_PDF_to_PNG(input_file_name, output_directory, page_names):
-    pdf_doc = fitz.open(input_file_name)
-    zoom = 3
-    magnify = fitz.Matrix(zoom, zoom)
+    """
+    Converts each page of the PDF to a PNG image with names from page_names.
+    Requires the 'pdf2image' Python package and the 'poppler' binary.
+
+    Parameters:
+    - input_file_name (str): Path to the input PDF file.
+    - output_directory (str): Directory where PNGs will be saved.
+    - page_names (List[str]): List of names (without extensions) to name PNGs.
+    """
+    if not os.path.exists(output_directory):
+        os.makedirs(output_directory)
+
+    # Convert PDF pages to PIL images
+    try:
+        images = convert_from_path(input_file_name, dpi=300)
+    except Exception as e:
+        raise RuntimeError(f"Error converting PDF to images: {e}")
 
-    if pdf_doc.page_count != len(page_names):
+    if len(images) != len(page_names):
         raise ValueError(
             "Error: The number of samples and number of plots do not match."
         )
-    if not os.path.exists(output_directory):
-        os.makedirs(output_directory)
 
-    for sample_name, page in zip(page_names, pdf_doc):
-        pix = page.get_pixmap(matrix=magnify)
-        out_file_name = os.path.join(output_directory, sample_name + ".png")
-        pix.save(out_file_name)
+    for image, sample_name in zip(images, page_names):
+        output_path = os.path.join(output_directory, sample_name + ".png")
+        image.save(output_path, "PNG")
 
 
 # Create sample reconstruction plots
@@ -263,6 +274,7 @@ def spa_analyze(
         genome_build = A string. The reference genome build. List of supported genomes: "GRCh37", "GRCh38", "mm9", "mm10" and "rn6". The default value is "GRCh37". If the selected genome is not in the supported list, the default genome will be used.
         verbose = Boolean. Prints statements. Default value is False.
         exome = Boolean. Defines if the exome renormalized signatures will be used. The default value is False.
+        sample_reconstruction_plots (str): Select output format for sample reconstruction plots. Valid options are {'pdf', 'png', 'both', 'none'}. Default is 'none'.
 
     Values:
         The files below will be generated in the output folder.
@@ -1061,7 +1073,8 @@ def spa_analyze(
     recon_output_types = ["png", "pdf", "both"]
     # Generate sample reconstruction plots
     if (
-        sample_reconstruction_plots in recon_output_types
+        isinstance(sample_reconstruction_plots, str)
+        and sample_reconstruction_plots.lower() in recon_output_types
         and mutation_type == "96"
         and signature_database is None
     ):

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61", "wheel", "build"]
+build-backend = "setuptools.build_meta"

setup.py

@@ -6,7 +6,7 @@
 if os.path.exists("dist"):
     shutil.rmtree("dist")
 
-VERSION = "0.2.1"
+VERSION = "0.2.2"
 
 
 def write_version_py(filename="SigProfilerAssignment/version.py"):
@@ -15,7 +15,7 @@ def write_version_py(filename="SigProfilerAssignment/version.py"):
 # THIS FILE IS GENERATED FROM SigProfilerAssignment SETUP.PY
 short_version = '%(version)s'
 version = '%(version)s'
-Update = 'v0.2.1: Fix bug in CLI returning non-zero exit code'
+Update = 'v0.2.2: Fix bug in CLI returning non-zero exit code'
 
     
     """
@@ -41,7 +41,8 @@ def write_version_py(filename="SigProfilerAssignment/version.py"):
     "reportlab>=3.5.42",
     "pypdf>=5.0.0",
     "alive_progress>=2.4.1",
-    "PyMuPDF>=1.21.0",  # required for package "fitz"
+    "pdf2image>=1.16.0",  # replacing PyMuPDF
+    # Note: 'poppler' is required as a system dependency for pdf2image
 ]
 
 write_version_py()

tests/test_cli.py

@@ -42,6 +42,8 @@ def test_argument_parsing():
             "True",
             "--exome",
             "True",
+            "--sample_reconstruction_plots",
+            "png",
         ],
         "Test argument parsing",
     )
@@ -56,6 +58,7 @@ def test_argument_parsing():
     assert args.export_probabilities == False
     assert args.export_probabilities_per_mutation == True
     assert args.exome == True
+    assert args.sample_reconstruction_plots == "png"
 
 
 def test_boolean_conversion():