name: cdr3aaphyschem description: Analyzes physicochemical properties of CDR3 amino acid sequences to understand biochemical characteristics of T-cell receptor repertoires. Performs regression analysis between two cell groups at different CDR3 lengths for each physicochemical feature (hydrophobicity, volume, isoelectric point, etc.).

CDR3AAPhyschem Process Configuration

Purpose

Analyzes physicochemical properties of CDR3 amino acid sequences to understand biochemical characteristics of T-cell receptor repertoires. Performs regression analysis between two cell groups at different CDR3 lengths for each physicochemical feature (hydrophobicity, volume, isoelectric point, etc.).

When to Use

• To analyze CDR3 biochemical properties differences between cell groups (e.g., Treg vs Tconv)
• For feature engineering in TCR machine learning models
• To identify sequence features that distinguish cell subsets
• After ScRepCombiningExpression (requires combined TCR + RNA data)
• When investigating T cell fate determination (regulatory vs conventional T cells)

Configuration Structure

Process Enablement

[CDR3AAPhyschem]
cache = true

Input Specification

[CDR3AAPhyschem.in]
scrfile = ["ScRepCombiningExpression"]

• scrfile: Output from ScRepCombiningExpression (RDS or qs/qs2 format)
• Must contain both TRA and TRB chains
• Generated by scRepertoire::combineExpression()

Environment Variables

[CDR3AAPhyschem.envs]
# Group comparison specification
group = "CellType"
comparison = {Treg = ["CD4 CTL", "CD4 Naive", "CD4 TCM", "CD4 TEM"], Tconv = "Tconv"}
target = "Treg"
each = "Sample"

# Chain selection
chain = "TRB"

Key Parameters:

• group: Column name in metadata defining groups to compare (e.g., CellType, seurat_clusters)
• comparison: Two-group specification for regression analysis
  • Format 1 (dict): Group1 = ["cell1", "cell2"], Group2 = "cell3"
  • Format 2 (list): ["Group1", "Group2"] (when groups exist in column)
• target: Which group to label as 1 in regression (default: first group in comparison)
• each: Column(s) to split data for separate analyses
  • Single column: "Sample"
  • Multiple columns: ["Sample", "Patient"]
  • Comma-separated: "Sample,Patient"
  • If not provided, all cells used together

Configuration Examples

Minimal Configuration

[CDR3AAPhyschem]
[CDR3AAPhyschem.in]
scrfile = ["ScRepCombiningExpression"]

Standard Treg vs Tconv Analysis

[CDR3AAPhyschem]
[CDR3AAPhyschem.envs]
# Define cell type groups for comparison
group = "CellType"
comparison = {Treg = ["Treg"], Tconv = ["Tconv"]}
target = "Treg"
chain = "TRB"

Multi-Sample Analysis

[CDR3AAPhyschem]
[CDR3AAPhyschem.envs]
group = "CellType"
comparison = ["Treg", "Tconv"]
target = "Treg"
# Run regression separately for each sample
each = "Sample"
chain = "TRB"

Custom Group Definition

[CDR3AAPhyschem]
[CDR3AAPhyschem.envs]
group = "Cluster"
# Define clusters to compare
comparison = {
  HighQuality = ["c1", "c2", "c5"],
  LowQuality = ["c3", "c4"]
}
target = "HighQuality"
chain = "TRB"

Physicochemical Properties

Available Properties

The process calculates 8 key physicochemical properties from CDR3 amino acid sequences:

Property Calculation Methods

• Default scales: Standard biophysical scales from peer-reviewed literature
• GRAVY: Kyte & Doolittle (1982) hydropathy scale
• Bulkiness: Zimmerman et al. (1968) bulkiness parameters
• Polarity: Grantham (1974) amino acid difference index
• Aliphatic index: Ikai (1980) thermodynamic stability scale
• Charge: Normalized based on pKa values (EMBOSS database)
• Acidic/Basic/Aromatic: Direct residue counting proportions

Regression Analysis

• Performed for each physicochemical property independently
• Compares properties across CDR3 length distributions
• Binary classification: target group (1) vs non-target (0)
• Output: Statistical significance of property differences

Common Patterns

Pattern 1: Treg vs Tconv (TRB Chain)

[CDR3AAPhyschem]
[CDR3AAPhyschem.envs]
# Literature-based: hydrophobic CDR3β promotes Treg fate
group = "CellType"
comparison = {Treg = ["Treg", "CD4+Treg"], Tconv = ["Tconv", "CD4+Tconv"]}
target = "Treg"
chain = "TRB"
each = ""  # Analyze all samples together

Pattern 2: Selected Properties Only

[CDR3AAPhyschem]
[CDR3AAPhyschem.envs]
# Focus on hydrophobicity (key Treg feature)
group = "CellType"
comparison = ["Treg", "Tconv"]
target = "Treg"
chain = "TRB"
# To analyze specific chains separately

Pattern 3: Multi-Chain Analysis

Run separate processes for different chains:

# TRB analysis
[CDR3AAPhyschem]
[CDR3AAPhyschem.envs]
chain = "TRB"
group = "CellType"
comparison = ["Treg", "Tconv"]

# Note: Create separate config for TRA analysis if needed

Pattern 4: Multi-Group Comparisons

[CDR3AAPhyschem]
[CDR3AAPhyschem.envs]
group = "CellType"
comparison = {
  Naive = ["CD4 Naive", "CD8 Naive"],
  Memory = ["CD4 TEM", "CD4 TCM", "CD8 TEM", "CD8 TCM"],
  Effector = ["CD4 CTL", "CD8 CTL"]
}
target = "Naive"
chain = "TRB"

Dependencies

• Upstream: ScRepCombiningExpression (required)
• Downstream: Feature analysis, ML model training, publication figures
• Required data: Both TRA and TRB chains in combined object

Validation Rules

• CDR3 sequence requirements: Must have valid amino acid sequences (no Ns)
• Chain requirement: Data must contain specified chain (TRA or TRB)
• Group specification: Groups must exist in metadata
• Minimum cells: Sufficient cells per group for statistical regression
• Length distribution: CDR3 length range must be adequate for regression

Troubleshooting

Issue: "Missing chain in data"

Cause: Specified chain (TRA/TRB) not found in combined object Solution:

# Change to available chain
[CDR3AAPhyschem.envs]
chain = "TRA"  # or "TRB"

Issue: "Group not found in metadata"

Cause: group column or comparison values don't exist Solution:

1. Check available metadata columns in ScRepCombiningExpression output
2. Verify group names match exactly (case-sensitive)

[CDR3AAPhyschem.envs]
group = "seurat_clusters"  # If CellType not available
comparison = ["0", "1"]  # Use cluster IDs

Issue: "Insufficient cells for regression"

Cause: Too few cells in one or more groups Solution:

1. Use each to analyze samples separately if pooled analysis fails
2. Combine similar cell types in comparison

[CDR3AAPhyschem.envs]
# Combine rare subtypes
comparison = {HighExpander = ["Treg", "Tconv"], LowExpander = ["Tfh"]}

Issue: "No significant property differences"

Cause: Groups may not differ in physicochemical properties Solution:

1. Check if comparison groups are biologically distinct
2. Consider different group column (e.g., gene expression clusters)
3. Verify CDR3 sequences are high-quality

Scientific Context

Key Publications

1. Stadinski et al. (2016): "Hydrophobic CDR3 residues promote development of self-reactive T cells" - Nature Immunology
2. Lagattuta et al. (2022): "TCR sequence features influence T cell fate" - Nature Immunology
3. Ostmeyer et al. (2019): "Biophysicochemical motifs distinguish TILs from healthy tissue" - Cancer Research

Interpretation Guidelines

• High GRAVY: More hydrophobic CDR3 (associated with self-reactivity, Treg)
• High charge: Electrostatic potential may affect binding affinity
• High aromaticity: Increased π-π interactions, structural stability
• Length distribution: Longer CDR3s may provide broader specificity

Feature Engineering Applications

Use properties as features for:

• TCR specificity prediction models
• T cell fate classification (Treg vs Tconv)
• Antigen binding affinity estimation
• Cross-reactivity assessment

Output Format

• Directory: {{in.scrfile | stem}}.cdr3aaphyschem/
• Files:
  • Regression plots per property (hydrophobicity, volume, pI)
  • Statistical tables comparing groups
  • CDR3 length distributions
  • Property correlation matrices
• Visualizations:
  • Property vs length scatter plots
  • Group-wise property boxplots
  • Regression curves with confidence intervals

Advanced Usage

Custom Property Scales

If using non-default scales (requires modifying underlying R script):

# Note: Advanced usage - may require script modification
[CDR3AAPhyschem]
[CDR3AAPhyschem.envs]
# Specify alternative hydrophobicity scale
hydro_scale = "Wimley"
pK_source = "Murray"

Length-Based Stratification

[CDR3AAPhyschem]
[CDR3AAPhyschem.envs]
# Analyze by CDR3 length bins
group = "CellType"
comparison = ["Treg", "Tconv"]
# Use metadata column with length information
each = "CDR3_Length_Bin"
chain = "TRB"

Publication-Ready Plots

[CDR3AAPhyschem]
[CDR3AAPhyschem.envs]
group = "CellType"
comparison = {Treg = "Treg", Tconv = "Tconv"}
target = "Treg"
chain = "TRB"
# Publication parameters
plot_theme = "nature"
fig_dpi = 300
fig_format = "pdf"