Cdr3aaphyschem

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"