Refactor ATAC analysis and update documentation

[willisbillis]

Enhance the MAPseq pipeline by restructuring scripts for better organization of FASTQ files, adding validation for ASAP FASTQ files, and updating installation instructions for ATAC Azimuth with Seurat and Signac. Additionally, improve the README and environment configuration for clarity.

Summary by Sourcery

Refactor ATAC workflows, update environment dependencies, and improve pipeline documentation

Enhancements:

• Refactor aggregation script to conditionally run RNA and ATAC workflows based on sample manifests and integrate demultiplexing and Seurat downstream steps
• Restructure ASAP-to-Kite script to separate ASAP and ATAC FASTQs into dedicated folders and validate presence of required R3 reads before processing

Build:

• Bump multiple package versions in environment_ubuntu-latest.yml to ensure compatibility

Documentation:

• Add quickstart note on renaming FASTQ files for NextSeq 2000 ASAPseq data and update README logo path
• Include Azimuth ATAC setup instructions and notes file

[sourcery-ai]

Reviewer's Guide

This PR refactors core pipeline scripts to add conditional execution and FASTQ validation, updates the conda environment with numerous dependency bumps, and enhances documentation with setup guidance and asset path corrections.

Sequence diagram for ASAP FASTQ validation and separation in run_asap_to_kite.sh

sequenceDiagram
    participant Script as run_asap_to_kite.sh
    participant FS as File System
    participant User as actor User

    Script->>FS: Create ASAP and ATAC FASTQ directories
    Script->>FS: Move FASTQ files to respective directories
    loop For each ASAP sample
        Script->>FS: Check for R1, R2, R3 FASTQ files
        alt R3 file missing
            Script->>User: Output error and exit
        else R3 file present
            Script->>Script: Run asap_to_kite_v2.py
        end
    end

Loading

Flow diagram for FASTQ file organization in run_asap_to_kite.sh

flowchart TD
    A[Start] --> B[Create ASAP and ATAC FASTQ directories]
    B --> C[For each FASTQ file in main directory]
    C --> D{Filename contains ASAP_NAMING_ID?}
    D -- Yes --> E[Move to ASAP FASTQ directory]
    D -- No --> F{Filename contains ATAC_NAMING_ID?}
    F -- Yes --> G[Move to ATAC FASTQ directory]
    F -- No --> H[Do nothing]
    E --> I[Next file]
    G --> I
    H --> I
    I --> C
    C --> J[End]

Loading

File-Level Changes

Change	Details	Files
Introduce conditional orchestration for RNA and ATAC aggregation and downstream processing	Extract sample names from manifest CSVs and filter out headers Use array length checks to conditionally run RNA and ATAC workflows Sequentially invoke cellranger aggr, souporcell demux, and Seurat scripts per modality	src/aggr_template/run_mapseq_aggr.sh
Enhance FASTQ file organization and validation in ASAP-to-KITE conversion script	Create separate ASAP and ATAC FASTQ subdirectories and move files based on naming IDs Validate presence of R3 FASTQ for each ASAP sample and exit with error if missing Update python invocation to point to the new FASTQ directories	src/mapseq_template/pipeline/ATAC.ASAP/run_asap_to_kite.sh
Bump multiple conda package versions in environment configuration	Update patch releases for a wide range of Python, R, and system libraries Ensure both hyphenated and underscored typing-extensions entries are synchronized Upgrade UMAP and other scientific packages to maintain compatibility	environment_ubuntu-latest.yml
Improve documentation with setup guidance and asset path updates	Add Quickstart note for renaming ASAPseq files from NextSeq 2000 outputs Correct README logo path to the assets directory Add Azimuth ATAC installation details in a new notes file	docs/quickstart.md README.md src/phase2_scripts/LRA/notes.for.running.Azimuth.ATAC.txt

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.