Skip to content

Engineering

Generate variant designs and build new antibodies based on these designs. Optimized leads have improved developability critical for downstream processing and manufacturing.

This tool is useful for engineering antibodies to improve their developability. The tool lists desired mutations entered via the Liabilities or PFA, or directly in the Engineering tool. The tool can be used to generate combinatorial variant designs and build new antibodies based on these designs.

Using the Engineering tool exemplifies the core work principle to "Be Inherently Lazy"—working very hard to build an easy, reproducible, and error-eliminating method to do work. Rather than copying a parent sequence in Excel multiple times and editing mutations in the copied versions by hand to generate combinatorial variants (which is slow, repetitive, and prone to human error), you can use the Engineering tool to design, filter, and build complex combinations in a fraction of the time with absolute consistency.

Accessing the Tool

Select exactly one antibody in the Project View. Go to the Edit menu and select Engineering. This will open the Engineering workspace in a new tab.

Engineering Mutation Designs: EngineeringMutationDesigns Engineering Variant Designs: EngineeringVariantDesigns

Using the Tool

  • Mutation Sets: Mutations are grouped into Sets, allowing you to manage parallel design paths (e.g., one set for humanization, another for liability removal) on the same antibody without overlapping configurations.

    • The Default set is the standard workspace and cannot be deleted. The tool always opens to this set by default.
    • Use the ⋮ menu next to the set dropdown to create a New Set Name or delete the current set.
    • Mutations from any set will show as an indicator dot in other tools, but only the Default set mutation will show in the Engineering modal in those tools.

  • Library Mutagenesis & Deep Mutational Scanning (DMS) Data: You can upload client library mutagenesis data (e.g., Deep Mutational Scanning / DMS binding permissibility files) to guide antibody engineering and candidate selection.

    • Importing & Managing Data: Click Library ▾ on the Mutation Designs toolbar to access all library actions from a single menu: Import Library Data, View Uploaded Library Data, Create Set from Library, and Clear Uploaded Library Data. Supports standard 5-column CSV/TSV files (Chain, Position, Parental, Mutant, IsSafe/BindingScore) as well as multi-tab Excel workbooks (.xlsx/.xls) or matrix-formatted CSV files. Matrix formats feature combined mature position headers (e.g. 1N, 2F, 3M... or N1, F2, M3...) and row amino acid labels (A, D, E...) with YES/NO permissibility cells. Sheet/tab names are irrelevant as Heavy vs Light chain assignments and sequence alignment offsets are determined dynamically.
    • Lineage Inheritance (Parents, Children & Grandchildren): Library mutagenesis data uploaded to a parent antibody is automatically inherited down the lineage tree by all descendant variants (children, grandchildren, etc.). If a child variant does not have its own directly uploaded library data, it recursively traverses its lineage tree to pull library data from the nearest ancestor, explicitly displaying a <i class="fas fa-sitemap"></i> Inherited from Parent: <AncestorName> badge in all engineering modals and library views. If a child variant later has a custom library dataset uploaded directly to it, its direct library data takes precedence.
    • Allowed Column in Mutation Designs Table: The Mutation Designs grid includes an Allowed column displaying real-time permissibility status for every entered mutant amino acid at each position based on uploaded library mutagenesis data. Permissible mutants display green badges (A, D), low binding/unsafe mutants display red badges (K), and hover tooltips report exact binding scores.
    • Overwrite Confirmation Warning: If a library dataset is already uploaded on the target antibody, uploading a new file triggers a dedicated Overwrite Library Data? confirmation modal (#libOverwriteConfirmModal, styled after Assembler workspace warnings) warning that uploading a new file will replace existing library data.
    • Viewing Uploaded Data: Select View Uploaded Library Data from the Library ▾ menu to launch an interactive modal displaying the full library matrix aligned to Mature Linear 1-based position numbers (skipping leader sequences). Every column header features native column filtering (with floating popovers supporting operators like >0.8, <=1, ranges 0.5-1.0, and text matches) and 3-click sort cycling (1st click = Ascending fa-sort-up, 2nd click = Descending fa-sort-down, 3rd click = Reset to Default sort with Light chain before Heavy chain), plus CSV export capabilities.
    • Parental Residue Mismatch Validation: The required Parental amino acid column is used for sequence integrity validation. If position numbers in the file do not match the expected parental residue in the target antibody sequence (e.g., due to leader sequence offsets or scheme mismatch), the system displays a Parental Residue Mismatches Detected warning modal listing the mismatched positions, allowing you to review your file or force-import if desired.
    • Mature Linear Mapping: Uploaded position numbers represent Mature Linear sequence positions (1-based index starting after the signal leader offset) and are automatically mapped to canonical IMGT scheme positions.
    • Create Set from Library: Select Create Set from Library from the Library ▾ menu to automatically extract all permissible substitutions (IsSafe=true) into a named Mutation Set for combinatorial variant generation.
    • Clear Library Data: Select Clear Uploaded Library Data from the Library ▾ menu to permanently remove the uploaded library matrix from the antibody. This option, View Uploaded Library Data, and Create Set from Library are automatically grayed out when no library dataset is present.
    • Shared Modal Integration: Uploaded library data is exposed across all tools (Alignment, Humanness, PFA, Liabilities, Clading, Surface Properties, Solvent Exposures, etc.). Clicking any residue opens the shared Engineering modal, displaying a Library Mutagenesis Data card with green/red permissibility badges and binding scores, plus a Use Safe Mutants button to auto-populate engineering designs.

  • Edit Menu: Select mutations in the grid to enable the Edit dropdown menu in the toolbar. From here, you can Edit Mutation (if only one is selected), Delete selected mutations, or use Copy / Move to Set... to launch a dedicated transfer modal where you can select Copy or Move and choose the target set. If an entry already exists at the target sequence position in the destination set, a Target Set Conflict modal provides options to Merge (combining proposed mutations, notes, and groups with existing entries) or Overwrite before proceeding.

  • Pairing Designs: Sometimes residues are designed in pairs. For example, a fragmentation site might be DP, and mutating to either EP or DR would disrupt that site, but ER would not be needed. Or, a pair of residues should be mutated together and not separately, such as a missing HC-CDR3 salt bridge in both positions or a pair of unusual cysteines. Select two or more mutations in the grid and open the Edit menu in the toolbar to apply pairing settings:

    • Pair Selected (Single): Groups the selected mutations under a new Pair ID. During variant generation, at most one mutation in this pair will be present in any generated variant (ensuring they are never made together). If "Include Parental" is not checked it is forced on the pair to enable variant generation.
    • Pair Selected (Together): Groups the selected mutations under a new Pair ID. During variant generation, all mutations in the pair must be made together (or not at all), ensuring they are never made separately.
    • Unpair Selected: Clears the pairing group and returns the selected mutations to standard independent mutations.

  • Mutation Designs: Click a residue in the Sequence tab, or in a tool supporting Engineering such as Alignment, PFA, or Liabilities, to open a mutation design. Mutation designs may be edited. The parental residue may be included in the variant design set or not. A parental residue is usually included if the user suspects the position may be necessary for function, in which case mutating the site would be risky. Use '-' to delete the residue.

  • Observations: Click a residue to enter an observation for that IMGT position. These are displayed in the Observations tab and on a clicked residue.

  • Min & Max Mutations Filters: Directly above the toolbar, you can specify Min Mutations and Max Mutations limits (defaulting to NA). The dropdown options populate dynamically based on the number of checked mutational designs in your grid. For example, if you check 16 mutation designs and set Min to 3 and Max to 5, only combinatorial variants carrying exactly 3, 4, or 5 mutations relative to the parental sequence will be generated.

    • The dynamic combination counter below the toolbar (e.g., 16 selected, 6,748 combos) automatically recalculates in real-time to show the exact number of combinations that satisfy these criteria.

  • Generate Variant Designs: First, use the Set dropdown to ensure you are viewing the correct set of mutations. Then, use the Generate dropdown menu in the toolbar to build combinations from that active set. The variant designs may be generated with parental residues as defined in the mutation designs using "Generate Combinations", or all parental residues ignored using "Generate Combinations (Non-Parent)". Only variants matching your active Min/Max filters will be generated.

  • Variant Designs: The generated designs are displayed in the Variant Designs tab. Designs may be deleted or selected for building new antibodies.

  • Build FASTA: Selected variant designs may be used to build and download a FASTA file.

  • Build Selected: Selected variant designs may be used to build new antibodies. New antibodies are added to the project and the parent antibody is assigned.

Using Sets - An Example

  1. Select Humanization on a parent entry.
  2. Select the Sapiens "Suggest Mutations" and click "Apply Mutations".
  3. From the main grid select Engineering for the parent entry.
  4. In the upper right in Mutation Designs select the vertical dots menu, New Set Name, enter "Humanization - Sapiens", and click Save.
  5. Select the mutations in the grid and select Edit > Move to Set > Humanization - Sapiens.

You now have a set of mutations isolated as "Humanization - Sapiens". You could then return to the Humanization tool, perform a different humanization and save its mutations as its own set. You can build combinatorial variants by first selecting the desired set and mutants, and then using Generate.

Importing Library Mutagenesis Data - Examples

Option A: Standard 5-Column CSV / TSV Format

Prepare a CSV file containing 1-based Mature Linear position numbering:

Chain,Position,Parental,Mutant,BindingScore,IsSafe
L,33,N,Q,1.1,true
L,33,N,T,0.8,true
L,33,N,P,0.1,false

Option B: Multi-Tab Excel Matrix Format (.xlsx / .xls)

Prepare an Excel workbook where columns represent position numbers paired with their parental amino acid (e.g., 1N, 2F, 3M... or N1, F2, M3...), and rows represent candidate amino acid substitutions. Cell values indicate permissibility (e.g. YES, TRUE, 1, or numeric binding score \(\ge 0.5\) for safe; NO, FALSE, 0, or \(< 0.5\) for unsafe):

AA 1N 2F 3M 4L 5V 6E 7S 8G 9G 10G
A YES NO NO NO YES NO YES NO NO NO
C NO NO NO NO NO NO NO NO NO NO
D YES NO NO NO NO YES NO NO NO NO
E YES NO NO NO NO YES NO NO NO NO
F NO YES NO NO NO NO NO NO NO NO

Note on Excel Workbooks: Separate worksheets (e.g. Light Chain and Heavy Chain tabs) are automatically processed. The importer aligns sequence positions and infers Heavy vs. Light chain assignments automatically, so sheet tab names do not need to follow any strict naming convention.

Lineage Inheritance in Child & Grandchild Antibodies

When building or analyzing child variants (e.g., Parent_M.001 or grandchild Parent_M.001_v2), library mutagenesis data uploaded to any ancestor is automatically inherited across the entire project lineage:

  1. Automatic Inheritance: Children and grandchildren inherit the parent's library matrix automatically without requiring re-uploading.
  2. Visual Source Annotation: All residue modals and library views explicitly display an Inherited from Parent: ParentName source badge to indicate inherited authority.
  3. Override Priority: If a child antibody has a custom library matrix directly uploaded to it, its direct library data takes precedence over ancestor data.