How poisonalien/maftools works
Project Type and Purpose
• maftools is an R library for summarizing, analyzing, and visualizing MAF (Mutation Annotation Format) files from cancer genomics studies.
• It wraps high-level R functions around core C routines for performance, ingests various input formats (MAF, BAM, GISTIC), and outputs plots, tables, and reports.
File Structure
• R/: Main R functions (data ingestion, statistical analyses, plotting).
• src/: Native C code (ntcounts.c, snpcounts.c, somaticfreq.c) for heavy computations.
• inst/extdata/: Bundled example datasets (MAF files, cytobands, signature references).
• man/: Documentation stubs for each R function (used by R help system).
• vignettes/: Tutorials and case-studies (R Markdown).
• scripts/: Utility scripts for pre-processing outside the package.
• DESCRIPTION, NAMESPACE: R package metadata and exports.
• .github/, workflows: CI checks and issue templates.
README for Additional Insights
• Core workflows: import MAF → create MAF object → pass to analysis/plot functions.
• Supported inputs: MAF, BAM, GISTIC, mosdepth.
• External dependencies: data.table, NMF, ggplot2, BiocManager, downstream tools (annovar2maf, vcf2maf).
• External services: TCGA, ICGC, cBioPortal.
Main Components & Their Relationships
a. User Interface Layer (R API)
– Entry-points for end users: functions such as read_maf(), oncoPlot(), inferTumHetero(), plotSignatures(), etc.
b. Core Engine
– R code orchestrates workflows: data validation, reshaping, statistical testing (fisherCorrect, estimateSignatures).
– Native C modules for performance-critical tasks (e.g., ntcounts, snpcounts, somaticfreq).
c. Data Layer
– Example/reference data in inst/extdata (cytobands, signature matrices).
– External input files: MAF, BAM, GISTIC.
– Clinical metadata (user-supplied or loaded via tcgaLoad()).
d. Visualization Layer
– ggplot2 wrappers for oncoplots, lollipop plots, rainfall plots, signature plots.
– Report generation via R Markdown vignettes.
e. Extensibility Points
– scripts/ folder for pre-processing pipelines.
– vignettes/ to guide custom workflows.
– S3/S4 class system (MAF-class, GISTIC-class) for method dispatch.
f. Integration with External Services
– BiocManager for installation.
– TCGA/ICGC REST or flat-file downloads.
– Third-party annotation tools (Annovar, vcf2maf).
Architectural Patterns & Design Principles
• Modular layering: clear separation between API, core logic, native code, data, and visualization.
• S3/S4 class dispatch: encapsulate MAF and GISTIC objects.
• “Plug-and-play” external data: inst/extdata and user-provided files.
• CI/CD with GitHub Actions (.github/workflows).
• Reproducibility via vignettes and scripts.
Putting It All Together
• Top layer: R API functions
• Underneath: C Modules
• To the right: Data Store (inst/extdata + user inputs)
• To the left: External Tools & Services
• Bottom: Visualization & Reports (vignettes, plots)
• Class objects (MAF, GISTIC) inside the Core Engine layer.
• CI/CD pipeline off to the side, linked to the GitHub repo.