search

JamesSweetJones / abYdraw

Input expressions of antibodies in AbML format and output drawings of their shape
GNU General Public License v3.0
3 stars 1 forks source link

readme

abYdraw

abYdraw is a program designed to use our group's Antibody Markup Language (AbML) for describing all antibody based drug formats including fragments, normal antibodies, multispecific antibodies (MsAbs) and antibody fusions (with specific support for T-Cell receptor domains) either by inputting an AbML descriptor string of an antibody-based drug, or by drawing a structure and outputting its descriptor string. It is written in Python 3 with both command-line and graphical interfaces built using the standard package TKinter in order to make it as accessible as possible.

Contents

  1. AbML
  2. Installing and Executing
  3. Interface
  4. Inputting AbML
  5. Obtaining AbML
  6. Formats Library
  7. Saving and exporting
  8. Settings

Reference: James Sweet-Jones, Maham Ahmad & Andrew C.R. Martin (2022) Antibody markup language (AbML) — a notation language for antibody-based drug formats and software for creating and rendering AbML (abYdraw), mAbs, 14:1, DOI: 10.1080/19420862.2022.2101183

Software authors: James Sweet-Jones and Andrew Martin (Darwin Building, University College London, Gower Street, London)

1. AbML

AbML Guide Sheet AbML was derived from existing macromolecule descriptor languages, but we have compensated for their limitations and made AbML simple, whilst conveying as much useful information as possible. Strings are split into chains, which are then split into domains. Each domain type has its own symbol and each domain unit also carries additional information including: modification types; the specificity of the variable region (if applicable); a number label assigned to the domain and the number label(s) assigned to the domain(s) it interacts with; the number of disulphide bonds between the two interacting domains and comments outlining additional information not covered by the language of types: TYPE; NOTE; MOD; ANTI and LENGTH. TYPE and MOD are limited to reserved keywords in block capitals while other comments are not restricted and written in lower case.

AbML expression for a standard IgG molecule would be:

VH.a(1:6)-CH1(2:7){1}-H(3:10){2}-CH2(4:11)-CH3(5:12) | VL.a(6:1)-CL(7:2){1} | VH.a(8:13)- CH1(9:14){1}-H(10:3){2}-CH2(11:4)-CH3(12:5) | VL.a(13:8)-CL(14:9){1}

Full documentation of AbML is available on the AbML website: AbML Documentation.

2. Installing and Executing

Requirements

This script requires tkinter 8.6 or newer to run. If you are experiencing issues running the script please check your version of tkinter with:

import tkinter
tkinter.TkVersion

Newer versions of tkinter may be installed from: https://tkdocs.com/tutorial/install.html

Command Line Interface

As well as a graphical interface, abYdraw has a Command Line based interface which may be accessed by executing the script with suitable arguments.

usage: python abYdraw [options]

optional arguments:

either -f or -i arguements are required to run the script and other options may be toggled between 0 (off) and 1 (on).

Graphical Interface

abYdraw may be downloaded and the GUI may be opened by executing the Python script without arguements.

python <path/to/file>/abYdraw.py
Compiling abYdraw

However, it may also be compiled into an executable file using py2app and the setup.py file provided, which may then be moved into the user's operating system's applications folder for convenient startup.

Install a virtual environment:

pip install virtualenv
virtualenv venv --system-site-packages

Then open a virtual environment and install py2app

source venv/bin/activate
pip install -U py2app

Finally, run py2app with the setup.py file

python <path/to/file>/setup.py py2app -A

This command will generate ./build ./dist folders. Your compiled app will be in the ./dist folder.

Precompiled versions of abYdraw are available for Windows and MacOS on our research group's website

3. Graphical Interface

abYdraw Interface

The program interface includes six points of reference, four of which are in a column on the left hand side and two more on the right hand side. Starting with the left hand column, the first is the Domain palette (A) which has buttons necessary for drawing antibody domains. To switch between Immunoglobulin and T-cell receptor domains, use the tab at the top of the palatte. Underneath is a library of commonly used antibody AbML expressions (B), thirdly the input box for AbML expressions (C) and a buttonpad that will render antibody schematics or output AbML to the textbox (D). On the right hand side, the most prominent feature is the canvas for drawing and rendering antibody schematics (E) and underneath there are two buttons which are involved in exporting the schematic (F).

4. Inputting AbML

AbML descriptor strings my be input in the entry box or opened in the File>Open menu and then by clicking Get Structure, a schematic of that antibody will render in the canvas. Schematics are drawn in colour-coded fashion depending on any specificities given in the descriptor chain. Domains are connected by different kinds of linkers which are also colour-coded depending on their type. Any comments given in the descriptor string are also displayed beside the schematic. Labels on the schematic may be toggled on and off using the Labels key on the Domain Palette.

5. Generating AbML

Drawing Domains

To draw an antibody, you must insert domains onto the canvas and arrange them so the program recognises it as an antibody. Tools for adding domains to the canvas are in the Domain Palette which contains all of the domain types, modifications, specificities and comment types as described in the AbML guidesheet as well as some options. Selecting a button on the palette will cause it to flash red to indicate it has been switched on. Only one domain or connector type may be switched on at a time, but you may choose any combination of modifications and specificities to accompany your selection. Specificity types are only applicable to variable domains where if no specificity is selected, it will be rendered as a default a value. Mulitple specificities may be selected by right-clicking the first specificity and left-clicking subsequent specificities. Once a domain is selected you will notice the cursor will change from an arrow to a "+" sign. This means you can left-click to insert your chosen domain type onto the canvas at the location you have clicked.

Connecting Domains

Domains may be connected with the connector options in the first column of the palette. When a connector type is selected it will become highlighted in red and the user must click and drag the bond from its starting position to its end, making sure each end is inside the boundaries two domains it links. Bonds are unidirectional and start from N-terminus to C-terminus.

Domain Comments

Comments may be added by selecting a comment type, which will highlight the button just pressed and the Comment button and then inputting the comment into the entry box beneath the palette, However, TYPE or MOD comments must be selected from the appropriate drop-down boolean lists because these are reserved values in AbML. Comments may then be drawn on the domains they are applicable to. To disable commenting, ensure the comment type and Comment buttons are no longer highlighted.

Editing Drawings

If no domain types or modifications are selected, but a modification or specificity is, then by clicking on a domain on the canvas, you may replace its current specificity and modification with those that are currently selected. To remove a modification, specificity or comment from a domain, select the feature you wish to remove from the Pallete and click a domain which already has that feature. The feature will then be removed from the Domain and using Tidy will remove the features from the AbML string and the schematic.

Additionally if no Domain Pallete buttons are selected, domains, linkers and comments may be rearranged by clicking and dragging them when the cursor is in the "Fleur" configuration (a cross with arrows at all points). You must ensure that interacting domains are positioned close together at roughly the same level and that VH and VL domains face each other to complete their antigen binding domains. If the new position of the domains no longer links any connectors originally inside those domains, the original connectors are deleted. Domain orientations can be changed by right-clicking the relevant domains.

Furthermore features may be deleted by selecting the Delete button on the palette and then selecting what to delete. To remove all domains and features, click Clear All and the canvas will be made blank.

Get AbML

Once domains and connectors are arranged, click the Get AbML button to generate the AbML descriptor string for this sequence. Once this has been generated it will appear in the input box. You may then click Get Structure again to re-render the schematic with abYdraw. Alternatively, the Tidy button performs both steps of this operation. Once rendered, an image may be altered by editing, adding or removing domains. By clicking Get AbML or Tidy, you will obtain a new expression for rendering.

6. AbML Formats Library

To assist users, the program has a library of MsAb formats available which can be scrolled through and selected. This will give the schematic and AbML expression for this format that can be used as a starting point to make new expressions and schematics that are relevant to the user.

7. Exporting and Saving

Exporting the canvas image as .eps file can be done by Export Image and using the file directory to save the image in JPEG, PNG or EPS format. Alternatively the AbML may be saved as a text file by clicking the File>Save option in the menu. Users may also export a Template File from the expression in the entry box which is a format of notating important MsAb residues. The program cannot locate these residues but it can identify the features that are in the MsAb that users may want to include in the Template Files.

8. Settings

Users may change aspects about the rendering and pairing of their schematic. By opening the File>Settings window, a menu with two tabs will appear. The first tab has settings regarding pairing sensitivity of drawn schematics, bond thickness, directional arrows, Hinge and Linker labels which can be set by using the appropriate sliders. For pairing sensitivity the scale is 0-80 pixels and bond width are between 1-5 pixels. Other binary settings are on sliders 0-1. To update the settings, users must press the update button and re-render their schematic to see their new schematic. The second tab is the colour-coding menu which with a list of domain types. When a domain type is selected the current colour of assigned to that domain will appear. Change colour allows users to assign a new colours to that domain type using the colour palette of the operating system, but these may be reverted by Revert colour or Revert all colours. Font-based settings are found in the third tab where size and colour may be changed.