1---2name: ppi-network-analysis3description: 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.4license: MIT5---6> **Source**: [https://github.com/aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills)
7
8# PPI Network Analysis
9
10## When to Read External Files
11
12| Situation | File to Read | Purpose |
13|-----------|--------------|---------|
14| Need algorithm details | `references/algorithm.md` | Explain local STRING mapping, interaction filtering, network metrics, and plot interpretation |
15| Need to execute the analysis | `scripts/main.R` | Run the CLI entry point with a complete `Rscript` command |
16| Encounter an error | `references/troubleshooting.md` | Map standardized error codes to causes and fixes |
17| Need CLI examples or baseline usage | `references/cli-guide.md` | Review installation notes, offline cache requirements, and runnable examples |
18| Need a runnable smoke test | `tests/data/` | Use the bundled small gene list for verification |
19
20## Usage
21
22```bash
23Rscript scripts/main.R \
24 --genelist_file ./input/gene_list.csv \
25 --species human \
26 --threshold 700 \
27 --output_dir output/basic-run \
28 --seed 42 \
29 --timeout_seconds 600
30```
31
32```bash
33Rscript scripts/main.R \
34 --plot_only TRUE \
35 --output_dir output/basic-run \
36 --seed 42 \
37 --timeout_seconds 600
38```
39
40## Arguments
41
42| Short | Long | Type | Default | Required | Description |
43|-------|------|------|---------|----------|-------------|
44| `-g` | `--genelist_file` | character | none | yes, unless `--plot_only TRUE` | Gene list file in CSV, TSV, TXT, or XLSX format |
45| `-s` | `--species` | character | none | yes, unless `--plot_only TRUE` | Species: `human`, `mouse`, `9606`, or `10090` |
46| `-t` | `--threshold` | integer | none | yes, unless `--plot_only TRUE` | STRING combined-score threshold from `400` to `1000` |
47| `-o` | `--output_dir` | character | `output` | no | Output directory inside the skill root |
48| `-p` | `--plot_only` | logical | `FALSE` | no | Reuse `output_dir/data/ppi_result.rds` and regenerate the network plot |
49| `-d` | `--seed` | integer | `42` | no | Random seed used for layout reproducibility |
50| `-u` | `--timeout_seconds` | integer | `600` | no | Elapsed time limit in seconds |
51| | `--string_cache_dir` | character | `references/string_cache` | no | Local STRING cache directory; if omitted, the bundled cache inside the skill is used |
52| | `--string_version` | character | `auto` | no | Preferred STRING cache version; use `auto`, `v11.5`, or `v12.0` when available |
53| | `--figure_family` | character | `sans` | no | PDF font family: `sans`, `serif`, or `mono` |
54| | `--figure_width` | numeric | `12` | no | Plot width in inches |
55| | `--figure_height` | numeric | `10` | no | Plot height in inches |
56| | `--label` | character | `node` | no | Label mode: `node` or `none` |
57| | `--label_size` | numeric | `0.8` | no | Label size |
58| | `--label_color` | character | `black` | no | Label color |
59| | `--label_dist` | numeric | `0` | no | Label distance from the node center |
60| | `--line_alpha` | numeric | `1` | no | Edge alpha |
61| | `--line_color` | character | built-in palette | no | Comma-separated edge colors |
62| | `--line_size` | numeric | `0.8` | no | Base edge width |
63| | `--line_type` | character | `solid` | no | Edge line type; supported values in plotting are `solid`, `dashed`, or `dotted` |
64| | `--mapping_link_alpha` | character | `value` | no | Map edge alpha from interaction score: `value` or `none` |
65| | `--mapping_link_color` | character | `value` | no | Map edge color from interaction score: `value` or `none` |
66| | `--mapping_link_size` | character | `value` | no | Map edge width from interaction score: `value` or `none` |
67| | `--mapping_node_alpha` | character | `none` | no | Map node alpha from degree: `value` or `none` |
68| | `--mapping_node_color` | character | `none` | no | Map node color from degree: `value` or `none` |
69| | `--mapping_node_size` | character | `value` | no | Map node size from degree: `value` or `none` |
70| | `--point_alpha` | numeric | `1` | no | Node alpha |
71| | `--point_color` | character | built-in palette | no | Comma-separated node border colors |
72| | `--point_fill` | character | built-in palette | no | Comma-separated node fill colors |
73| | `--point_shape` | character | `circle` | no | Node shape: `circle` or `square` |
74| | `--point_size` | numeric | `12` | no | Base node size |
75| | `--style_layout` | character | `nicely` | no | Layout style: `kk`, `fr`, `nicely`, `circle`, `star`, `grid`, or `randomly` |
76| | `--style_line` | character | `straight` | no | Edge style: `straight` or `curve` |
77| | `--theme_size` | numeric | `0.8` | no | Theme size placeholder retained for compatibility |
78| | `--title` | character | empty | no | Main plot title |
79
80## Input Format
81
82### Supported input types
83
84`--genelist_file` accepts the following formats:
85- `.csv`
86- `.tsv`
87- `.txt`
88- `.xlsx`
89
90### Gene list parsing rules
91
92- Plain-text `.txt` files can be provided as one gene symbol per line without a header.
93- For `.csv`, `.tsv`, and `.xlsx`, the tool automatically selects a likely gene column.
94- Preferred column names include: `gene`, `genes`, `genename`, `genesymbol`, `symbol`, `hgnc`, `hgncsymbol`, `mgi`, `ensembl`, `ensemblgeneid`, `geneid`, and `id`.
95- If no standard gene column name is found, the tool falls back to the column with the strongest non-numeric signal.
96- Values may contain multiple genes separated by commas, semicolons, pipes, tabs, or spaces; these are split automatically.
97- Empty inputs, unsupported file extensions, or inputs with no parsable genes will raise a `SKILL_EMPTY_DATA` or `SKILL_INVALID_PARAMETER` error.
98
99### Minimal examples
100
101#### TXT example
102
103```text
104TP53
105EGFR
106BRCA1
107MYC
108```
109
110#### CSV example
111
112```csv
113gene
114TP53
115EGFR
116BRCA1
117MYC
118```
119
120## Output Files
121
122| File | Format | Description |
123|------|--------|-------------|
124| `data/ppi_result.rds` | RDS | Serialized PPI bundle with mappings, interactions, nodes, summary, and metadata |
125| `table/ppi_network_edges.xlsx` | XLSX | Edge table with `from`, `to`, and `combined_score` |
126| `table/ppi_network_nodes.xlsx` | XLSX | Node table with `gene`, `degree`, `betweenness`, and `closeness` |
127| `table/ppi_summary.csv` | CSV | Summary metrics for input genes, mapped genes, unmapped genes, nodes, edges, and threshold |
128| `plot/ppi_network_plot.pdf` | PDF | Rendered PPI network plot from the local STRING interaction graph |
129| `session_info.txt` | TXT | R version, platform, and package version information |
130
131## Error Handling
132
133| Error Code | Meaning | How to Fix |
134|-----------|---------|------------|
135| `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` |
136| `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 |
137| `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 |
138| `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 |
139| `SKILL_PACKAGE_NOT_FOUND` | Required R packages are not installed | Install the missing packages listed in the error message before rerunning |
140
141Detailed fixes and troubleshooting steps: READ `references/troubleshooting.md`
142
143## Testing
144
145### Smoke test with bundled data
146
147```bash
148Rscript scripts/main.R \
149 --genelist_file tests/data/gene_list.csv \
150 --species human \
151 --threshold 700 \
152 --output_dir tests/output/basic-run
153```
154
155### Plot-only regeneration test
156
157```bash
158Rscript scripts/main.R \
159 --plot_only TRUE \
160 --output_dir tests/output/basic-run \
161 --seed 42
162```
163
164### Expected outputs after test
165
166- `tests/output/basic-run/data/ppi_result.rds`
167- `tests/output/basic-run/table/ppi_network_edges.xlsx`
168- `tests/output/basic-run/table/ppi_network_nodes.xlsx`
169- `tests/output/basic-run/table/ppi_summary.csv`
170- `tests/output/basic-run/plot/ppi_network_plot.pdf`
171- `tests/output/basic-run/session_info.txt`
gabrielmoreira