plip

plip packages the Protein-Ligand Interaction Profiler (PLIP) 3.0.1 for TAFFISH.

Package identity:

• name: plip
• command: taf-plip
• kind: tool
• version: 3.0.1-r1
• native platforms: linux/amd64, linux/arm64
• license: Apache-2.0 for the TAFFISH app packaging
• upstream license: GPL-2.0-only
• upstream: https://github.com/pharmai/plip

What This App Packages

PLIP detects and characterizes non-covalent interactions in PDB structures. It can analyze conventional protein-ligand complexes, peptide and intrachain contacts, and the chain- or region-based protein-protein interactions added in PLIP 3.

This image builds the official PLIP v3.0.1 source and exposes both the plip command-line interface and upstream Python API. It also builds Open Babel 3.2.1 with its complete plugin set and Python bindings, and includes headless PyMOL 3.1 plus ImageMagick 7 for upstream PSE and PNG visualization paths.

Scope

This app supports:

• local PDB files, standard input, or PDB-ID retrieval from RCSB;
• TXT and XML reports, optional gzip compression, and report output on standard output;
• protein-ligand interactions, peptide/protein contacts, intrachain contacts, and protein-protein interactions selected by chains or residue regions;
• PSE session and PNG image generation through headless PyMOL;
• scripts using the upstream plip Python package;
• automatic TAFFISH command mode for packaged helper commands such as python3, obabel, pymol, and magick.

This app does not:

• provide the PLIP web server or a browser-based graphical interface;
• bundle a PDB archive or interaction database;
• guarantee that an arbitrary structure, biological assembly, protonation state, alternate location, or interaction threshold is scientifically appropriate for a particular study.

Container Contents

• plip: PLIP 3.0.1 command-line entry point.
• python3: Python runtime with the PLIP API, NumPy, lxml, Open Babel bindings, and PyMOL module.
• obabel: Open Babel 3.2.1 command-line entry point and full runtime plugins.
• pymol: PyMOL 3.1 command-line runtime used by PLIP visualization.
• magick: ImageMagick 7 command used to validate, crop, and pad PNG output.
• /opt/plip/share/doc/plip: upstream README, manual, changelog, and package metadata.
• /opt/plip/share/provenance: exact source identity, package manifests, and the retained downstream visualization patch.
• /opt/plip/share/source and /opt/openbabel/share/source: checksum-pinned compressed source archives retained for reproducibility and GPL source availability.

Usage

Show this app's terminal help or the upstream PLIP help:

taf-plip --help
taf-plip -- --help

Analyze a local complex and write XML and TXT reports:

taf-plip -- -f complex.pdb -o plip-results -x -t --maxthreads 4

Name the report files explicitly and avoid writing the fixed PDB copy:

taf-plip -- -f complex.pdb -o plip-results -x -t \
  --name sample01 --nofixfile

Generate a PyMOL session and a rendered PNG as well as reports:

taf-plip -- -f complex.pdb -o plip-results -x -t -y -p

Read a PDB structure from standard input and print a TXT report:

cat complex.pdb | taf-plip -- -f - -O -t --nohydro

Download and analyze a PDB ID from RCSB; this is the only normal PLIP input path that requires network access:

taf-plip -- -i 1vsn -o plip-1vsn -x -t

Analyze contacts between chain groups or between residue regions:

taf-plip -- -f complex.pdb -o chain-contacts -t \
  --chains '[[A], [B, C]]'

taf-plip -- -f complex.pdb -o region-contacts -t \
  --regions '({A: 1-99}, {B: 1-99})'

Analyze a peptide chain or contacts within one chain:

taf-plip -- -f complex.pdb -o peptide-contacts -t --peptides I
taf-plip -- -f complex.pdb -o intrachain-contacts -t --intra A

Use the upstream Python API:

taf-plip python3 analyze.py

Example analyze.py:

from plip.structure.preparation import PDBComplex

mol = PDBComplex()
mol.load_pdb("complex.pdb")
mol.analyze()
for site, interactions in mol.interaction_sets.items():
    print(site, sorted(interactions.interacting_res))

Command Mode

The default command is plip. Use taf-plip -- -f ... for the clearest way to pass option-leading PLIP arguments through the TAFFISH wrapper, or use the explicit equivalent taf-plip plip -f ....

TAFFISH reserves wrapper-level -v and --version. Upstream PLIP uses -v for verbose logging and does not have a dedicated version option, so invoke upstream verbosity as taf-plip -- -v -f complex.pdb .... The first paragraph of upstream help reports the PLIP runtime version:

taf-plip -- --help

Automatic command mode also supports commands such as:

taf-plip obabel -V
taf-plip pymol -cq script.pml
taf-plip magick -version

Those helpers are included to support PLIP and reproducible inspection. The dedicated TAFFISH Open Babel app remains the preferred package for general chemical conversion workflows.

Inputs

Input	Meaning	Notes
PDB file	Local macromolecular structure	Use -f FILE; .pdb.gz is accepted by upstream input handling.
Standard input	PDB content from a pipe	Use -f -; combine with -O to print reports.
Four-character PDB ID	Structure downloaded from RCSB	Use -i PDBID; requires network access at run time.
Chain specification	Protein-protein chain groups	--chains '[[A], [B, C]]'.
Region specification	Protein-protein residue groups	--regions '({A: 1-20}, {B: 17-46})'.

PLIP relies on PDB ATOM and HETATM semantics when identifying conventional receptors and ligands. Peptide ligands encoded as ATOM records should be selected explicitly with --peptides or another protein-interaction mode.

Output Notes

Without --name, a local file such as complex.pdb normally produces complex_report.xml and/or complex_report.txt under -o OUTDIR. --name sample01 instead produces sample01.xml and sample01.txt; batch inputs add a numeric suffix where needed. -z compresses TXT/XML reports with gzip, and -O prints requested reports to standard output.

Unless --nofixfile is used, PLIP can also write its fixed/prepared PDB file. Visualization creates one .pse session and, with -p, one square .png per analyzed interaction site. Exact visualization filenames encode the structure, ligand or interaction site, chain, and residue position.

TXT and XML reports contain the interaction types and geometry reported by upstream PLIP, including applicable hydrophobic contacts, hydrogen bonds, water bridges, salt bridges, pi stacking, pi-cation interactions, halogen bonds, and metal complexes.

Resources, Databases, and Platform

Local files, standard input, report generation, the Python API, and bundled visualization run offline. No external database, model, account, GPU, service port, or environment activation is required. -i PDBID deliberately accesses RCSB and is therefore excluded from offline smoke testing.

The image has native linux/amd64 and linux/arm64 builds. --maxthreads controls PLIP's parallel visualization work; structure parsing and interaction analysis are often modest, while many structures, large assemblies, PyMOL ray rendering, and PNG generation require more CPU, memory, and disk.

The final runtime includes PyMOL, its graphics/runtime libraries, ImageMagick, and the complete Open Babel plugin set because they are real upstream PLIP capabilities. Compilers, headers, static libraries, package-manager caches, and Python build tooling are removed from the final image.

Boundaries

PLIP 3.0.1 constructs several ImageMagick operations as command strings but invokes them without a shell. Upstream can consequently log a hidden FileNotFoundError after PLIP itself exits successfully. This image applies a small retained patch that passes safe argument arrays to ImageMagick, checks subprocess failures, and preserves the intended crop and square-padding behavior. It does not modify PLIP interaction detection or thresholds.

PLIP may add hydrogens and repair structures unless options such as --nohydro, --nofix, or --nofixfile are selected. These options change preparation or output behavior and should be chosen for scientific reasons, not merely to silence diagnostics. Consult the upstream manual for alternate locations, models, composite ligands, DNA/RNA receptor handling, and threshold settings.

Troubleshooting

• If an option is interpreted by the TAFFISH wrapper, place -- before PLIP arguments, for example taf-plip -- -f complex.pdb -x.
• If no ligand is detected, inspect ATOM/HETATM records, ligand chain and residue identity, biological assembly, model selection, and whether peptide, intrachain, chain, or region mode is appropriate.
• If -i fails while local files work, verify container network access and the PDB ID; local analysis does not need that network path.
• If visualization is expensive, omit -y and -p, reduce --maxthreads, or generate reports first and visualize only selected complexes.

Testing

Independent offline smoke tests cover:

• exact PLIP 3.0.1 and Open Babel 3.2.1 identities, source checksums, licenses, Python imports, PyMOL, and ImageMagick;
• upstream help and protein-ligand, protein-protein chain, and residue-region interfaces;
• real TXT/XML reports from upstream structures;
• standard-input and standard-output reporting;
• a real Python API analysis;
• headless PSE and PNG generation, hidden subprocess-error rejection, PNG signature validation, and final square dimensions;
• dynamic-library completeness for the source-built Open Babel runtime.

Smoke does not contact RCSB, benchmark scientific accuracy, or replace review of production structures and thresholds.

License and Citation

The TAFFISH app repository and wrapper metadata are Apache-2.0. PLIP and Open Babel are distributed under GPL-2.0-only. Their original notices and exact corresponding source archives are retained in the image; Debian runtime packages keep their own license terms.

Please cite PLIP according to upstream guidance:

Schake P, Bolz SN, Linnemann K, Schroeder M. PLIP 2025: introducing protein-protein interactions to the protein-ligand interaction profiler. Nucleic Acids Research. 2025;53(W1):W463-W465. https://doi.org/10.1093/nar/gkaf361

Upstream documentation: https://github.com/pharmai/plip/blob/v3.0.1/DOCUMENTATION.md