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.
Installation
RINet is available as a macOS desktop installer for interactive workflows and as a Python package for the command line interface and Python API. Many teams use both: the desktop app for exploration and report export, and the CLI for batch runs and reproducible sweeps.
macOS Desktop (DMG)
Download the DMG from the product page. Open it and drag RINet.app into Applications. On first launch, macOS may show a
security prompt depending on system settings.
Python package (CLI + API)
The pip install pathway is recommended for batch workflows, compute environments, and cross-platform installs. After installation, the CLI is available
as rinet. If your distribution includes the GUI launcher, it can be started with rinet-gui.
# 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 --helpIf 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 --helpCommand 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.csvTip: 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, confirm the environment is activated and run python -m pip -V to verify pip is pointing to the expected
environment. 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.