Proteinspy

A CLI tool and Python library for analysing protein structure files.

Supports .cif, .mmcif, .pdb, .ent, and their .gz compressed variants. Full documentation: akhilteja2209.github.io/Proteinspy

Installation

pip install proteinspy

Windows note

If proteinspy is not recognised after installation, add the Python Scripts folder to your PATH. Run this once in PowerShell:

$scriptsPath = python -c "import sysconfig; print(sysconfig.get_path('scripts', 'nt_user'))"
$env:PATH += ";$scriptsPath"
[System.Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")

Then restart PowerShell and run proteinspy again.

Quick start

# See all commands with
proteinspy
# Or
proteinspy --help

# Run all basic analyses on a structure file
proteinspy analyze my_protein.cif

# Works with PDB format too
proteinspy analyze my_protein.pdb

Commands

Format: proteinspy <command> <file> [--output table|json|csv|tsv]

Basic analyses

Advanced analyses

Examples

# Basic analyses
proteinspy analyze    my_protein.cif
proteinspy resolution my_protein.cif
proteinspy chains     my_protein.cif
proteinspy ligands    my_protein.cif
proteinspy missing    my_protein.cif

# Advanced analyses
proteinspy bfactor   my_protein.cif
proteinspy disulfide my_protein.cif
proteinspy interface my_protein.cif --cutoff 8.0
proteinspy validate  my_protein.cif

# Output formats — any command supports --output / -o
proteinspy chains    my_protein.cif --output json
proteinspy bfactor   my_protein.cif --output csv
proteinspy analyze   my_protein.cif -o tsv

# Export to file (format inferred from extension)
proteinspy export my_protein.cif report.json
proteinspy export my_protein.cif chains.csv  --analysis chains
proteinspy export my_protein.cif bonds.json  --analysis disulfide

Output formats

Every command accepts --output (or -o):

Supported file formats

Python API

You can import and use every analysis function directly:

from proteinspy import get_resolution, get_chains, get_bfactor_stats
from proteinspy import to_json, write_output

# Basic
result = get_resolution("my_protein.cif")
print(result["resolution"], result["method"])

# Advanced
stats = get_bfactor_stats("my_protein.cif")
print(stats["overall"]["mean"])

# Export
write_output(get_chains("my_protein.cif"), "json", output_path="chains.json")

Check out API Reference for the list of all the functions.

Requirements

• pip installed on device
• Python 3.10 or later
• Dependencies installed automatically: gemmi, rich, click

Contributing

Contributions are welcome — new analyses, output formats, bug fixes, or docs. See CONTRIBUTING.md for setup instructions, code standards, and how to add a new analysis command.

Documentation

Full Installation and usage guides at akhilteja2209.github.io/Proteinspy

Version: 1.1.5