pICkIT

Automated analysis of protein–ligand interactions

pICkIT is an open-source Python library for the extraction, filtering, and analysis of protein–ligand interaction data from large structural datasets. It was built to process the interaction files generated by tools such as Arpeggio, whose raw output is often too large and complex for manual inspection.

pICkIT parses these files into a compact, structured interaction matrix and provides a modular API for filtering, summarizing, comparing, and visualizing interaction patterns across hundreds or thousands of protein–ligand complexes — turning hundreds of megabytes of raw JSON into a few kilobytes of publication-ready data, in seconds.

Table of contents

• What does pICkIT do?
• Workflow
• Installation
• Quick start
• Core concepts
• API overview
• Example: analyzing SARS-CoV-2 Mpro inhibitors
• Repository contents
• Citing pICkIT
• Authors
• Funding
• License

What does pICkIT do?

• Parses large Arpeggio JSON interaction files into a single, compact interaction matrix
• Filters interactions by type, residue, subunit/chain, or binding-site subpocket
• Integrates ligand activity data (e.g. IC50 / pIC50) to relate interactions to potency
• Generates compact summary matrices, exportable to Excel (.xlsx)
• Produces publication-ready heatmaps, bar charts, and pie charts
• Supports dataset comparison across ligand series and binding subpockets

Workflow

PDB Search & Quality Filtering  ─▶  Arpeggio Interaction Profiling (JSON)
        │
        ▼
Curation & Annotation (IC50 → pIC50, binding-site/subpocket definitions)
        │
        ▼
pICkIT: parsing → filtering → interaction matrix
        │
        ▼
Output & Visualization: summary tables, heatmaps, bar charts, pie charts

In its validation study, pICkIT processed 378 SARS-CoV-2 Mpro complexes, reducing 365 MB of raw Arpeggio output to a 109 KB summary matrix (a 99.98% reduction) in seconds — see POSTER-pICkIT.pdf for the full case study and example figures.

Installation

Prerequisites: Python 3.12+

From PyPI (stable release)

pip install pickit-urv

From TestPyPI (pre-release / testing versions)

pip install -i https://test.pypi.org/simple/ pickit

Note: the package is published under different names on each index — pickit-urv on PyPI and pickit on TestPyPI — but both install the same pickit module, so imports (from pickit.analyze_interactions import AnalyzeInteractions) work identically either way.

From source

git clone https://github.com/31ldts/pICkIT.git
cd pICkIT
pip install .

Or install the dependencies directly if you'd rather import the module as-is:

pip install pandas numpy matplotlib seaborn mplcursors openpyxl

Dependencies: pandas, numpy, matplotlib, seaborn, mplcursors, openpyxl.

Quick start

from pickit.analyze_interactions import AnalyzeInteractions

analyzer = AnalyzeInteractions()

# Point pICkIT to your input/output directories
analyzer.change_directory("input", mode=analyzer.INPUT)
analyzer.change_directory("output", mode=analyzer.OUTPUT)

# Parse a directory of Arpeggio JSON files, annotated with ligand activity
data = analyzer.analyze_files(
    directory="my_complexes",
    mode=analyzer.ARPEGGIO,
    activity_file="activities.csv",
    save="interaction_matrix.xlsx",
)

# Inspect the interaction types found
print(analyzer.get_interactions(data))

# Visualize
analyzer.heatmap(interaction_data=data, title="Interaction counts", mode=analyzer.COUNT)
analyzer.pie_chart(interaction_data=data, plot_name="interaction_types", axis=analyzer.ROWS)

Note: analyze_files restricts interactions to the bundled template.json by default. This default template lives inside the installed package itself (src/pickit/template.json). If you pass your own template_file=, that path is resolved relative to the input directory you set with change_directory(path, mode=analyzer.INPUT) — just like activity_file and subpocket_path.

A full walkthrough of every method, with runnable examples and sample input/output files, is available in pICkIT-notebook.ipynb (also runnable directly in Colab).

Core concepts

• AnalyzeInteractions — the main entry point. Holds configuration (I/O directories, interaction labels, plot colors, heatmap settings) and exposes all parsing, filtering, and plotting methods.
• InteractionData — the object returned by most methods. Wraps the interaction matrix plus metadata (interaction labels, colors, protein/ligand/subunit flags, processing mode). Most pICkIT methods take an InteractionData object in and return a new one out, so calls can be chained.
• Interaction matrix — a 2D matrix with residues on one axis and ligands/complexes on the other; each cell encodes the interaction type(s) present between them (and, optionally, the specific atoms and subunit involved).

API overview

Method	Purpose
change_directory(path, mode)	Set the input or output working directory
set_config(...)	Configure interaction labels, plot/heatmap colors, and column limits
analyze_files(directory, mode, ...)	Parse a directory of Arpeggio (or IChem) interaction files into an InteractionData matrix, optionally annotated with activity data
filter_by_interaction(interaction_data, interactions)	Keep only the specified interaction types
filter_by_residue(interaction_data, chain=..., subpocket_path=..., subpockets=...)	Filter by main/side chain atoms or by binding-site subpocket
filter_by_subunit(interaction_data, subunits)	Filter by protein subunit
sort_matrix(interaction_data, thr_interactions=..., thr_activity=..., selected_items=...)	Sort and select rows/columns by interaction count, activity threshold, or top-N
remove_empty_axis(interaction_data)	Drop empty rows/columns
transpose_matrix(interaction_data)	Swap rows and columns
get_dataframe(interaction_data)	Convert the matrix to a pandas DataFrame
get_interactions(interaction_data)	List the interaction types present in the matrix
heatmap(interaction_data, title, mode, ...)	Plot a heatmap (min, max, mean, count, or percent mode), optionally colored by subpocket
bar_chart(interaction_data, plot_name, ...)	Plot a (stacked) bar chart of interaction counts per residue/complex
pie_chart(interaction_data, plot_name, axis, ...)	Plot the distribution of interaction types
save_interaction_data(interaction_data, filename)	Export the matrix and its metadata to a formatted .xlsx file

Every public method is fully documented with docstrings (arguments, return values, and exceptions raised). The implementation is split across src/pickit/ (see Repository contents above for the breakdown by module) — browse the generated API reference (mkdocs serve) or the notebook for details. The stable import path, from pickit.analyze_interactions import AnalyzeInteractions, is unaffected by this internal split.

Example: analyzing SARS-CoV-2 Mpro inhibitors

pICkIT was validated on 378 protein–ligand complexes of SARS-CoV-2 main protease (Mpro), producing:

• Interaction frequency heatmaps — counts of residue–interaction occurrences across the dataset
• Mean activity heatmaps — average pIC50 of complexes exhibiting each residue–interaction pair
• Residue interaction profiles — stacked bar charts of the most active residues and their predominant interaction types
• Subpocket-level breakdowns — identifying which S1', S1, S2, and S4 binding subsites each inhibitor occupies

See main.py for a complete real-world analysis script covering these use cases, and the poster for the resulting figures.

Repository contents

.
├── src/pickit/                     # Core library (modularized, see below)
│   ├── analyzer.py                     # AnalyzeInteractions: composes all mixins below
│   ├── analyze_interactions.py         # Backward-compatibility shim (re-exports everything
│   │                                    # under the same names/import path as before)
│   ├── models.py                       # InteractionData
│   ├── constants.py                    # Global constants (interaction labels, colors, delimiters...)
│   ├── exceptions.py                   # Custom exceptions
│   ├── _validation.py                  # ValidationMixin: shared input-validation helpers
│   ├── filter_mixin.py                 # FilterMixin: filter/sort/reshape the interaction matrix
│   ├── export_mixin.py                 # ExportMixin: DataFrame / Excel export
│   ├── plot_mixin.py                   # PlotMixin: heatmap / bar_chart / pie_chart
│   ├── io_mixin.py                     # IOMixin: directory/config management, analyze_files
│   ├── parsers/                        # File-format parsers used by analyze_files
│   │   ├── arpeggio.py                     # Arpeggio parser (plain + template-restricted)
│   │   ├── ichem.py                        # IChem parser
│   │   └── common.py                       # Helpers shared by both parsers
│   └── template.json                   # Default interaction template bundled with the package
├── tests/                          # Test suite (pytest), one file per module above
├── docs/                           # mkdocs + mkdocstrings API reference (`mkdocs serve` to browse)
├── notebook-materials/             # Sample input/output files used by the notebook
├── pICkIT-notebook.ipynb           # Interactive tutorial covering the full API (runnable in Colab)
├── main.py                         # Example analysis script (SARS-CoV-2 Mpro inhibitor dataset)
├── POSTER-pICkIT.pdf               # Conference poster describing the tool and its validation study
├── LICENSE.txt                     # License file
└── README.md                       # This file

AnalyzeInteractions is composed from five mixins (ValidationMixin, FilterMixin, ExportMixin, PlotMixin, IOMixin), each covering one concern — see docs/ for the full breakdown and the reasoning behind it.

Citing pICkIT

If you use pICkIT in your research, please cite the accompanying poster/publication (details to be added upon publication) and link back to this repository.

Authors

Developed by the Cheminformatics & Nutrition research group, Universitat Rovira i Virgili (Tarragona, Spain):

• Said Trujillo-De Leon — 31ldts@gmail.com
• Ariadna Llop-Peiro — ariadna.llop@urv.cat
• Gerard Pujadas — gerard.pujadas@gmail.com
• Santiago Garcia-Vallvé — santi.garcia-vallve@urv.cat
• Aleix Gimeno — aleix.gimeno@urv.cat

Funding

This work was supported by project PID2022-138327OB-I00 (MCIN/AEI/10.13039/501100011033/FEDER, UE) and project PDI2020-117646RB-I00 (MICIU/AEI/10.13039/501100011033).

License

Distributed under the GNU Affero General Public License v3.0 (AGPL-3.0).