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

ppi-network-analysis

PPI Network Analysis

When to Read External Files

Usage

Arguments

Input Format

Supported input types

Gene list parsing rules

Minimal examples

TXT example

CSV example

Output Files

Error Handling

Testing

Smoke test with bundled data

Plot-only regeneration test

Expected outputs after test

Is this your skill?