/bulkrna-ppi-network

name: bulkrna-ppi-network
description: Load when querying STRING for the protein-protein interaction neighborhood of a bulk
  RNA-seq DEG list and finding hub genes. Skip when pathway enrichment of the same list (use bulkrna-enrichment);
  de novo co-expression network discovery (use bulkrna-coexpression).
trigger: PPI, protein interaction, STRING, network, hub gene, interactome
tags:
- bulkrna
- PPI
- STRING
- network
- hub-genes
- protein-interaction

bulkrna-ppi-network

When to use

Analyze a PPI subgraph and rank hub genes from explicit interaction tables. Use bulkrna-coexpression for expression-derived networks and bulkrna-enrichment for pathways.

Use from a step

import pandas as pd
from skills._sdk.notebook import load_skill, read_input, write_output
library = load_skill('bulkrna-ppi-network')
data = read_input('edges.csv', reader=pd.read_csv)
result = library.analyze(data)
write_output(result, 'tables/result.csv')

[examples/example_step.py](examples/example_step.py) runs offline and supports fresh-kernel replay. Pure computations return objects; CLI and steps own writes.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

`analyze(data, *, genes=None, induced=False)`

Rank query nodes using the CLI's unweighted neighborhood convention.

:param data: Interaction DataFrame with gene_a, gene_b and score columns; scores do not weight centrality. :param genes: Optional gene list including isolates; None uses all edge endpoints. :param induced: Default False preserves external neighbors in degree/closeness; True restricts edges to genes. :returns: A node-centrality DataFrame with degree, betweenness, closeness and hub_score. :raises ValueError: Edge columns or the node list are invalid.

`fetch_interactions(data, *, species=9606, score_threshold=400)`

Query STRING explicitly; unavailable or malformed responses raise.

:param data: Gene identifiers sent to the public STRING service. :param species: CLI default 9606 (human); NCBI taxonomy identifier. :param score_threshold: CLI default 400; integer confidence cutoff from 0 to 1000. :returns: A DataFrame with gene_a, gene_b and scores on STRING's 0 to 1 scale. :raises ImportError: Install requests with install_skill_deps if unavailable. :raises ValueError: Parameters or response columns are invalid. :raises Exception: Network and HTTP failures propagate without demo fallback.

`run_info(data, *, keep=True)`

Read topology diagnostics attached to the node table.

:param data: Centrality DataFrame returned by analyze. :param keep: Default True; the CLI removes diagnostics with False. :returns: An independent summary dictionary. :raises TypeError: data is not a DataFrame.

`network_figure(data, *, genes=None, random_state=42)`

Draw a seeded spring layout without changing numpy's global random state.

:param data: Edge DataFrame accepted by analyze. :param genes: Optional gene list including isolates; None uses edge endpoints. :param random_state: CLI default 42; spring-layout initialization seed. :returns: A matplotlib Figure. :raises ValueError: Edges or node list are invalid.

`hubs_figure(data, *, top_n=20)`

Plot the highest-ranked hub scores.

:param data: Centrality table returned by analyze. :param top_n: CLI default 20; maximum number of nodes shown. :returns: A matplotlib Figure. :raises KeyError: gene or hub_score is absent.

<!-- api:end -->

Methods and parameters

fetch_interactions explicitly queries STRING with a 0 to 1000 confidence threshold and returns 0 to 1 scores. analyze uses an unweighted graph and includes provided isolates. Hub scores combine normalized degree and betweenness. The CLI demo reads the fixed 364-edge STRING table described in data/README.md; it does not contact STRING.

Gotchas

• `--demo` accepts only species 9606 because `data/demo_string_edges.csv` contains human interactions; other species require a real query.
• `fetch_interactions` propagates HTTP/network errors and never substitutes demo edges. `analyze` defaults to the CLI neighborhood convention: degree includes external neighbors, closeness visits them, and betweenness is restricted to query nodes. Use induced=True to restrict all edges to the query set. `network_figure` draws query nodes only and uses seed 42 without changing the global random generator.

Inputs and outputs

`tables/hub_genes.csv`, `tables/interaction_edges.csv`, `tables/node_centrality.csv`, `figures/hub_genes_barplot.png`, `figures/ppi_network.png`, `report.md`, `result.json` and `reproducibility/commands.sh`.

CLI

python skills/bulkrna/bulkrna-ppi-network/bulkrna_ppi_network.py --demo --output /tmp/bulkrna_ppi_network

See also

• [Parameters](references/parameters.md)
• [Methodology](references/methodology.md)
• [Output contract](references/output_contract.md)

Dependencies

`numpy`, `pandas`, `matplotlib`, `requests`