Introduction to T Cell Receptor Modeling with BioLuminate

Tutorial Created with Software Release: 2025-3
Topics: Biologics Drug Discovery
Products Used: BioLuminate, PIPER

Tutorial files

327.7 MB
This tutorial is written for use with a 3-button mouse with a scroll wheel.
Words found in the Glossary of Terms are shown like this: Workspacethe 3D display area in the center of the main window, where molecular structures are displayedthe 3D display area in the center of the main window, where molecular structures are displayed

 

Tip: You can hover over a glossary term to display its definition. You can click on an image to expand it in the page.
Abstract:

 

This tutorial provides an introduction to common computational workflows for modeling T Cell Receptors (TCRs) in BioLuminate. It covers essential steps such as structure preparation, visualization, and analysis of key interactions within the TCR-peptide-MHC complex.

Tutorial Content

  1. Introduction to T Cell Receptors

  1. Creating Projects and Importing Structures

  1. Preparing the TCR-peptide-MHC Complex

  2. Annotating the TCR Structure in the Multiple Sequence Viewer/Editor

  1. Visualizing and Analyzing the TCR-peptide-MHC Interactions

  2. Performing MM-GBSA Residue Scanning
  3. Running and Analyzing TCR-pMHC Docking Job

  1. Conclusion and References

  1. Glossary of Terms

1. Introduction to T Cell Receptors

T cells play a crucial role in adaptive immunity, recognizing and eliminating infected or malignant cells through their specialized surface receptors, known as T Cell Receptors. The TCR is a heterodimeric protein complex, typically composed of α and β chains, though γδ T cells express an alternative γδ TCR. Each TCR chain contains variable (V) and constant (C) domains, with the variable domains responsible for antigen recognition. The V region of each chain comprises Framework Regions (FRs) and Complementarity Determining Regions (CDRs). Each chain contains three CDRs (CDR1, CDR2, and CDR3), yielding a total of six CDRs per TCR heterodimer.

Figure 1: Left: an overview of the structural elements of a TCR-peptide-MHC complex. Right: the TCR-peptide interface shown from the TCR side.

In contrast to antibodies, which recognize soluble antigens, TCRs bind to peptide fragments presented by Major Histocompatibility Complex (MHC) molecules on the surface of antigen-presenting cells. This interaction triggers intracellular signaling cascades that activate T cells, leading to immune responses tailored against infections and cancer.

Given their antigen specificity, TCRs have significant therapeutic potential, particularly in TCR-engineered T cell (TCR-T) therapy, where genetically modified T cells express TCRs targeting tumor-associated antigens. This strategy has demonstrated promise in treating solid tumors and viral infections. Beyond TCR-T therapy, other engineered T cell-based approaches, such as Chimeric Antigen Receptor (CAR) T cells, T Cell Engagers (TCEs), and TCR-like antibodies, have been developed. Despite challenges such as MHC restriction and potential off-target effects, advances in protein engineering and computational design continue to refine TCR-based therapies, expanding their applications in cancer immunotherapy.

This tutorial uses the 3QDJ structure, which represents a ternary complex involving the DMF5 T cell receptor, the human class I MHC molecule HLA-A*0201 (HLA-A2), and the MART-1 (27-35) nonameric peptide. The MHC class I molecule consists of a heavy chain that forms the peptide binding groove and a light chain that stabilizes the MHC structure. The nonameric peptide (AAGIGILTV), derived from the melanoma associated antigen MART-1 (also known as Melan-A) serves as a target for T cell recognition. For information on how this structure provides valuable insights into T cell recognition mechanisms pertinent to cancer immunotherapy, read this paper.

In this tutorial, you will learn how to prepare TCR structures for modeling applications, visualize structural features, identify key residues involved in antigen recognition, and assess TCR-MHC binding interactions.

2. Creating Projects and Importing Structures

At the start of the session, change the file path to your chosen Working Directorythe location where files are saved in Maestro to make file navigation easier. Each session in Maestro begins with a default Scratch Projecta temporary project in which work is not saved, closing a scratch project removes all current work and begins a new scratch project, which is not saved. A Maestro project stores all your data and has a .prj extension. A project may contain numerous entries corresponding to imported structures, as well as the output of modeling-related tasks. Once a project is created, the project is automatically saved each time a change is made.

Structures can be built in Maestro or can be imported using File > Import Structures (or drag-and-dropped), and are added to the Entriesa simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion and Project Tabledisplays the contents of a project and is also an interface for performing operations on selected entries, viewing properties, and organizing structures and data. The Entriesa simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion is located to the left of the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed. The Project Tabledisplays the contents of a project and is also an interface for performing operations on selected entries, viewing properties, and organizing structures and data can be accessed by Ctrl+T (Cmd+T) or Window > Project Table if you would like to see an expanded view of your project data. The Toggle Table is another way to interact with structures and can be accessed via Window > Toggle Table.

  1. Double-click the BioLuminate icon.

Figure 2-1. Change Working Directory option.

  1. Go to File > Change Working Directory.
  2. Find your directory, and click Choose.
  3. Pre-generated files are included for running jobs or examining output Download the zip file here: https://www.schrodinger.com/sites/default/files/s3/release/current/Tutorials/zip/tcr_modeling.zip
  4. After downloading the zip file, unzip the contents in your Working Directorythe location where files are saved for ease of access throughout the tutorial.

Figure 2-2. Saving the project in the Save Project panel.

  1. Go to File > Save Project As.
  2. In the Save Project panel, change the File name to TCR_modeling and click Save.
    • The project is now named TCR_modeling.prj.

Figure 2-3. The Get PDB File dialog box.

  1. Go to File > Get PDB.
    • The Get PDB File dialog box opens.
  2. For PDB IDs, type 3QDJ.
  3. Click Download.
    • A banner appears and the TCR-peptide-MHC complex is loaded into the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed.

Note: Imported structures in Maestro are includedthe entry is represented in the Workspace, the circle in the In column is blue in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed and selected(1) the atoms are chosen in the Workspace. These atoms are referred to as "the selection" or "the atom selection". Workspace operations are performed on the selected atoms. (2) The entry is chosen in the Entries (and Project Table) and the row for the entry is highlighted. Project operations are performed on all selected entries in the Entriesa simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion by default. Please refer to the Glossary of Terms for the difference between includedthe entry is represented in the Workspace, the circle in the In column is blue and selected(1) the atoms are chosen in the Workspace. These atoms are referred to as "the selection" or "the atom selection". Workspace operations are performed on the selected atoms. (2) The entry is chosen in the Entries (and Project Table) and the row for the entry is highlighted. Project operations are performed on all selected entries.

3. Preparing the TCR-peptide-MHC Complex

Structure files obtained from the PDB, vendors, and other sources often lack necessary information for performing modeling-related tasks. In this section, you will prepare the TCR-peptide-MHC complex using the Protein Preparation Workflow to make the structure suitable for modeling tasks performed later in this tutorial. For detailed information on how to prepare protein structures, please refer to the Introduction to Structure Preparation and Visualization tutorial, and Best Practices for Protein Preparation.

3.1 Prepare the complex using the Protein Preparation Workflow

Figure 3-1.  Preparing the structure.

  1. Click Prepare in the banner or alternatively click Protein Preparation in the Favorites toolbar.
    • The Protein Preparation Workflow panel opens in the Preparation Workflow tab.

Figure 3-2. Checking for issues present in the structure in the Diagnostics tab.

Before preparing the structure, you should review potential issues.

 

  1. Go to the Diagnostics tab and click Check Workspace Entry.

 

The Valences tab shows valence errors present in the structure. These are caused by crystallographically invisible Hydrogen atoms and will be resolved during protein preparation.

 

Figure 3-3. The Alternates tab.

The Alternates tab shows two residues (A: ARG 14 and B: MET 99) that can crystallize in two distinct positions. They are not at the pMHC-TCR interface, so their precise positioning will not impact the analysis later in the tutorial.

Figure 3-4. Reviewing the structure before preparation.

You can also review the contents of the structure. This is an easy way to remove crystallographic artifacts or some of the chains (and ligands or solvents associated with them) if you need to.

 

  1. Go to the Substructures tab and click Load Workspace Entry.
    • The tables are populated.
    • The Ligands, Metals, Other table shows the nonameric peptide.
    • Notice that there are five chains in the complex.

Chains A and B belong to the MHC class I (HLA-A2) molecule, chain C is the nonameric peptide, and chains D and E form the DMF5 TCR.

Figure 3-5. Preprocess settings.

After reviewing the structure, you can now set up the preparation workflow. In this tutorial, we highlight the options particular to T cell receptors. For an in-depth understanding of various options in the Protein Preparation Workflow, see the Introduction to Structure Preparation and Visualization tutorial and the panel documentation.

 

  1. Return to the Preparation Workflow tab.
  2. Under Preprocess, click More Options.
  3. For Identify protein features, choose T-Cell Receptor.

 

Note: This will annotate the TCR structural regions using the selected scheme (IMGT or AHo). The regions can then be identified via the Hierarchy.

Figure 3-6. Modifying Minimize and Delete Waters settings and running the preparation job .

We always recommend keeping all crystallographic water molecules throughout structure preparation. You may delete them later for workflows that require dry structures.

 

  1. Under Minimize and Delete waters, click Settings.
  2. For Delete Waters, uncheck Distant from ligands (hets).
  3. Change the Job name to proteinprep_3QDJ.
  4. Click Run.
    • This job will take ~ 2 minutes.
    • Once the job is completed, a banner appears and a new group proteinprep_3QDJ-out is added to the Entriesa simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion.
  5. Close the Protein Preparation Workflow panel.

Figure 3-7. Duplicating the prepared structure.

We will later use this structure for docking with PIPER, so we will need a copy of the structure without the crystallographic solvents.

 

  1. Right-click 3QDJ – prepared and choose Duplicate > Entries Only (In Place).

Figure 3-8. Including and renaming the duplicated entry.

  1. Includethe entry is represented in the Workspace, the circle in the In column is blue and double-click the duplicated entry and rename it to 3QDJ – prepared_dry.

Figure 3-9. Deleting water molecules from the duplicated structure.

  1. In the Hierarchy, expand Solvents and right-click Waters.
  2. Choose Delete Atoms.
    • All the water molecules are deleted from the duplicated structure.

4. Annotating the TCR Structure in the Multiple Sequence     Viewer/Editor

Annotations are a means of representing additional information associated with a sequence. In this section, you will compute TCR family features for specified sequences in order to annotate the TCR structure. Annotating the structure will help you identify the key amino acids and regions involved in binding to the peptide-MHC (pMHC) complex.

4.1 Use the Multiple Sequence Viewer/Editor to annotate the TCR structure

Figure 4-1.Opening the Multiple Sequence Viewer/Editor from Tasks.

  1. Includethe entry is represented in the Workspace, the circle in the In column is blue 3QDJ – prepared in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed.
  2. Find and select Multiple Sequence Viewer/Editor from Tasks.

Figure 4-2. Duplicating the chains D and E of TCR into another tab in the Multiple Sequence Viewer/Editor panel.

You can isolate the TCR chain sequences into a separate tab for clarity.

 

  1. In the Workspace tab, Ctrl+Click (Cmd+Click) to select chains D and E of the 3QDJ – prepared entry.
  2. Right-click the selected chains and choose Duplicate > Into Existing  Tab > View 1.

Figure 4-3. Renaming the tab and toggling off Wrap Sequences.

 

  1. Right-click the View 1 heading and rename it to TCR_chains.

 

You can adjust the view options to your preference. For viewing annotations, we recommend disabling sequence wrapping to improve legibility.

 

  1. Click the View Options icon in the bottom right corner of the panel.
  2. Toggle off Wrap Sequences.

 

Note: You can now horizontally scroll to view the complete sequence using the scroll bar.

Figure 4-4. Other Tasks pane in the Multiple Sequence Viewer/Editor.

  1. In the Toolbar, click Other Tasks.
  2. Click Identify Family Features.
    • The Identify Family Features dialog box opens.

Figure 4-5. Identifying family features for the TCR structure.

  1. Check T-Cell Receptor Regions.
  2. Click OK.
    • The sequences are annotated by regions.

 

Note: We recommend maintaining consistency with the numbering scheme. Recall that we selected the IMGT scheme during protein preparation.

Figure 4-6. Annotated TCR sequences in the Multiple Sequence Viewer/Editor.

  1. Inspect the annotated sequence.
  2. Close the Multiple Sequence Viewer/Editor panel.

AFR1, AFR2, AFR3, AFR4 are the framework regions of the α chain (Chain D) while A1, A2, and A3 correspond to the CDRα1, CDRα2, and CDRα3 respectively. Similarly, BFR1, BFR2, BFR3, and BFR4 are the framework regions of the β chain (Chain E) while B1, B2, and B3 correspond to the CDRβ1, CDRβ2, and CDRβ3 respectively.

 

For more information on how to analyze sequences in the Multiple Sequence Viewer/Editor, please refer to the Introduction to BioLuminate and the Multiple Sequence Viewer/editor tutorial.

5. Visualizing and Analyzing the TCR-peptide-MHC Interactions

In this section, you will visualize the TCR-peptide-MHC complex in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed using Preset rendering options. Presets are available to quickly apply common styles to biomolecules to facilitate easy visualization. These can be used in a variety of ways, from decluttering your structure to creating publication-quality images. Further, you will analyze the peptide-MHC interactions using the Interactions Toggle in the Workspace Configuration Toolbar and 2D Ligand Interaction Diagram. Further, you will also analyze the TCR-MHC interactions using the Protein Interaction Analysis panel.

5.1 Visualize the TCR-peptide-MHC complex

Figure 5-1. Applying the TCR specific Preset to the prepared complex structure.

  1. Go to Presets and choose T-Cell Receptor > IMGT.
    • The TCR-peptide-MHC complex is rendered in cartoon styled ribbon representation, with different colors showing different protein components.

Figure 5-2. Viewing the protein chains in the Hierarchy and the Status Bar.

You can hover over the structure to see the chain names in the Status Bar.

 

  1. Expand Protein in the Hierarchy.
    • Recall that the chains A (white) and B (orange) belong to the HLA-A2 MHC molecule, chain C (light green) is the nonameric peptide, and the chains D (purple) and E (green) form the DMF5 TCR.

Figure 5-3. Applying Surface representation to the chain A of MHC molecule.

A surface representation can help understand the topology of the protein-protein interface.

 

  1. Select(1) the atoms are chosen in the Workspace. These atoms are referred to as "the selection" or "the atom selection". Workspace operations are performed on the selected atoms. (2) The entry is chosen in the Entries (and Project Table) and the row for the entry is highlighted. Project operations are performed on all selected entries Chain A of the HLA-A2 molecule in the Hierarchy.
  2. Go to the Style Toolbox and click Surface.
    • A solid gray surface is applied.
    • The Surface menu appears next to the title in the Entriesa simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion.
  3. Rotate the structure to visualize the peptide binding groove formed by chain A of HLA-A2 molecule.

Figure 5-4. Disabling the surface representation.

  1. Click the S next to the 3QDJ – prepared_dry entry and uncheck QuickMolecularSurface to disable the generated surface.

 

Note: You can turn off the Surfaces Toggle in the Workspace Configuration Toolbar (bottom right corner) to hide all surfaces.

5.2 Analyze the peptide-MHC interactions

Figure 5-5. Displaying atoms of peptide-MHC in the Workspace.

To visualize the interactions in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed, it is essential to display the atoms involved in the interactions.

 

  1. Ctrl+Click (Cmd+Click) to select(1) the atoms are chosen in the Workspace. These atoms are referred to as "the selection" or "the atom selection". Workspace operations are performed on the selected atoms. (2) The entry is chosen in the Entries (and Project Table) and the row for the entry is highlighted. Project operations are performed on all selected entries Ligands (chain C) and Chain A in the Hierarchy.
  2. Right-click the selection and choose Display.
    • All atoms of chain A and chain C are displayed in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed.

Figure 5-6. Applying thick tube representation to the peptide.

  1. Select(1) the atoms are chosen in the Workspace. These atoms are referred to as "the selection" or "the atom selection". Workspace operations are performed on the selected atoms. (2) The entry is chosen in the Entries (and Project Table) and the row for the entry is highlighted. Project operations are performed on all selected entries Ligands in the Hierarchy.
  2. Go to the Style Toolbox and choose thick tube representation.
  3. Click Fit view to selected atoms buttons.
    • The Workspacethe 3D display area in the center of the main window, where molecular structures are displayed zooms to the peptide (chain C).

Figure 5-7. Visualizing the peptide-MHC interactions in the Workspace.

  1. Right-click the Interactions Toggle in the bottom right corner.
  2. Confirm the Non-covalent bonds and Pi interactions are all toggled on.
  3. Rotate the structure in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed and identify the peptide-MHC interactions.

Figure 5-8. Opening the Ligand Interaction Diagram from Tasks.

  1. Find and select Ligand Interaction Diagram from Tasks.
    • The 2D Ligand Interaction Diagram opens.

Figure 5-9. Visualizing peptide-MHC interactions in the 2D Ligand Interaction Diagram.

  1. Click the Configure view (settings) icon and check LID Legend.
    • The legend appears below the diagram.
    • Follow the legend and note the peptide-MHC interactions in the 2D Ligand Interaction Diagram.

 

Note: You can click the Clean up button to generate a less-cluttered orientation of the diagram.

 

Optional: Click the Export icon and save the image of the diagram. For visual clarity, we recommend modifying the resolution while saving the image.

 

  1. Close the Ligand Interaction Diagram panel.

The peptide forms multiple Hydrogen bonds with the residues of Chain A of the HLA-A2 MHC molecule. The following residues of chain A are involved in Hydrogen bonding with the peptide: TYR-7, GLU-63, HIE-70, ASP-77, TYR-84, TYR-99, LYS-146, TRP-147, TYR-159 and TYR-171. These interactions stabilize the binding of the peptide to the MHC binding groove. Further, the peptide binding groove of HLA-A2 also has hydrophobic and charged residues that enhance the binding affinity through non-polar and electrostatic interactions respectively. Understanding these peptide-MHC interactions is crucial for developing immunotherapeutic strategies.

 

You may create a Custom Set to easily access these binding site residues in the future. For details on how to create a Custom Set, refer to the Introduction to Structure Preparation and Visualization tutorial.

5.3 Analyze the TCR-pMHC interactions

Figure 5-10. Opening the Protein Interaction Analysis panel from Tasks.

The Protein Interaction Analysis panel can identify and highlight important contacts in the complex. The interactions are evaluated between two user-specified atom sets representing the TCR and the pMHC complex.

 

  1. Find and select Protein Interaction Analysis from Tasks.

Figure 5-11. Specifying chains for the interaction analysis.

  1. Under Interaction sets section, for Define sets by option, select Chain.
  2. For Set 1, click Add and select chains A and C (of pMHC).
  3. For Set 2, click Add and select chains D and E (of TCR).

 

Note: Distance thresholds for the interactions can be customized depending on the context of the analysis.

 

  1. Click Advanced Options.
    • A dialog box opens.

Figure 5-12. Modifying cut off distance for Hydrogen bond interactions.

The default cut-off for the maximum Hydrogen bond distance is very strict, so you will increase it to cover the mean donor-acceptor distance in proteins.

 

  1. For Hydrogen bonds, set the Maximum distance to 2.8 Å.

 

Optional: Compare the calculated interactions with the findings reported in the supplementary information of the publication.

 

  1. Click OK.

Figure 5-13. Sorting the Interactions table by Distance to view the TCR-pMHC interactions.

  1. Click Calculate.
    • The calculation will take a few seconds.
    • The Interactions table is populated.
  2. Click on the Distance heading to sort the table by distance.
  3. Check the Fit on Select option.
  4. Click on a table row to visualize the corresponding interactions in the 3D Workspacethe 3D display area in the center of the main window, where molecular structures are displayed.

 

Take your time to scroll and view the interactions in the Specific Interactions column. Additionally, scroll to the right or resize the window to view other column results.

 

Note: You can export the Interactions table as a CSV file by clicking on the Export Table option.

The Interactions table provides an overview of the important residue contacts in the TCR-pMHC complex. With few exceptions, both pMHC (Set1) and TCR (Set2) residues have high Buried SASA values, which depicts that these are most likely the interface residues. Since these residues are highly buried upon complex formation, they are significant contributors to the binding affinity. Further, the lack of van der Waals clashes suggests a stable interface.

 

As seen in the Specific Interactions column, multiple hydrogen bonds exist between these interface residues, playing a major role in stabilizing the entire complex. Particularly strong hydrogen bonds are present between C:ALA 2 and D:GLN 30 (1.8 Å) and A:GLU 58 and D:SER 25 (1.9 Å). Hydrogen bonds are also present between A:ARG 65 and D:PHE 92 (2.0 Å), A:GLU 166 and D:ASN 52 (2.0 Å), C:THR 8 and E:ASN 33 (2.0 Å), A:GLN 72 and E:ASN 53 (2.1 Å), C:ILE 4 and D:GLN 30 (2.1 Å), C:ILE 6 and E:SER 99 (2.5 Å), and A:GLU 166 and D:LYS 66 (2.7 Å), making the binding even stronger. Additionally, a salt bridge is formed between A:GLU 166 and D:LYS 66 (2.7 Å).

 

Other pMHC residues like A:THR 73, C:LEU 7, A:THR 163, A:ALA 150, A:TRP 167, A:VAL 76, A:HIE 70, A:GLN 155, A:ALA 158, A:GLY 62, A:ALA 69, A:TYR 159, and A:ARG 170 do not contribute to specific interactions, but are in close proximity with the TCR residues.

Figure 5-14. The Protein Interaction Analysis Diagram.

  1. Click Diagram.
    • The 2D Protein Interaction Analysis Diagram opens.
  2. Click the Configure View (settings) icon and check LID Legend.
    • Follow the legend to analyze the interactions.

 

Optional: Click the Export icon and save the image of the diagram. For visual clarity, we recommend modifying the resolution while saving the image.

 

  1. Close the Protein Interaction Analysis Diagram and the Protein Interaction Analysis panel.

6. Performing MM-GBSA Residue Scanning

In this section, you will perform the MM-GBSA Residue Scanning calculations. The goal is to identify key residues at the interface of the peptide–MHC–TCR complex that are critical for binding affinity. Affinity describes the strength of the binding interaction between a TCR and the peptide-MHC complex i.e. it is a measure of how tightly the TCR binds to the peptide presented by the MHC molecule. By systematically mutating individual residues to alanine, you can assess their contribution to the binding strength between the TCR and the peptide–MHC complex.

6.1 Set up an MM-GBSA residue scanning calculation

Figure 6-1. Opening the MM-GBSA Residue Scanning Calculations panel from Tasks.

  1. Find and select MM-GBSA Residue Scanning Calculations from Tasks.

Figure 6-2. The MM-GBSA Residue Scanning panel with modified settings.

  1. In the MM-GBSA Residue Scanning panel, for Import structure from, choose Workspace.
  2. Click Import.
    • The Residues table is populated.

 

You need to specify the calculation type and which PDB chains correspond to each binding partner (TCR and pMHC).

 

  1. For Calculation type, choose Stability and Affinity.
  2. For Binding partners, uncheck D and E in the Chains menu.
    • Chains A, B and C (of pMHC) are binding to chains D and E (of TCR).

Figure 6-3. Selecting all the CDR residues.

You will mutate the CDR residues to ALA and will analyze the change in affinity and stability for the mutated structure.

 

  1. Under Quick Select, click the Choose item button (three horizontal dots) and select TCR CDRs > All CDRs.
    • All the CDR residues are selected in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed and in the Residues table.

Figure 6-4. Mutating the CDR residues to Alanine and running the MM-GBSA Residue Scanning job.

  1. For Set mutations for, choose Selected residues.
  2. Click Apply.
    • Where possible, the CDR residues mutate to Alanine.

 

Note: The number of residues in the CDRs is 56, but only 53 mutants will be investigated. This is because the selection includes Alanine residues (which you might want to mutate to Glycine instead), and Cysteine residues part of Disulfide bridges.

 

  1. Change the Job name to CDR_residue_scanning.
  2. Click Run.
    • This job takes ~ 1 hour to complete on a single CPU.
    • Once the job is completed, the MM-GBSA Residue Scanning Viewer panel opens.  

Note: To save time, you will use the pre-generated results.

 

  1. Close the MM-GBSA Residue Scanning panel.

6.2 Examine the pre-generated MM-GBSA residue scanning results

Figure 6-5. Opening the MM-GBSA Residue Scanning Viewer panel from Tasks.

  1. Find and open MM-GBSA Residue Scanning Results from Tasks.
    • The MM-GBSA Residue Scanning Viewer panel opens.
  2. For Load results from, choose File.
  3. Click Browse.

 

Figure 6-6. Selecting the input file for analyzing the MM-GBSA Residue Scanning results.

  1. Navigate to the CDR_residue_scanning folder and find CDR_residue_scanning-out.maegz.
  2. Click Open.
    • The Mutations table is populated.
    • ΔStability (solvated) vs ΔAffinity graph is shown below the Mutations table.

 

Note: You can click the column headings in the Mutation table to sort the table by the corresponding property. Additionally, you can scroll to the right to see the values for other properties.

ΔStability (solvated) and ΔAffinity and values are most helpful in assessing the potential impact of a mutation.

 

Interpreting ΔStability

Stability is the change in the Gibbs free energy of folding (ΔGfolding) i.e. it is the difference between the native (folded) state and the denatured (unfolded) state of a protein. A more negative ΔGfolding means a more stable protein. ΔStability measures how a mutation changes the overall stability of a protein i.e. it measures the change in the folding free energy of the protein itself upon mutation – independent of ligand (substrate) binding.

 

ΔStability = ΔGstability (mutant) – ΔGstability (wild-type)

Where                                                 ΔGstability = Gfolded – Gunfolded

 

Interpreting ΔAffinity

Affinity is the change in the Gibbs free energy of binding (ΔGbinding) i.e. it is the energy difference between the bound and unbound states. A more negative ΔGbinding means a stronger, more favorable binding interaction. ΔAffinity measures how a mutation changes the binding strength between a protein (enzyme) and its binding partner.

 

ΔAffinity = ΔGaffinity (mutant) – ΔGaffinity (wild-type)

Where                                              ΔGaffinity = Gbound – Gunbound

 

Figure 6-7. Plot showing correlation between ΔStability (solvated) and the ΔAffinity for the residue mutations.

  1. On the graph, click and drag to select the peaks shown in the adjacent figure.
  2. Check Sync selection with mutations table.
    • Filtered results are now selected in the Mutations table.

The graph displays a correlation between ΔStability (solvated) and the ΔAffinity for the generated mutations. Each point corresponds to a specific mutation, with its position determined by how the mutation affects the system’s stability (X-axis) and binding affinity (Y-axis).

 

The horizontal dashed line at y = 0 represents no change in binding affinity, allowing easy identification of mutations that have either favorable (below the line) or unfavorable (above the line) impacts on the system’s binding affinity. A high positive ΔAffinity value reflects a substantial loss in binding strength when the residue is mutated to ALA.

 

Most mutations result in ΔAffinity values fluctuating within a relatively narrow range indicating minor effects on binding affinity. However, there are a few notable outliers corresponding to mutations of the following residues: D:ARG 27, D:GLN 30, D:GLY 93, E:PHE 100, and E:GLY 101, where values spike sharply suggesting these mutations significantly decrease binding affinity. Among these outliers, residues like D:ARG 27, D:GLY 93, and E:PHE 100 (highlighted points in the above plot) represent high ΔAffinity values but relatively low ΔStability (solvated) values upon ALA substitution. This indicates that these residues play an important role in binding with the peptide-MHC, even though they contribute modestly to the overall structural stability of the complex. These residues must be conserved to retain or enhance affinity during affinity maturation or rational design of engineered TCRs.

Figure 6-8. Analyzing the change in stability due to residue mutations.

  1. Optional: For X-axis, choose Mutant Row Number.
    • The graph is updated to show ΔStability (solvated) values for each mutation.
  2. On the graph, click and drag to select the region that corresponds to ΔStability (solvated) values less than zero (below Y = 0 line).

 

Note: Negative ΔStability (solvated) values correspond to favorable mutations.

As seen in the above graph, most of the mutations result in positive ΔStability (solvated) values, indicating they are destabilizing. Mutations to only a few residues like D:GLY 53, E:GLY 56, E:LYS 60, E:GLY 66, and E:GLU 103 (highlighted in the above graph) are favorable.

 

Mutations to D:GLN 30, D: PHE 92, and E:ASN 33 are not favorable. This is because the side chains of the residues are involved in hydrogen bond interactions with the residues of the peptide-MHC complex (as seen in the results of Protein Interaction Analysis). Further, Phenylalanine has a bulky, aromatic ring which engages in hydrophobic and Pi interactions. Therefore, mutations to residues like D:PHE 92 results in a loss of stabilizing interactions and disrupts the protein’s structure as replacing Phenylalanine with the much smaller Alanine creates cavities or voids.

 

Glycine, being the smallest amino acid with just hydrogen side chain, is highly flexible, and can fit into constrained backbone conformations like loops, turns, etc. Therefore, when the residues D:GLY:94, D:GLY 95, and E:GLY 101 within the CDR loops of α and β chains are mutated, the flexibility is disrupted making these mutations unfavorable resulting in high positive Δ Stability (solvated) values.

Figure 6-9. Analyzing the change in affinity due to residue mutations.

  1. Optional: For Y-axis, choose ΔAffinity.
    • The graph is updated to show ΔAffinity values for each mutation.
  2. On the graph, click and drag to select the outliers.
  3. Take your time to inspect these outliers.

 

Note: Negative ΔAffinity values correspond to favorable mutations.

7. Running and Analyzing TCR-pMHC Docking Job

In this section, you will perform a pMHC - TCR docking calculation. Re-docking the structure with the original sequence before investigating any mutants is always recommended to validate that the structural model, preparation, and docking setup are sound.

Since both the receptor and ligand are proteins, you’ll use the Protein-Protein Docking panel, which interfaces with the PIPER docking engine. PIPER uses a Fast Fourier Transform (FFT)-based approach to rapidly explore numerous orientations of the two proteins, scoring them based on shape complementarity, electrostatics, and atomic pairwise interactions.

By default, PIPER retains the top 1000 scoring poses and clusters them based on the RMSD between matching atoms in each pair. From each cluster, a representative pose is selected – the one with the most neighbors in the cluster. Typically, only the largest ~ 30 clusters are returned, as they are most likely to include near-native conformations.

However, for this tutorial, we will go beyond the default and investigate all 1000 top-scoring poses directly. Instead of relying solely on clustering, we will apply alternative criteria – such as raw PIPER energy scores – to rank the outputs. This approach illustrates how users can extract the full set of top-scored poses and apply a customized ranking strategy suited to specific needs or analysis goals.

For detailed information on how PIPER works, refer to this website and this publication. For more information on the Protein-Protein Docking panel, refer to the documentation.

Please note that we are using a prepared structure for performing docking. If you are following along with a different structure, make sure your structure is prepared using the Protein Preparation Workflow.

7.1 Split the TCR-peptide-MHC complex

Figure 7-1. Copying the peptide-MHC chains to a new entry.

 

For performing the docking calculation, you will split the dry structure into peptide-MHC (ligand) and TCR (receptor). In protein-protein docking, it is good practice to treat the larger protein as the receptor and the smaller one as ligand.

 

  1. Includethe entry is represented in the Workspace, the circle in the In column is blue 3QDJ - prepared_dry in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed.
  2. Go to Presets and choose T-Cell Receptor > IMGT.
  3. In the Hierarchy, expand Ligands and Protein.
  4. Ctrl+Click (Cmd+Click) to select Ligand 1, Chain A, and Chain B.
  5. Right-click the selection and choose Copy to New Entry.
    • A new entry is added to the Entriesa simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion and is includedthe entry is represented in the Workspace, the circle in the In column is blue in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed.
    • A banner to set a name for the new entry appears.

Figure 7-2. Renaming the newly created entry for the peptide-MHC complex.

  1. In the banner, change the Entry title to peptide-MHC and click the adjacent tick mark.
    • The entry is renamed to peptide-MHC.

 

Note: You can also double-click any entry title to rename it.

Figure 7-3. Copying the TCR chains to a new entry.

  1. Includethe entry is represented in the Workspace, the circle in the In column is blue 3QDJ – prepared_dry in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed.
  2. In the Hierarchy, expand Protein and select(1) the atoms are chosen in the Workspace. These atoms are referred to as "the selection" or "the atom selection". Workspace operations are performed on the selected atoms. (2) The entry is chosen in the Entries (and Project Table) and the row for the entry is highlighted. Project operations are performed on all selected entries T-Cell Receptor.
  3. Right-click the selection and choose Copy to New Entry.

Figure 7-4. Renaming the newly created entry for the TCR chains.

  1. In the banner, change the Entry title to TCR and click the adjacent tick mark.
    • The entry is renamed to TCR.

7.2 Set up a docking calculation with restraints

Figure 7-5. Opening the Protein-Protein Docking panel from Tasks.

  1. Includethe entry is represented in the Workspace, the circle in the In column is blue TCR in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed and select(1) the atoms are chosen in the Workspace. These atoms are referred to as "the selection" or "the atom selection". Workspace operations are performed on the selected atoms. (2) The entry is chosen in the Entries (and Project Table) and the row for the entry is highlighted. Project operations are performed on all selected entries peptide-MHC in the Entriesa simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion.
  2. Find and open Protein-Protein Docking from Tasks.

Figure 7-6. Specifying TCR chains as Receptor for docking.

 

You will perform the docking in the Standard Mode. While Antibodies are similar to TCRs, the Antibody mode is not suited for our purposes.

 

  1. In the Structures to Dock section, click the Receptor option menu and select From the Workspace.
    • Multiple Chains Found dialog box opens.
  2. In the dialog box, Ctrl+click (Cmd+click) to select Chains D (199 residues) and E (242 residues).
  3. Click OK.

Figure 7-7. Specifying peptide-MHC chains as Ligand for docking.

  1. Click the Ligand option menu and select From Project Table (selected entry).
    • Multiple Chains Found dialog box opens.
  2. In the dialog box, Ctrl+click (Cmd+click) to select Chains A (275 residues), B (100 residues), and C (9 residues).
  3. Click OK.

Figure 7-8. Assigning restraint to TCR (receptor) for docking.

 

Now you will add restraints to ensure that the peptide-MHC docks correctly onto the CDR loops of the TCR. This will prevent unrealistic interactions, such as binding to the constant or framework regions of the TCR.

 

  1. Go to the Attraction and Repulsion tab.
  2. Click Add Restraint button.
    • You can now see the Restraints table columns.
  3. Under Type, choose Repulsion.

There are two categories of restraints in the Protein-Protein Docking panel: Attraction/Repulsion and Distance. Further, there are three types of attraction and repulsion restraints for Protein-Protein Docking. The Attraction restraint increases the attractive potential of specified residue to participate in binding. The Buried restraint increases the van der Waals radius of selected atoms or residues so that they are deeply buried. The Repulsion restraint sets the attractive potential of the specified residue to zero, such that only the repulsive van der Waals energy term is taken into account.

Figure 7-9. Selecting all the non-CDR residues.

You will specify all the non-CDR residues for this restraint so that their attractive potential is set to zero and hence, they do not influence the binding.

 

  1. Under Quick Select, click the Choose item button (three horizontal dots) and select TCR CDRs > All CDRs.
  2. In the Selection toolbar, click Invert to invert the current selection.
    • All the non-CDR residues are selected.

 

Note: You can always see the current selection in the Hierarchy.

Figure 7-10. Specifying the non-CDR residues for assigning restraint.

  1. In the Restraints table, under Residues, click Click to specify and choose From Workspace Selection.

Figure 7-11. Assigning restraint to the peptide-MHC (ligand) for docking.

You will add another restraint since all the 9 residues of the peptide and only the first 180 residues of the MHC are involved in binding with the TCR.

 

  1. Click Add Restraint button.
  2. Under Type, choose Repulsion.
  3. Under Component, choose Ligand.

Figure 7-12. Defining peptide-MHC residues to assign restraint.

There are many different ways to select the relevant residues. In the next few steps, we’ll show you how to construct it using the Atom Specification Language (ASL) using the GUI.

 

  1. Includethe entry is represented in the Workspace, the circle in the In column is blue peptide-MHC in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed.
  2. Click Define.
    • The Atom Selection dialog box opens.

Figure 7-13. Adding chain A of MHC.

  1. Go to the Chain tab and select chain A.
  2. Click Add.

Figure 7-14. Specifying residues of MHC involved in binding with the TCR.

  1. Go to the Residue tab > Residue number.
  2. In the Residue number text box, type 1-180.
  3. Click Intersect.

Figure 7-15. Adding chain C (peptide).

  1. Go to the Chain tab and select chain C.
  2. Click Add.

Figure 7-16. Inverting the current selection to select all the residues not involved in the binding.

  1. Click Invert.
  2. Click OK.
    • Chain A residues numbered greater than 180, along with all residues of chain B are selected.  

Note: For more information on the Atom Specification Language, see the documentation.

Figure 7-17. Specifying pMHC residues for assigning restraint.

 

  1. Under Residues, click Click to specify and choose From Workspace Selection in the Protein-Protein Docking panel.
  2. Change the job name to TCR-pMHC_docking.
  3. Optional: Click Run.
    • This job will take ~3 hours to run on a single CPU.
    • Once the job is completed, a banner appears and a new group TCR-pMHC_docking-out is added to the Entriesa simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion.
    • The number in the parentheses shows the number of docked poses obtained as output.
    • You can find the pre-generated results in the tutorial zip archive.

 

Note: The TCR-pMHC_docking-out group contains one representative pose from each cluster. Since there are 30 clusters, it has 30 representative poses.

 

  1. Close the Protein-Protein Docking panel.

7.3 Examine the pre-generated docking results

Figure 7-18. Importing the clustered structured files for analyzing the results of docking.

  1. Go to File > Import Structures.
  2. Open the TCR-pMHC_docking folder and shift-click to select all the 30 clustered structure files.
  3. Click Open.
    • This will take a few seconds.
    • A banner appears confirming successful import of all the 30 clustered structure files.

Figure 7-19. Ungrouping all the clustered groups.

To find the best poses, you have to extract the poses from the cluster-based groups so you can sort the results by the PIPER pose energy.

 

  1. Right-click the TCR-pMHC_docking_cluster_1_out_pv group and choose Ungroup Groups.
    • All the clustered groups are ungrouped.

Figure 7-20. The Show Property option in Change table settings.

  1. Click the Change table settings icon (three vertical dots) and choose Show Property.
    • The Show Properties in Table dialog box opens.

Figure 7-21. Choosing PIPER pose energy to add as a property in the table.

  1. In the dialog box, click Choose.
  2. From the List, find and select PIPER pose energy.
  3. Click OK.
    • The PIPER pose energy column is added to the table.

Figure 7-22. Sorting the table in ascending order of PIPER pose energy.

  1. Right-click the PIPER pose energy heading and choose Sort Selected (Ascending).
    • The poses are sorted by PIPER pose energy, with the pose having the most negative energy shown at the top.

Figure 7-23.Comparing the pose with most negative PIPER pose energy with the crystal structure.

  1. Double-click the In circle of the 3QDJ - prepared_dry.
    • The structure is pinned which implies it is fixed in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed.
  2. Includethe entry is represented in the Workspace, the circle in the In column is blue cluster_2_pose_1 in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed.
  3. Use the right and left arrow keys to visualize the other poses in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed.

Out of all 1000 poses, cluster_2_pose_1 (cyan in the previous figure) has the most negative PIPER pose energy and is a close fit to the crystal structure. Our docking model has therefore successfully recovered a close match to the crystallographic pose, and we can continue using it to investigate any mutant constructs.

8. Conclusion and References

In this tutorial, you learned how to prepare and visualize key interactions in TCR-peptide-MHC complex structures. You also learned how to annotate TCR sequences in the Multiple Sequence Viewer/Editor and analyze protein-protein interactions. Further, you performed MM-GBSA Residue Scanning to identify residues crucial for binding affinity and stability of the complex. Finally, you performed TCR-pMHC docking to predict the TCR-pMHC binding modes.

For further reading:

 

9. Glossary of Terms

Entries - a simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion

Included - the entry is represented in the Workspace, the circle in the In column is blue

Project Table - displays the contents of a project and is also an interface for performing operations on selected entries, viewing properties, and organizing structures and data

Recent actions - This is a list of your recent actions, which you can use to reopen a panel, displayed below the Browse row. (Right-click to delete.)

Scratch Project - a temporary project in which work is not saved, closing a scratch project removes all current work and begins a new scratch project

Selected - (1) the atoms are chosen in the Workspace. These atoms are referred to as "the selection" or "the atom selection". Workspace operations are performed on the selected atoms. (2) The entry is chosen in the Entries (and Project Table) and the row for the entry is highlighted. Project operations are performed on all selected entries

Working Directory - the location where files are saved

Workspace - the 3D display area in the center of the main window, where molecular structures are displayed