ppi-network-analysis

Source: https://github.com/aipoch/medical-research-skills

PPI Network Analysis

When to Read External Files

Situation	File to Read	Purpose
Need algorithm details	references/algorithm.md	Explain local STRING mapping, interaction filtering, network metrics, and plot interpretation
Need to execute the analysis	scripts/main.R	Run the CLI entry point with a complete Rscript command
Encounter an error	references/troubleshooting.md	Map standardized error codes to causes and fixes
Need CLI examples or baseline usage	references/cli-guide.md	Review installation notes, offline cache requirements, and runnable examples
Need a runnable smoke test	tests/data/	Use the bundled small gene list for verification

Usage

Rscript scripts/main.R \
  --genelist_file ./input/gene_list.csv \
  --species human \
  --threshold 700 \
  --output_dir output/basic-run \
  --seed 42 \
  --timeout_seconds 600

Rscript scripts/main.R \
  --plot_only TRUE \
  --output_dir output/basic-run \
  --seed 42 \
  --timeout_seconds 600

Arguments

Short	Long	Type	Default	Required	Description
-g	--genelist_file	character	none	yes, unless --plot_only TRUE	Gene list file in CSV, TSV, TXT, or XLSX format
-s	--species	character	none	yes, unless --plot_only TRUE	Species: human, mouse, 9606, or 10090
-t	--threshold	integer	none	yes, unless --plot_only TRUE	STRING combined-score threshold from 400 to 1000
-o	--output_dir	character	output	no	Output directory inside the skill root
-p	--plot_only	logical	FALSE	no	Reuse output_dir/data/ppi_result.rds and regenerate the network plot
-d	--seed	integer	42	no	Random seed used for layout reproducibility
-u	--timeout_seconds	integer	600	no	Elapsed time limit in seconds
	--string_cache_dir	character	references/string_cache	no	Local STRING cache directory; if omitted, the bundled cache inside the skill is used
	--string_version	character	auto	no	Preferred STRING cache version; use auto, v11.5, or v12.0 when available
	--figure_family	character	sans	no	PDF font family: sans, serif, or mono
	--figure_width	numeric	12	no	Plot width in inches
	--figure_height	numeric	10	no	Plot height in inches
	--label	character	node	no	Label mode: node or none
	--label_size	numeric	0.8	no	Label size
	--label_color	character	black	no	Label color
	--label_dist	numeric	0	no	Label distance from the node center
	--line_alpha	numeric	1	no	Edge alpha
	--line_color	character	built-in palette	no	Comma-separated edge colors
	--line_size	numeric	0.8	no	Base edge width
	--line_type	character	solid	no	Edge line type; supported values in plotting are solid, dashed, or dotted
	--mapping_link_alpha	character	value	no	Map edge alpha from interaction score: value or none
	--mapping_link_color	character	value	no	Map edge color from interaction score: value or none
	--mapping_link_size	character	value	no	Map edge width from interaction score: value or none
	--mapping_node_alpha	character	none	no	Map node alpha from degree: value or none
	--mapping_node_color	character	none	no	Map node color from degree: value or none
	--mapping_node_size	character	value	no	Map node size from degree: value or none
	--point_alpha	numeric	1	no	Node alpha
	--point_color	character	built-in palette	no	Comma-separated node border colors
	--point_fill	character	built-in palette	no	Comma-separated node fill colors
	--point_shape	character	circle	no	Node shape: circle or square
	--point_size	numeric	12	no	Base node size
	--style_layout	character	nicely	no	Layout style: kk, fr, nicely, circle, star, grid, or randomly
	--style_line	character	straight	no	Edge style: straight or curve
	--theme_size	numeric	0.8	no	Theme size placeholder retained for compatibility
	--title	character	empty	no	Main plot title

Input Format

Supported input types

--genelist_file accepts the following formats:

• .csv
• .tsv
• .txt
• .xlsx

Gene list parsing rules

• Plain-text .txt files can be provided as one gene symbol per line without a header.
• For .csv, .tsv, and .xlsx, the tool automatically selects a likely gene column.
• Preferred column names include: gene, genes, genename, genesymbol, symbol, hgnc, hgncsymbol, mgi, ensembl, ensemblgeneid, geneid, and id.
• If no standard gene column name is found, the tool falls back to the column with the strongest non-numeric signal.
• Values may contain multiple genes separated by commas, semicolons, pipes, tabs, or spaces; these are split automatically.
• Empty inputs, unsupported file extensions, or inputs with no parsable genes will raise a SKILL_EMPTY_DATA or SKILL_INVALID_PARAMETER error.

Minimal examples

TXT example

TP53
EGFR
BRCA1
MYC

CSV example

gene
TP53
EGFR
BRCA1
MYC

Output Files

File	Format	Description
data/ppi_result.rds	RDS	Serialized PPI bundle with mappings, interactions, nodes, summary, and metadata
table/ppi_network_edges.xlsx	XLSX	Edge table with from, to, and combined_score
table/ppi_network_nodes.xlsx	XLSX	Node table with gene, degree, betweenness, and closeness
table/ppi_summary.csv	CSV	Summary metrics for input genes, mapped genes, unmapped genes, nodes, edges, and threshold
plot/ppi_network_plot.pdf	PDF	Rendered PPI network plot from the local STRING interaction graph
session_info.txt	TXT	R version, platform, and package version information

Error Handling

Error Code	Meaning	How to Fix
SKILL_FILE_NOT_FOUND	Input gene list, STRING cache directory, required cache files, or data/ppi_result.rds in plot-only mode was not found	Confirm the path exists, required cache files are present, and run a full analysis before --plot_only TRUE
SKILL_EMPTY_DATA	No valid genes were parsed, no genes mapped to STRING, fewer than two mapped STRING IDs remained, no interactions passed filtering, or the interaction table was empty for plotting	Check that the input is not empty, verify gene symbols are supported by the local STRING cache, and lower the threshold if the network is too sparse
SKILL_INVALID_PARAMETER	A required argument is missing, a numeric value is out of range, an unsupported choice was supplied, the output path is invalid, or the input extension is unsupported	Recheck the parameter value and allowed choices, especially --species, --threshold, mapping options, plot options, and output paths
SKILL_MISSING_COLUMNS	Required columns were not found in a STRING cache table	Confirm the local aliases, info, and links files are valid STRING cache files with expected columns
SKILL_PACKAGE_NOT_FOUND	Required R packages are not installed	Install the missing packages listed in the error message before rerunning

Detailed fixes and troubleshooting steps: READ references/troubleshooting.md

Testing

Smoke test with bundled data

Rscript scripts/main.R \
  --genelist_file tests/data/gene_list.csv \
  --species human \
  --threshold 700 \
  --output_dir tests/output/basic-run

Plot-only regeneration test

Rscript scripts/main.R \
  --plot_only TRUE \
  --output_dir tests/output/basic-run \
  --seed 42

Expected outputs after test

• tests/output/basic-run/data/ppi_result.rds
• tests/output/basic-run/table/ppi_network_edges.xlsx
• tests/output/basic-run/table/ppi_network_nodes.xlsx
• tests/output/basic-run/table/ppi_summary.csv
• tests/output/basic-run/plot/ppi_network_plot.pdf
• tests/output/basic-run/session_info.txt