Assembly interfaces analysis

Basic information

This python package works with PISA to analyze data for macromolecular interfaces and interactions in assemblies.

The code consists of the module pisa_analysis that will:

• Analyse macromolecular interfaces with PISA
• Create a JSON dictionary with assembly interactions/interfaces information

git clone https://github.com/PDBe-KB/pisa-analysis

cd pisa-analysis

Dependencies

The pisa_analysis process runs PISA as a subprocess and requires apriori compilation of PISA.

To make your life easier when running the process, you can set two path environment variables for PISA:

An environment variable to the pisa binary:

export PATH="$PATH:your_path_to_pisa/pisa/build"

A path to the setup directory of PISA:

export PISA_SETUP_DIR="/your_path_to_pisa/pisa/setup"

Additionally, it is required that PISA setup directory contains a pisa configuration template named pisa_cfg_tmp

Usage

Follow below steps to install the module pisa_analysis and required dependencies:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt

To run the modules in command line:

pisa_analysis:

pisa_analysis [-h] \
  -i <INPUT_CIF_FILE> \
  --pdb_id <PDB_ID> \
  --assembly_id <ASSEMBLY_CODE> \
  -o <OUTPUT_JSON> \
  --output_xml <OUTPUT_XML>

Required arguments are :

--input_cif (-i)          :  Assembly CIF file (It can also read a PDB file). Optional if --gen_full_results is used and --assembly_id not specified.
--pdb_id                  :  Entry ID
--assembly_id             :  Assembly code
--output_json (-o)        :  Output directory for JSON fille
--output_xml              :  Output directory for XML files

Other optional arguments are:

--input_updated_cif       : Updated cif for pdbid entry
--force                   : Always runs PISA calculation
--pisa_setup_dir          : Path to the 'setup' directory in PISA
--pisa_binary             : Binary file for PISA
-h, --help                : Show help message

The process is as follows:

For pisa_analysis module:

1. The process first runs PISA in a subprocess and generates two xml files:

   • interfaces.xml
   • assembly.xml

   The xml files are saved in the output directory defined by the --output_xml argument. If the xml files exist and are valid, the process will skip running PISA unless the --force is used in the arguments.

2. Next, the process parses xml files generated by PISA and creates a dictionary that contains all assembly interfaces/interactions information.

3. While creating the interfaces dictionary for the entry, the process reads UniProt accession and sequence numbers from an Updated CIF file using Gemmi.

4. The process also parses xml file assembly.xml generated by PISA and creates a simplified dictionary with some assembly information.

5. In the last steps, the process dumps the dictionaries into JSON files. The JSON files are saved in the output directory defined by the -o or --output_json arguments. The output json files are:

   xxxx-assemX_interfaces.json and xxxx-assemblyX.json

   where xxxx is the pdb id entry and X is the assembly code.

Expected JSON files

Documentation on the assembly interfaces json file and schema can be found here:

https://pisalite.docs.apiary.io/#reference/0/pisaqualifierjson/interaction-interface-data-per-pdb-assembly-entry

The simplified assembly json output looks as follows:

{
   "PISA": {
      "pdb_id": "1d2s",
      "assembly_id": "1",
      "pisa_version": "2.0",
      "assembly": {
         "id": "1",
         "size": "8",
         "macromolecular_size": "2",
         "dissociation_energy": -3.96,
         "accessible_surface_area": 15146.45,
         "buried_surface_area": 3156.79,
         "entropy": 12.09,
         "dissociation_area": 733.07,
         "solvation_energy_gain": -41.09,
         "number_of_uc": "0",
         "number_of_dissociated_elements": "2",
         "symmetry_number": "2",
         "formula": "A(2)a(4)b(2)",
         "composition": "A-2A[CA](4)[DHT](2)"
      }
   }
}

Run with Docker

docker run -v <HOST_DIR>:/data_dir \
   pdbegroup/pisa-analysis \
   pisa_analysis \
   --input_cif /data_dir/<INPUT_CIF> \
   --pdb_id <PDB_ID> \
   --assembly_id <ASSEMBLY_CODE> \
   --output_json /data_dir/<OUTPUT_JSON> \
   --output_xml /data_dir/<OUTPUT_XML>

Development

The library supports Python 3.10 and later. The full development environment requires Python 3.11 or later because pre-commit's transitive filelock dependency requires it.

We use Astral's uv tool for setting up the project and managing dependencies:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv python pin 3.11
uv sync
source .venv/bin/activate

We also use pre-commit checks to ensure that requirements.txt and requirements-dev.txt are up to date and, also, to lint the code with Ruff.

pre-commit install
pre-commit run --all-files

To run the tests on Python 3.10 without installing the full development tooling:

uv run --python 3.10 --no-dev --group test make test

or defaulting to Python 3.11:

make test

You can also build the Docker image locally and then run it as described above:

docker build . -t pdbegroup/pisa-analysis

Error codes

• Exit Status 9: File not found

Versioning

We use SemVer for versioning.

Authors

• Grisell Diaz Leines - Lead developer
• Stephen Anyango - Review and productionising
• Mihaly Varadi - Review and management

See all contributors here.

License

See LICENSE