tf-target-gene-regulatory-network

Transcription Factor (TF) Regulatory Network Analysis

When to Use

Use this skill when you have a human or mouse gene list and want to identify upstream TFs from the Dorothea database.
Use it when you need a ready-to-export TF-target network table plus a publication-ready PDF network plot.
Use it for reproducible CLI execution with saved session information and optional local Dorothea .rds databases.

When Not to Use

Do not use this skill for differential expression, pathway enrichment, cell type annotation, or survival analysis.
Do not use it to infer causal direction beyond curated Dorothea TF-target relationships.
Do not use it when your input genes are aliases or mixed-species symbols that have not been normalized first.

Input Validation

This skill accepts: a human or mouse gene list (HGNC symbols for human, first-letter-uppercase for mouse) for TF regulatory network analysis using Dorothea.

If the user's request does not involve identifying upstream transcription factors from a gene list — for example, asking to run differential expression, pathway enrichment, cell type annotation, or multi-omics integration — do not proceed with the workflow. Instead respond:

"tf-target-gene-regulatory-network is designed to identify upstream transcription factors from a gene list using the Dorothea database and generate a TF-target network visualization. Your request appears to be outside this scope. Please provide a gene list for TF regulatory analysis, or use a more appropriate tool for your task."

Entry Point

Primary CLI entry point: scripts/main.R
Canonical visualization values: English tokens fr, curve, diamond, triangle, square

When to Read External Files

Situation	File to Read	Purpose
Need algorithm details	`references/algorithm.md`	Statistical methods, Dorothea database, network analysis algorithms
Need to run analysis	`scripts/main.R`	Execute: `Rscript scripts/main.R --gene ... --species ...`
Encounter errors	`references/troubleshooting.md`	Common errors and solutions
Need CLI examples	`references/cli-guide.md`	Detailed CLI usage examples
Need test data	`tests/data/`	Sample gene lists for testing

Installation

R Package Dependencies

# CRAN packages
install.packages(c("optparse", "dplyr", "openxlsx", "tidyverse", "tidygraph", "ggraph", "showtext"))

# Bioconductor packages (optional if using local database files)
if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("dorothea")

Local Database Files (Recommended)

For faster analysis and offline use, generate local database files:

Rscript database/database-get.R

This creates database/dorothea_hs.rds (human) and database/dorothea_mm.rds (mouse) in the skill root directory.

Verification

Rscript scripts/main.R --help

Usage

Rscript scripts/main.R \
  --gene "TP53,MYC,EGFR" \
  --species human \
  --output_dir ./TF_Result \
  --seed 42

Arguments

Note: Either --gene or --gene_file must be provided (at least one is required).

Short	Long	Type	Default	Description
`-g`	`--gene`	character	NULL	Comma-separated gene list (e.g., `"TP53,MYC,EGFR"`) — required if `--gene_file` not provided
`-f`	`--gene_file`	character	NULL	File with gene names (txt or csv, one per line or comma-separated) — required if `--gene` not provided
`-s`	`--species`	character	`human`	Species: `human` or `mouse`
`-o`	`--output_dir`	character	`TF_Result`	Output directory name
	`--db_path`	character	NULL	Local `.rds` database file path. If not specified, auto-searches default paths
`-d`	`--dir`	character	NULL	Working root directory (advanced)
	`--seed`	integer	`42`	Random seed for reproducibility
	`--title`	character	`""`	Main plot title

Visualization Parameters: For complete list (plot dimensions, colors, labels, layout, edge styles), see references/visualization-parameters.md. Canonical values are English tokens: fr (force-directed layout), curve (curved edges), diamond / triangle / square (node shapes).

Input Format

Gene List Input

Two ways to provide input genes:

Command line: --gene "TP53,MYC,EGFR" (comma-separated)
File input: --gene_file genes.txt (one gene per line or comma-separated)

Gene Naming Convention

Human genes: All uppercase symbols (e.g., TP53, MYC, EGFR)
Mouse genes: First letter uppercase only (e.g., Tp53, Myc, Egfr)
Use official gene symbols, not aliases
Case-sensitive for species matching

Species Support

human: Human genes (Homo sapiens)
mouse: Mouse genes (Mus musculus)

Performance Guidance

For large gene lists (> 500 genes), Dorothea database queries may take several minutes. Use a local .rds database (--db_path) for substantially faster lookups. There is currently no --timeout_seconds parameter; monitor progress with verbose logging if available.

Output Files

File	Description
`TF_Network_Plot.pdf`	TF-target network visualization
`tf_network.xlsx`	Network data (edges and nodes worksheets)
`TF_Target_Filtered_Core_<species>.xlsx`	Complete TF-target relationships table
`session_info.txt`	R session and package version info
`tf.Rdata`	R environment data

Outputs are organized under TF_Result/ in data/, plot/, and table/ subdirectories.

Workflow

Step 1: Load Database

Priority search for local database files (.rds format) in: --db_path, getwd()/database/, script_dir/database/, dirname(script_dir)/database/
If no local file found, load from Dorothea R package
Filter for high-confidence interactions (confidence levels A, B, C)

Step 2: Identify Regulating TFs

Match input genes against target genes in Dorothea database
Extract transcription factors regulating these targets
Compute TF frequency (number of targets regulated)

Step 3: Generate Network Data

Create edge list (TF → Target relationships)
Create node list with types (TF or Target)
Save to Excel format for downstream analysis

Step 4: Visualize Network

Generate network graph using tidygraph and ggraph
Apply visual customization (layout, colors, shapes)
Save as PDF publication-ready figure

Methods

Dorothea Database

Curated database of TF-target interactions
Confidence levels: A (high), B (medium), C (low)
Includes human and mouse data
Source: https://github.com/saezlab/dorothea

Network Analysis

Graph construction: TF-target relationships as directed edges
Layout algorithms: Multiple options including fr (force-directed), circle, grid, sphere
Visual customization: Full control over colors, shapes, sizes

Local Database Feature

Option to use pre-saved .rds files for faster analysis and offline use
Priority search paths for local database files (see Step 1 above)
Fallback to Dorothea R package if no local file found

Examples

Basic Usage (Human Genes)

Rscript scripts/main.R \
  -g "TP53,MYC,EGFR" \
  -s human \
  -o ./TF_Result

File Input

Rscript scripts/main.R \
  -f gene_list.txt \
  -s human \
  -o ./TF_Result

Mouse Genes

Rscript scripts/main.R \
  -g "Tp53,Myc,Egfr" \
  -s mouse \
  -o ./Mouse_TF_Result

Custom Styling

Rscript scripts/main.R \
  -g "PTPRC,FOXP3,CD4" \
  -s human \
  --style_layout "fr" \
  --style_line "curve" \
  --point_shape "diamond,triangle" \
  --line_color "#E64B35" \
  --title "Immune TF Network" \
  -o ./Custom_Plot

Using Local Database

Rscript scripts/main.R \
  -g "TP53,MYC,EGFR" \
  -s human \
  --db_path database/dorothea_hs.rds \
  -o ./LocalDB_Result

Error Handling

Common Errors

Error Code	Cause	Solution
`SKILL_FILE_NOT_FOUND`	Input gene file does not exist	Check file path and permissions
`SKILL_NO_INPUT_GENES`	Empty gene list or file	Provide genes using `--gene` or `--gene_file`
`SKILL_INVALID_SPECIES`	Species not `human` or `mouse`	Use `human` or `mouse` only
`SKILL_INVALID_PARAMETER`	Invalid layout, shape, line, or legend value	Use supported values shown by `Rscript scripts/main.R --help`
`SKILL_EMPTY_RESULTS`	No TF-target relationships found for input genes	Check gene symbols and species; try broadening confidence levels
`SKILL_DEPENDENCY_MISSING`	Missing dplyr, dorothea, tidygraph, etc.	Install missing packages (see Installation section)

Exit Status Codes

Code	Meaning
`0`	Success
`1`	Execution error (see error code for details)
`2`	`SKILL_EMPTY_RESULTS` — no TF-target matches found for the input genes

IF error persists, READ: references/troubleshooting.md

Testing

Test with Sample Data

# Check help
Rscript scripts/main.R --help

# Run with sample human genes
Rscript scripts/main.R \
  -g "TP53,MYC,EGFR" \
  -s human \
  -o tests/output_human/

# Run with sample mouse genes
Rscript scripts/main.R \
  -g "Tp53,Myc,Egfr" \
  -s mouse \
  -o tests/output_mouse/

After running, verify tests/output_human/plot/TF_Network_Plot.pdf and tests/output_human/table/tf_network.xlsx exist and are non-empty.

Reference Files

File	Purpose
`references/algorithm.md`	Statistical methods and Dorothea database details
`references/troubleshooting.md`	Common errors and solutions
`references/cli-guide.md`	CLI usage examples
`references/visualization-parameters.md`	Complete visualization parameter list