Agent Skills
› aipoch/medical-research-skills
› ppi-network-analysis
ppi-network-analysis
GitHub提供基于本地STRING缓存的R语言PPI网络分析工作流，支持基因列表输入、交互过滤、节点边表导出及可复现PDF绘图，适用于离线生物医学研究。
Trigger Scenarios
需要构建蛋白质相互作用网络
使用本地数据生成网络可视化图
Install
npx skills add aipoch/medical-research-skills --skill ppi-network-analysis -g -y
SKILL.md
Frontmatter
{
"name": "ppi-network-analysis",
"author": "AIPOCH",
"license": "MIT",
"description": "Use when you need a standardized R CLI workflow to build a protein-protein interaction network from a local gene list and an offline STRING cache, export node and edge tables, and render a reproducible PDF network plot. NOT for online API fetching, arbitrary graph databases, multi-omics integration, or non-STRING interaction sources."
}
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
.txtfiles 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, andid. - 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_DATAorSKILL_INVALID_PARAMETERerror.
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 |
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.rdstests/output/basic-run/table/ppi_network_edges.xlsxtests/output/basic-run/table/ppi_network_nodes.xlsxtests/output/basic-run/table/ppi_summary.csvtests/output/basic-run/plot/ppi_network_plot.pdftests/output/basic-run/session_info.txt
Version History
- f5ef65b Current 2026-07-24 17:04
