DOCSEARCHbyAlgolia
Submit Docs

immunarch

repository·master·Indexed 43 days ago

https://github.com/immunomind/immunarch

An R toolkit for multi-modal immune repertoire analysis (AIRR data). It provides scalable, reproducible pipelines for computing receptor- and repertoire-level statistics, feature engineering for machine learning, and biomarker discovery, including functional families for diversity, clonality, public receptor indices, and gene usage analysis.

Tokens
1.8K
Snippets
5
Records
8
Agent score
6%

What's inside immunarch

  1. Quick Start: Analyze AIRR data with immunarch

    master

    This guide demonstrates how to load pre-packaged test data and perform essential Adaptive Immune Receptor Repertoire (AIRR) statistics in just a few lines of code.

    # 1. Load the library and test data
library(immunarch)
immdata <- get_test_idata() |> agg_repertoires("Therapy")

# 2. Compute and visualize statistics
airr_stats_genes(immdata, gene_col = "v_call") |> vis()
airr_public_jaccard(immdata) |> vis()
airr_diversity_pielou(immdata) |> vis()
airr_diversity_chao1(immdata) |> vis()
airr_clonality_prop(immdata)
    library(immunarch)
immdata <- get_test_idata() |> agg_repertoires("Therapy")

airr_stats_genes(immdata, gene_col = "v_call") |> vis()
airr_public_jaccard(immdata) |> vis()
airr_diversity_pielou(immdata) |> vis()
airr_diversity_chao1(immdata) |> vis()
airr_clonality_prop(immdata)

  2. Import your own AIRR data into immunarch

    master

    You can load your own repertoire data using read_repertoires. You can either provide a metadata table to map files or point directly to a set of files.

    Option 1: Using a metadata table

    If you have a CSV containing sample information, use the <metadata> placeholder to tell immunarch to look for sample files defined in that metadata.

    mdtable <- read_metadata("data/metadata.csv")
immdata <- read_repertoires("<metadata>", metadata = mdtable)

    Option 2: Reading files directly

    If you want to load all files matching a specific pattern (e.g., all compressed TSV files in a directory):

    mdtable <- read_metadata("data/metadata.csv")
immdata <- read_repertoires("data/*.tsv.gz", metadata = mdtable)
    mdtable <- read_metadata("data/metadata.csv")
immdata <- read_repertoires("data/*.tsv.gz", metadata = mdtable)

  3. Report bugs and request features

    master

    To report a bug or request a new feature, use the GitHub Issue templates provided by the project.

    1. Navigate to the immunarch GitHub Issues page.
    2. Select the appropriate template for your issue type.
    3. If you are reporting a bug, try to provide a minimal reproducible example (reprex). If you need to share data that is too large for GitHub, please note this in the issue description.

  4. Propose code changes via Pull Requests

    master

    To contribute code, new features, or bug fixes to immunarch, follow these steps:

    1. File an Issue first: Before making substantial changes, ensure the proposed change is desired by the team. If reporting a bug, include a minimal reprex to illustrate the problem.
    2. Fork the dev branch: Always fork the dev branch (not master) to ensure you are working with the latest pre-release version.
    3. Create a feature branch: Use a descriptive name for your branch (e.g., fix-issue-12 or repClonality-refactor).
    4. Follow coding standards:
      • Use the tidyverse style guide.
      • Use the styler package to apply styles (but do not restyle unrelated code).
      • Use roxygen2 for documentation.
      • Use testthat for testing. Contributions including test cases are preferred.
    5. Check CI status: Verify the Continuous Integration (CI) build status both before and after your changes.

  5. Install immunarch via pak

    master

    To install immunarch, it is highly recommended to first install pak, a fast package manager. This simplifies the installation of immunarch and its dependencies, especially when installing from GitHub.

    1. Install pak prerequisites

    Run the following in R to install pak:

    install.packages("pak", repos = sprintf("https://r-lib.github.io/p/pak/stable/%s/%s/%s", .Platform$pkgType, R.Version()$os, R.Version()$arch))

    2. Install immunarch

    Choose one of the following methods:

    • Latest version (Recommended): Installs from GitHub to ensure all dependencies are handled correctly via pak.
      pak::pkg_install("immunomind/immunarch")
    • CRAN version:
      pak::pkg_install("immunarch")
    • Development version (Bleeding edge/Hotfixes):
      pak::pkg_install("immunomind/immunarch@dev")
    • Specific pre-1.0 version (0.9.1):
      pak::pkg_install("immunomind/immunarch@0.9.1")
    • Latest 1.0 pre-release:
      pak::pkg_install("immunomind/immunarch")
    install.packages("pak", repos = sprintf("https://r-lib.github.io/p/pak/stable/%s/%s/%s", .Platform$pkgType, R.Version()$os, R.Version()$arch))

# Install latest from GitHub
pak::pkg_install("immunomind/immunarch")

  6. Fix documentation typos

    master

    Small typos or grammatical errors in documentation can be edited directly via the GitHub web interface.

    Important: Always edit the source file.

    • YES: Edit a roxygen comment in a .R file located under the R/ directory.
    • NO: Do not edit .Rd files located under the man/ directory.

    All typo fixes must be submitted via a Pull Request; do not commit directly to the master branch.

  7. Follow commit naming conventions

    master

    The project uses specific commit types and scopes to support automated releases. Commits should follow the format: <type>(<scope>): <description>.

    Commit Types

    • feat: Implementation of a new feature.
    • fix: Fixing a bug.
    • docs: Updating documentation.
    • refactor: Code changes that neither fix a bug nor add a feature.
    • test: Adding or modifying tests.
    • chore: Maintenance tasks.
    • perf: Code changes that improve performance.
    • style: Changes that do not affect the meaning of the code (white-space, formatting, etc.).

    Commit Scopes

    Use these scopes to categorize your changes:

    • diversity, overlap, pub-rep, clonality, gene-usage, explore, kmers, spectratype, dynamics, tools, single-cell: Analysis or visualization-specific functions.
    • vis: General changes in visualization functions (e.g., changing a non-specific function like vis_bar).
    • io: Changes in parsing.
    • db: Changes in database support.
    • utility: General statistics or additional functions.
    • data: Changes in data.
    • upkeep: Changes in NAMESPACE, DESCRIPTION, citations, ISSUE_TEMPLATE.md, etc. (excluding README).
    • vignette: Changes in README and vignettes.
    • ci: Changes in Continuous Integration.
    • shiny: Changes in Shiny applications.

    Examples

    feat(diversity): added the Chao1 method for diversity estimations
fix(clonality): fixed a bug in clonality computations #12
    feat(diversity): added the Chao1 method for diversity estimations
fix(clonality): fixed a bug in clonality computations #12

  8. Explore immunarch function families

    master

    The immunarch API is organized into functional families. You can explore available methods in R using the ? help command on a function or its family prefix.

    Key functional areas include:

    • Basic statistics: Gene usage, length distribution (e.g., ?airr_stats or ?airr_stats_genes)
    • Public receptor indices: Overlap, Jaccard, Morisita (e.g., ?airr_public)
    • Clonality analysis: Clonal lines, occupied space, clonal space homeostasis (e.g., ?airr_clonality)
    • Diversity analysis: Pielou, Shannon, Chao1 (e.g., ?airr_diversity)
    # Examples of help commands
?airr_stats
?airr_public
?airr_clonality
?airr_diversity