Key concepts

Immunology in Gradient Biotech is organized around immune cell populations, immune states, receptor repertoires, signaling interactions, disease context, multimodal assays, and reproducible analysis runs. This page explains the main immunology concepts behind the workflows and the app concepts used to manage them.

Immune profiling data

Most Immunology workflows start from tabular assay data. The rows may represent cells, clonotypes, cytokine measurements, spatial locations, chromatin accessibility peaks, cytometry events, or samples. Columns usually represent labels, metadata, genes, proteins, receptors, coordinates, or computed scores.

Common input types:

• Single-cell ribonucleic acid sequencing (scRNA-seq): single-cell gene expression data used for immune composition, annotation, and state scoring.
• Cellular indexing of transcriptomes and epitopes by sequencing (CITE-seq) / antibody-derived tags (ADT): antibody-derived protein measurements paired with single-cell data.
• Variable, diversity, and joining region sequencing (VDJ) / repertoire: T cell receptor or B cell receptor sequence records used to identify clonotypes and clonal expansion.
• Spatial: immune labels or expression features with tissue coordinates.
• Bulk ribonucleic acid (bulk RNA): sample-level expression tables for immune profiling contexts.
• Assay for transposase-accessible chromatin using sequencing (ATAC) / multiome: chromatin accessibility and paired multimodal summaries.
• Flow cytometry standard (FCS) / cytometry: marker intensity data from flow or mass cytometry, currently supported through tabular event tables.
• Cytokine: signaling or activity measurements used in communication and disease workflows.

The current app supports dataset records and pipeline inputs from file paths or inline rows. Production analyses should use explicit study data even when a panel can run with built-in demo rows.

Immune composition

Immune composition summarizes which immune populations are present and how their proportions differ across samples or groups. This is often the first immunology analysis because it establishes the cellular context for downstream state, repertoire, communication, and disease workflows.

Common concepts:

Concept	Meaning
Cell type	Immune population label, such as T cell, B cell, monocyte, natural killer (NK) cell, or dendritic cell.
Population count	Number of cells assigned to a label.
Proportion	Fraction of cells assigned to a label within a sample, group, or study.
Group summary	Composition summarized by condition, cohort, disease label, treatment, or timepoint.
Dominant population	The most abundant label in a sample or group.

Composition shifts can suggest immune infiltration, depletion, expansion, or sampling bias. They should be interpreted with sample size, capture method, tissue source, disease context, and annotation quality.

Annotation and immune state scoring

Annotation assigns immune labels to cells or records. Labels may be broad, such as lymphocyte or myeloid, or more specific, such as cluster of differentiation 8 (CD8) T cell, regulatory T cell, plasma cell, macrophage, or neutrophil.

Immune state scoring summarizes functional programs that cut across cell types.

Common state programs:

• Activation: markers of immune stimulation or response.
• Exhaustion: inhibitory or dysfunction-associated programs often studied in chronic infection, autoimmunity, and cancer.
• Effector: genes or proteins linked to active immune function.
• Cytotoxicity: killing-associated programs, often relevant to cluster of differentiation 8 T cells and natural killer cells.
• Regulatory: suppressive or immune-modulating programs.

An annotation label is a hypothesis based on measured markers and context. Strong interpretation checks whether the label, marker pattern, tissue, organism, and disease setting agree.

T cell receptor and B cell receptor repertoire

T cells and B cells use rearranged receptors to recognize antigens. T cell receptor (TCR) and B cell receptor (BCR) repertoire analysis summarizes the diversity and expansion of those receptor sequences.

Important concepts:

• T cell receptor (TCR): T cell receptor sequence, usually from alpha/beta or gamma/delta chains.
• B cell receptor (BCR): B cell receptor sequence, often linked to antibody lineage analysis.
• Complementarity-determining region 3 (CDR3): highly variable receptor region commonly used for clonotype definitions.
• V gene and J gene usage: receptor segment usage patterns.
• Clonotype: group of cells or sequences inferred to share the same receptor identity.
• Clonal expansion: enrichment of one clonotype, suggesting antigen-driven or context-driven expansion.
• Diversity: distribution of clonotypes across a sample.
• Overlap: shared clonotypes across samples, groups, timepoints, or tissues.

Expanded clonotypes are biologically interesting, but they do not identify the antigen by themselves. Repertoire results should be interpreted with cell state, disease context, sampling depth, chain pairing, and assay type.

Cell-cell communication

Cell-cell communication estimates signaling interactions between immune populations using ligand-receptor pairs, cytokine activity, and pathway summaries.

Core concepts:

• Ligand: signaling molecule expressed or secreted by a source cell population.
• Receptor: target molecule expressed by a receiving cell population.
• Interaction score: computed strength or evidence for a ligand-receptor pair.
• Cytokine network: cytokine-centered signaling pattern across cell populations.
• Pathway summary: grouped signaling programs, such as interferon, tumor necrosis factor (TNF), chemokine, or checkpoint-related activity.
• Condition delta: difference in signaling between groups or disease states.

Communication outputs are computational evidence, not direct proof of physical interaction. They are strongest when supported by expression quality, expected biology, spatial proximity, and experimental validation.

Disease workflows

Disease workflows connect immune states to disease context, trajectory, spatial location, cohort metadata, and treatment or timepoint information.

Common concepts:

• Disease label: condition or subgroup used for comparison.
• Disease activity score: numeric score representing severity, activity, or response context.
• Trajectory / pseudotime: ordered axis used to model state progression or differentiation.
• Clone-state link: relationship between clonotypes and immune states.
• Spatial immune niche: tissue region where immune populations, cytokine activity, or disease features co-occur.
• Tertiary lymphoid structure-like (TLS-like) region: tertiary lymphoid structure-like pattern inferred from immune composition and spatial context.
• Proximity: distance or neighborhood relationship between immune cells, states, or tissue features.

Disease interpretation depends on metadata quality. Medication, timepoint, vaccination or infection history, tissue site, and cohort definition can change the biological meaning of the same signal.

Multi-modal immune profiling

Multi-modal profiling combines multiple assay layers to describe immune cells more completely than one modality alone.

Supported concepts:

• Antibody-derived tag (ADT) / protein markers: antibody-derived tags used to summarize surface or protein expression.
• Assay for transposase-accessible chromatin using sequencing (ATAC) peaks: accessible chromatin regions linked to regulatory activity.
• Multiome summaries: paired expression and accessibility signals from the same or matched cells.
• Cytometry events: marker intensity rows representing flow or mass cytometry measurements.
• Protein-informed clusters: cell groups interpreted using protein markers in addition to RNA labels.

Multi-modal agreement improves confidence. Disagreement can also be informative, but it may reflect technical differences, marker choice, normalization, or batch effects.

Cohorts and immune metadata

Immunology studies often compare immune features across cohorts, samples, and disease contexts.

Useful metadata fields include:

• Organism: species for marker interpretation and gene naming.
• Disease context: autoimmune, infectious disease, oncology, vaccine, transplant, inflammatory, or other study domain.
• Cohort label: group or study arm used for summaries.
• Sample identifier (sample ID): identifier connecting cells, repertoire rows, cytokine measurements, and metadata.
• Medication and timepoint: context for treatment and longitudinal analysis.
• Vaccination or infection history: immune exposure context.

Metadata is not background decoration. It defines the biological question and the statistical grouping used by downstream analyses.

Artificial intelligence interpretation and reporting

Artificial intelligence (AI) interpretation reads completed Immunology run records and produces grounded summaries from computed outputs.

The interpretation context can include:

• immune composition
• annotation and state scoring
• repertoire analysis
• cell-cell communication
• disease workflows
• multi-modal profiling

Guardrails require metric citations, matching run identifiers and values, no fabricated numbers, no clinical recommendations, and a research-only disclaimer. Report runs create structured JavaScript Object Notation (JSON), methods text, tables, figure specs, and provenance.

Study

An Immunology study is the project container. It stores metadata such as disease context, organism, cohort label, datasets, run records, interpretation outputs, and report artifacts.

Dataset

A dataset records modality and file metadata. It may point to local files or serve as a study-level record for analysis inputs.

Common dataset modalities include:

• scrna for single-cell ribonucleic acid sequencing
• cite_seq for cellular indexing of transcriptomes and epitopes by sequencing
• vdj for variable, diversity, and joining region repertoire data
• spatial
• bulk_rna for bulk ribonucleic acid data
• atac for assay for transposase-accessible chromatin using sequencing data
• fcs for flow cytometry standard files or cytometry records
• cytokine

The app does not yet provide a full Immunology file-upload manager. Register datasets first, then pass paths or rows through the analysis panels or application programming interface (API) until upload workflows are expanded.

Run record

A run record stores one execution of an Immunology pipeline.

Each run records:

• Pipeline name
• Submitted parameters
• Status and progress
• Result JavaScript Object Notation
• Artifact path
• Provenance
• Platform version

Completed scientific runs are used by interpretation and reporting. Interpretation and report runs are excluded from the source context so reports cite scientific analysis runs only.

Artifact

An artifact is a JavaScript Object Notation output written under data/immunology/artifacts/{run_id}/. Artifacts contain the computed results shown in the user interface (UI) and the records used for downstream interpretation.

Dependency gate

Some deeper workflows need optional packages or configured model assets. The app feature-gates these instead of silently pretending they ran.

Feature	Gate
Full CellTypist model execution	CellTypist model asset/path
Full weighted nearest neighbor (WNN) / multiome graph workflows	muon
Full single-cell assay for transposase-accessible chromatin using sequencing (scATAC) preprocessing and peak calling	SnapATAC2
Binary flow cytometry standard parsing	FlowUtils or flowutils

Feature gates are not failures. They mark where the current environment can run a summary or tabular implementation but needs additional configured assets or packages for the deeper workflow.

Provenance and reproducibility

Every Immunology analysis writes a run record and an artifact. Use run identifiers, pipeline names, parameter JSON records, platform versions, and artifact paths in methods sections. Re-run analyses from the same study context when upstream datasets, metadata, or parameters change.

Interpretation scope

Immunology outputs are for exploratory and translational research. They are not clinical decision support, diagnostics, treatment recommendations, or regulated medical device outputs. Treat outputs as structured evidence for research review.