Structure-first inference for protein teams

Interpretable allostery signals from protein structure, delivered as reproducible analysis artifacts

RINet converts a protein structure into a residue interaction network and runs deterministic graph dynamics to generate residue-indexed coupling profiles. It is designed for practical use in exploratory workflows where teams need fast, auditable signals that can be compared across variants and exported in a report-friendly format.

Desktop workflow with report export CLI for pipelines and sweeps Deterministic execution and metadata Forward, scan, inverse, mediators

Designed for review

RINet emphasizes outputs that survive scrutiny: explicit graph assumptions, explicit operators, deterministic runs, and exports that preserve the context required to interpret and reproduce results. The goal is not a one-off plot, but a durable artifact your team can cite and revisit.

Fast enough to iterate

The model is intentionally lightweight compared to full simulation. That makes it suitable for parameter sensitivity analysis, comparative profiling across mutants, and early-stage hypothesis prioritization before expensive downstream work.

RINet is an interpretable, structure-first coupling profiler. It does not attempt to reproduce full atomistic dynamics. Instead, it provides deterministic approximations that are fast enough for iteration and explicit enough to be compared across variants.

RINet CLI + Python API — pip installation

Naming note: rinet is the PyPI package name and CLI command, while allograph is the internal Python module used for imports.

For batch runs, parameter sweeps, and integration into pipelines, install the RINet command line interface and Python API with pip. This path works on macOS, Linux, and Windows. After installation, the command-line interface is available as rinet. The Python API can be accessed via import allograph. The desktop GUI is distributed separately as a macOS application.

# macOS / Linux
python3 -m venv rinet-env
source rinet-env/bin/activate

python -m pip install -U pip
python -m pip install rinet

rinet --help

# Windows (PowerShell)
py -m venv rinet-env
.\rinet-env\Scripts\Activate.ps1

python -m pip install -U pip
python -m pip install rinet

rinet --help

If you are in an offline or restricted environment, install from a wheel file instead of PyPI. Download a .whl release and install it with python -m pip install rinet-*.whl. The commands are the same after installation.

Install details CLI usage

Capabilities

RINet is built around residue-indexed outputs that are easy to compare across proteins and variants. The core capability is forward propagation: given a seed residue or region, the tool produces a coupling profile indicating where influence concentrates under an explicit contact graph and operator. On top of that, the toolkit includes scan inference to identify globally influential residues, inverse attribution to propose plausible upstream sources for a downstream effect, and mediator discovery to highlight residues that behave as bridge-like conduits in influence routes.

The desktop application organizes these modes into a single workflow: ingest a structure, configure graph construction parameters, run inference, inspect the resulting residue profiles in plots and tables, and export a report folder. The report folder is designed to preserve the context needed to interpret and reproduce results without relying on screenshots or informal notes.

Data handling and deployment posture

RINet is designed so core inference can be performed locally without transmitting structure files to external services. This is important for teams working with unpublished structures or proprietary variants. The intended deployment model is straightforward: install the desktop application for interactive work, install the CLI for pipeline integration, and store structure files and exported reports in controlled storage.

If collaboration or cloud-backed features are added, they will be explicit and opt-in. RINet’s default posture is local execution and export artifacts that remain meaningful outside an interactive session.

Documentation

RINet Documentation

RINet is designed for structure-first coupling analysis with deterministic execution and export artifacts that support review. This documentation focuses on installation, practical usage, and the meaning of the exported outputs.

Overview

RINet represents a protein structure as a residue interaction network. Each residue is a node. Structural contacts become edges under an explicit contact rule. A perturbation is represented as an initial residue-indexed state. The state evolves under a deterministic operator derived from the graph, producing a coupling profile that can be plotted, compared, and exported.

RINet is not a substitute for molecular dynamics. It is a structured approximation that provides fast, interpretable signals suitable for comparative profiling across variants and for prioritizing downstream experiments or deeper simulation.

Python package (CLI + API)

The pip install pathway is recommended for batch workflows, compute environments, and cross-platform installs. After installation, the Python API is available via import allograph, and the command-line interface is available as rinet. The desktop GUI is distributed separately as a macOS application.

# macOS / Linux
python3 -m venv rinet-env
source rinet-env/bin/activate

python -m pip install -U pip
python -m pip install rinet

rinet --help

# Windows (PowerShell)
py -m venv rinet-env
.\rinet-env\Scripts\Activate.ps1

python -m pip install -U pip
python -m pip install rinet

rinet --help

If you are installing from a wheel file (offline installs or internal distribution), install it directly and then run the same commands:

# Install from a downloaded wheel file
python -m pip install rinet-0.1.0-py3-none-any.whl

rinet --help

Command line usage

The CLI is designed for reproducible runs and batch processing. It emits explicit CSV outputs that can be versioned, diffed, and incorporated into downstream pipelines. A typical workflow is: build a contact graph under an explicit rule, run an inference mode, and export a residue-indexed result vector alongside the parameters used to generate it.

# Forward propagation (seed a residue; produce coupling profile)
rinet forward --pdb path/to/structure.pdb --seed 45 --cutoff 8.0 --out rinet_forward.csv

# Scan inference (seed each residue; produce global influence score)
rinet scan --pdb path/to/structure.pdb --cutoff 8.0 --out rinet_scan.csv

# Inverse inference (propose likely upstream sources)
rinet inverse --pdb path/to/structure.pdb --cutoff 8.0 --out rinet_inverse.csv

Tip: when comparing variants, keep graph construction parameters (contact mode, cutoff, chain selection, weight rule) fixed across runs so results are comparable. Changes to these parameters change the underlying graph and can dominate the profile.

Quickstart workflow

A standard analysis run consists of four steps. First, load a structure file and confirm residues are parsed with stable identifiers. Second, configure graph construction: contact mode, distance cutoff, chain selection, and weight mode. Third, run an inference mode, typically forward propagation from a seed residue or region, then optionally scan, inverse attribution, or mediator discovery depending on the question. Fourth, export a report folder that contains the result vector, plot image, and run metadata capturing the settings used to generate the result.

The exported folder is meant to be shareable: it contains the values and the context needed to interpret them without relying on screenshots or informal notes.

Graph construction

Graph construction is the central modeling assumption. In Cα mode, residues are connected when Cα distance is below a cutoff. In heavy-atom mode, a contact can be defined by the existence of any heavy atom pair across residues within the cutoff. Heavy-atom graphs tend to be denser and emphasize packing; Cα graphs tend to be simpler and often better for coarse comparative workflows. Weighting can be binary or distance-based; any weight rule used should be kept fixed when comparing runs.

Propagation model

The default operator is diffusion-like dynamics on a graph Laplacian. Let x be a residue-indexed state and let L be the Laplacian derived from the adjacency. A common update is x_{t+1} = x_t + dt · (−L x_t). The step size and number of steps affect localization and smoothing. Because graph density varies across proteins, parameter sweeps under controlled conditions are recommended when drawing conclusions.

Inference suite

Forward propagation produces a coupling profile for a specified seed residue or region. Scan inference runs forward propagation across candidate seeds and aggregates influence-as-seed into a global score. Inverse attribution proposes plausible upstream sources for a downstream effect under an explicit inverse model. Mediator discovery highlights residues that behave like bridge-like conduits in influence routes.

Reports and outputs

RINet exports residue-indexed vectors to CSV and can render the same values as a profile plot for rapid review. A complete export includes metadata that records structure identifiers and run parameters. This is what makes results portable: a collaborator can interpret what was run and compare outputs across variants under a consistent construction.

Data handling

RINet is designed so core inference can run locally without uploading structures to external services. This supports teams working with proprietary or unpublished structures. If collaboration or cloud-backed features are added, they will be explicit and opt-in, with documented data transmission paths.

Troubleshooting

If the macOS app will not open, check your macOS security prompt and ensure the DMG was fully downloaded. If the CLI command is not found after pip installation, ensure that your virtual environment is activated and that python -m pip refers to the same Python installation used to run rinet. If a run produces a flat profile, confirm your graph construction settings generate a nontrivial contact graph and that the seed residue index is valid for the structure.