GenePerturbR_docs.json

{
  "gpdb_analyze_cascade": {
    "package": "GenePerturbR",
    "function_name": "gpdb_analyze_cascade",
    "title": "Trace Multi-Step Regulatory Cascades from Starting Gene",
    "description": "Identifies multi-layer regulatory networks by iteratively expanding from a starting gene through successive regulatory relationships. Discovers indirect regulation pathways (e.g., A->B->C) by querying GenePerturbR database at each depth level. **Database covers 2,810 genes across 7,665 experiments** with confidence-scored multi-dataset evidence (high: 5+ datasets, 80 %+ consistency) supporting cascade discovery.",
    "user_queries": ["How do I trace multi-step regulatory pathways from a starting gene?", "What genes are indirectly regulated by TP53 through intermediate factors?", "Can I discover regulatory cascades beyond direct targets?", "How do I find genes that regulate my target through multiple steps?", "What is the regulatory network downstream of MYC?", "How deep should I set max_depth for cascade analysis?", "What is the difference between forward, backward, and both directions?", "How do I visualize the cascade network I discovered?", "Can I export cascade results to Cytoscape or other network tools?", "Why does my cascade stop at depth 1 or 2?", "How do I filter cascade results to keep only strong regulatory relationships?", "What genes are in the secondary layer of TP53 regulation?", "Can I compare regulatory cascades between different genes?", "How long does cascade analysis take for depth 3 vs depth 5?", "What tissue or cell types are represented in my cascade results?", "How reliable are indirect regulatory relationships (depth 2+)?", "Can I trace cascades specific to cancer cell lines?", "How do I interpret the effect sizes in multi-step cascades?", "What happens if I set min_confidence to \"high\" in cascade analysis?", "How many genes are typically discovered at each cascade depth?"],
    "usage": "gpdb_analyze_cascade( start_gene, max_depth = 3, min_effect_size = 1, min_confidence = \"medium\", direction = c(\"forward\", \"backward\", \"both\") )",
    "parameters": [
      {
        "name": "start_gene",
        "has_default": false,
        "description": "Character. Gene symbol to start cascade analysis (e.g., \"TP53\", \"MYC\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended."
      },
      {
        "name": "max_depth",
        "has_default": true,
        "default_value": "3",
        "description": "Integer. Maximum cascade depth to explore (1-5, default: 3). Higher depths discover longer regulatory chains but increase computation time exponentially. Depth 3 typically captures direct and secondary effects."
      },
      {
        "name": "min_effect_size",
        "has_default": true,
        "default_value": "1",
        "description": "Numeric. Minimum |logFC| threshold for each regulatory step (default: 1.0). Higher values (1.5-2.0) focus on strong effects; lower values (0.5-1.0) include moderate regulatory relationships."
      },
      {
        "name": "min_confidence",
        "has_default": true,
        "default_value": "\"medium\"",
        "description": "Character. Evidence strength filter for each step (\"high\", \"medium\", \"low\"). Default: \"medium\" . Options: \"high\" (5+ datasets, most reliable), \"medium\" (2-4 datasets, balanced), \"low\" (1 dataset, exploratory)."
      },
      {
        "name": "direction",
        "has_default": true,
        "default_value": "c(\"forward\", \"backward\", \"both\")",
        "description": "Character. Cascade expansion strategy: \"forward\" (downstream targets), \"backward\" (upstream regulators), or \"both\" (bidirectional network). Default: \"forward\" . \"both\" provides comprehensive networks but increases computation time significantly."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Forward Cascade (TESTED - runtime: 0.03 sec)\n# ===========================================================================\n# Scientific Question: What are the multi-step downstream effects of TP53?\n# Query: TP53 forward cascade (depth=2)\n# Expected output: Direct and secondary targets with effect sizes\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Trace TP53 downstream targets through 2 regulatory layers\ncascade <- gpdb_analyze_cascade(\n  start_gene = \"TP53\",\n  max_depth = 2,\n  min_confidence = \"high\",\n  direction = \"forward\"\n)\n\n# Verify output structure\nstr(cascade, max.level = 1)\ncat(\"Cascade statistics:\\n\")\ncat(\"  Total edges:\", cascade$n_paths, \"\\n\")\ncat(\"  Unique genes:\", cascade$n_genes, \"\\n\")\ncat(\"  Depth distribution:\\n\")\nprint(table(cascade$paths$depth))\n\n# Examine direct targets (depth 1)\ndirect_targets <- cascade$paths[cascade$paths$depth == 1, ]\ncat(\"\\nDirect targets (depth 1):\\n\")\nprint(head(direct_targets))\n\n# Examine secondary targets (depth 2)\nsecondary_targets <- cascade$paths[cascade$paths$depth == 2, ]\ncat(\"\\nSecondary targets (depth 2):\\n\")\nprint(head(secondary_targets))\n\n# ===========================================================================\n# Example 2: Bidirectional Cascade Network (TESTED - runtime: 5.33 sec)\n# ===========================================================================\n# Compare how direction parameter affects network discovery\n\n# Forward only: downstream targets\ncascade_forward <- gpdb_analyze_cascade(\n  start_gene = \"TP53\",\n  max_depth = 3,\n  min_confidence = \"medium\",\n  direction = \"forward\"\n)\n\n# Both directions: comprehensive network\ncascade_both <- gpdb_analyze_cascade(\n  start_gene = \"TP53\",\n  max_depth = 3,\n  min_confidence = \"medium\",\n  direction = \"both\"\n)\n\n# Compare network sizes\ncat(\n  \"Forward only:\", cascade_forward$n_paths, \"edges,\",\n  cascade_forward$n_genes, \"genes\\n\"\n)\ncat(\n  \"Both directions:\", cascade_both$n_paths, \"edges,\",\n  cascade_both$n_genes, \"genes\\n\"\n)\n\n# Direction distribution in bidirectional network\ncat(\"\\nDirection distribution:\\n\")\nprint(table(cascade_both$paths$direction))\n\n# ===========================================================================\n# Example 3: Parameter Impact on Cascade Depth\n# ===========================================================================\n# Show how min_effect_size affects cascade expansion\n\n# Strict filter: strong effects only\ncascade_strict <- gpdb_analyze_cascade(\n  start_gene = \"MYC\",\n  max_depth = 3,\n  min_effect_size = 1.5, # Strong effects only\n  min_confidence = \"medium\"\n)\n\n# Relaxed filter: include moderate effects\ncascade_relaxed <- gpdb_analyze_cascade(\n  start_gene = \"MYC\",\n  max_depth = 3,\n  min_effect_size = 0.5, # Moderate to strong effects\n  min_confidence = \"medium\"\n)\n\n# Compare cascade penetration\ncat(\"Strict (effect > 1.5):\\n\")\nprint(table(cascade_strict$paths$depth))\ncat(\"\\nRelaxed (effect > 0.5):\\n\")\nprint(table(cascade_relaxed$paths$depth))\n\n# Effect size distribution\ncat(\n  \"\\nEffect size range (strict):\",\n  round(range(abs(cascade_strict$paths$effect)), 2), \"\\n\"\n)\ncat(\n  \"Effect size range (relaxed):\",\n  round(range(abs(cascade_relaxed$paths$effect)), 2), \"\\n\"\n)\n\n# ===========================================================================\n# Example 4: Visualize and Export Cascade\n# ===========================================================================\n# Demonstrate downstream analysis and export\n\n# Run cascade analysis\ncascade <- gpdb_analyze_cascade(\n  start_gene = \"TP53\",\n  max_depth = 2,\n  min_confidence = \"high\",\n  direction = \"both\"\n)\n\n# Visualize cascade network (requires ggraph package)\nif (requireNamespace(\"ggraph\", quietly = TRUE)) {\n  plot <- gpdb_plot_cascade(cascade)\n  print(plot)\n}\n\n# Extract all unique genes in cascade\nall_cascade_genes <- unique(c(cascade$paths$from, cascade$paths$to))\ncat(\"Cascade contains\", length(all_cascade_genes), \"unique genes\\n\")\n\n# Perform pathway enrichment on cascade genes\n# enrichment <- gpdb_enrich(all_cascade_genes, enrich.type = \"GO\")\n\n# Export for Cytoscape or other network tools\n# write.csv(cascade$paths, \"tp53_cascade_edges.csv\", row.names = FALSE)\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# For complete workflows, see:\n# - Visualize cascade: ?gpdb_plot_cascade (network graph with ggraph)\n# - Enrichment analysis: ?gpdb_enrich (GO/KEGG pathways for cascade genes)\n# - Compare genes: ?gpdb_compare_genes (compare cascades of multiple genes)\n# - Load raw data: ?gpdb_load_data (expression data for cascade genes)\n# - Direct targets only: ?gpdb_find_targets (faster alternative, no cascade)\n## End(No test)\n\n\n",
    "return_value": "List containing cascade analysis results: **Return Structure**: start_gene Starting gene symbol (Character) max_depth Maximum depth explored (Integer) n_paths Total regulatory edges discovered (Integer) paths Data.frame of all regulatory relationships with columns: from : Source gene in relationship to : Target gene in relationship depth : Cascade layer (1 = direct, 2+ = indirect) effect : Average log2 fold change across datasets direction : Expansion type (\"forward\" or \"backward\") n_genes Unique genes in cascade network (Integer) **Programmatic Access**: Get direct relationships: result$paths[result$paths$depth == 1, ] Filter strong effects: result$paths[abs(result$paths$effect) > 2, ] Count genes per depth: table(result$paths$depth) Extract edge list for network tools: result$paths[, c(\"from\", \"to\")] **What You Can Do Next**: Visualize cascade network: gpdb_plot_cascade (result) Enrich pathway analysis: gpdb_enrich (unique(c(result$paths$from, result$paths$to))) Compare with direct targets: gpdb_find_targets (start_gene) Load raw data for key genes: gpdb_load_data (dataset_id) Export network for Cytoscape: write.csv(result$paths, \"cascade_edges.csv\") **Alternative Methods**: gpdb_find_targets : Use when only direct downstream targets needed (faster, depth=1) gpdb_find_regulators : Use when only upstream regulators needed (faster, depth=1) gpdb_what_happens : Use when comprehensive single-gene query needed (no cascade) gpdb_compare_genes : Use when comparing cascades of multiple genes side-by-side",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "start_gene: Character. Gene symbol to start cascade analysis (e.g., \"TP53\", \"MYC\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended.\nmax_depth: Integer. Maximum cascade depth to explore (1-5, default: 3). Higher depths discover longer regulatory chains but increase computation time exponentially. Depth 3 typically captures direct and secondary effects.\nmin_effect_size: Numeric. Minimum |logFC| threshold for each regulatory step (default: 1.0). Higher values (1.5-2.0) focus on strong effects; lower values (0.5-1.0) include moderate regulatory relationships.\nmin_confidence: Character. Evidence strength filter for each step (\"high\", \"medium\", \"low\"). Default: \"medium\" . Options: \"high\" (5+ datasets, most reliable), \"medium\" (2-4 datasets, balanced), \"low\" (1 dataset, exploratory).\ndirection: Character. Cascade expansion strategy: \"forward\" (downstream targets), \"backward\" (upstream regulators), or \"both\" (bidirectional network). Default: \"forward\" . \"both\" provides comprehensive networks but increases computation time significantly.",
    "simple_arguments": "start_gene: Character. Gene symbol to start cascade analysis (e.g., \"TP53\", \"MYC\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended."
  },
  "gpdb_compare_contexts": {
    "package": "GenePerturbR",
    "function_name": "gpdb_compare_contexts",
    "title": "Compare Gene Perturbation Effects Across Biological Contexts",
    "description": "Identify tissue-specific and context-shared regulatory targets by comparing gene perturbation effects across different tissues, cell lines, or experimental conditions. **Database covers 2,810 genes across 1,063 cell lines and 71 tissue types**, enabling discovery of context-dependent gene functions, tissue-specific drug targets, and conserved regulatory mechanisms across biological systems.",
    "user_queries": ["How do I compare TP53 effects in liver vs lung?", "Which targets are tissue-specific vs conserved across tissues?", "Can I compare gene effects across different cell lines?", "How to identify liver-specific regulatory targets for drug development?", "What does high context-specificity tell me biologically?", "How many tissues can I compare simultaneously?", "Can I compare primary tissues vs cancer cell lines?", "How to interpret genes affected only in one tissue?", "What if one context has very few datasets?", "How to validate context-specific targets experimentally?", "Can I use this for species comparison (human vs mouse)?", "How to identify housekeeping vs tissue-specific functions?", "What contexts are available in the database?", "How to compare stem cells vs differentiated cells?", "Can I filter by experimental method (CRISPR vs shRNA)?", "How to find biomarkers specific to disease tissues?", "What causes low overlap between contexts?", "How to visualize context comparison results?", "Can I nest comparisons (tissue within organ system)?", "How to use results for precision medicine applications?"],
    "usage": "gpdb_compare_contexts(gene, contexts, metric = \"specificity\")",
    "parameters": [
      {
        "name": "gene",
        "has_default": false,
        "description": "Character. Gene symbol to query (e.g., \"TP53\", \"MYC\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended."
      },
      {
        "name": "contexts",
        "has_default": false,
        "description": "Named list. Context specifications for comparison. Each element should be a named list containing context filters: tissue : Tissue type (e.g., \"Liver\", \"Lung\", \"Brain\") cell_line : Specific cell line (e.g., \"HepG2\", \"A549\") Example: list(liver = list(tissue = \"Liver\"), lung = list(tissue = \"Lung\")) Minimum 2 contexts required for meaningful comparison."
      },
      {
        "name": "metric",
        "has_default": true,
        "default_value": "\"specificity\"",
        "description": "Character. Comparison metric (default: \"specificity\"). Currently only \"specificity\" is implemented, which calculates context-specific and shared targets. Future versions may support correlation-based metrics."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage - Tissue Comparison (TESTED - runtime: 0.104 sec)\n# ===========================================================================\n# Scientific Question: Does TP53 regulate different genes in liver vs lung?\n# Query: TP53 effects in Liver and Lung tissues\n# Expected output: Common and tissue-specific targets\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\nresult <- gpdb_compare_contexts(\n  \"TP53\",\n  contexts = list(\n    liver = list(tissue = \"Liver\"),\n    lung = list(tissue = \"Lung\")\n  )\n)\n\n# Verify output structure\nstr(result, max.level = 1)\ncat(\"Common targets:\", length(result$common_targets), \"\\n\")\ncat(\"Liver-specific:\", length(result$specific_targets$liver), \"\\n\")\ncat(\"Lung-specific:\", length(result$specific_targets$lung), \"\\n\")\n\n# Preview common targets (conserved across tissues)\ncat(\"\\nTop 10 common targets:\\n\")\nprint(head(result$common_targets, 10))\n\n# Preview liver-specific targets\ncat(\"\\nTop 10 liver-specific targets:\\n\")\nprint(head(result$specific_targets$liver, 10))\n\n# ===========================================================================\n# Example 2: Multiple Context Comparison (3+ tissues)\n# ===========================================================================\n# Compare MYC effects across three tissue types\n\nresult_multi <- gpdb_compare_contexts(\n  \"MYC\",\n  contexts = list(\n    liver = list(tissue = \"Liver\"),\n    lung = list(tissue = \"Lung\"),\n    brain = list(tissue = \"Brain\")\n  )\n)\n\n# Summary statistics\ncat(\"MYC context comparison:\\n\")\ncat(\"Common targets (all 3):\", length(result_multi$common_targets), \"\\n\")\nfor (ctx_name in names(result_multi$specific_targets)) {\n  n_specific <- length(result_multi$specific_targets[[ctx_name]])\n  n_total <- nrow(result_multi$all_effects[[ctx_name]])\n  pct <- round(n_specific / n_total * 100, 1)\n  cat(sprintf(\n    \"%s-specific: %d (%s%% of total)\\n\",\n    ctx_name, n_specific, pct\n  ))\n}\n\n# ===========================================================================\n# Example 3: Enrichment of Context-Specific Targets\n# ===========================================================================\n# Identify pathways specific to liver vs lung for TP53\n\nresult_tp53 <- gpdb_compare_contexts(\n  \"TP53\",\n  contexts = list(\n    liver = list(tissue = \"Liver\"),\n    lung = list(tissue = \"Lung\")\n  )\n)\n\n# Enrichment analysis of liver-specific targets\n# (Requires gpdb_enrich or external enrichment tool)\n# liver_enrich <- gpdb_enrich(result_tp53$specific_targets$liver, enrich.type = \"GO\")\n\n# Compare effect sizes for common targets\ncommon <- result_tp53$common_targets\nliver_effects <- result_tp53$all_effects$liver\nlung_effects <- result_tp53$all_effects$lung\n\n# Extract common target effects\nliver_common <- liver_effects[liver_effects$target_gene %in% common, ]\nlung_common <- lung_effects[lung_effects$target_gene %in% common, ]\n\ncat(\"\\nCommon targets - average effect sizes:\\n\")\ncat(\"Liver:\", mean(abs(liver_common$logfc_mean)), \"\\n\")\ncat(\"Lung:\", mean(abs(lung_common$logfc_mean)), \"\\n\")\n\n# ===========================================================================\n# Example 4: Cell Line Comparison\n# ===========================================================================\n# Compare same gene across different cancer cell lines\n\nresult_cell_lines <- gpdb_compare_contexts(\n  \"METTL3\",\n  contexts = list(\n    hepg2 = list(cell_line = \"HepG2\"),\n    k562 = list(cell_line = \"K-562\")\n  )\n)\n\ncat(\"METTL3 in HepG2 vs K-562:\\n\")\ncat(\"Common:\", length(result_cell_lines$common_targets), \"\\n\")\ncat(\"HepG2-specific:\", length(result_cell_lines$specific_targets$hepg2), \"\\n\")\ncat(\"K-562-specific:\", length(result_cell_lines$specific_targets$k562), \"\\n\")\n\n# Calculate overlap percentage\nhepg2_total <- nrow(result_cell_lines$all_effects$hepg2)\nk562_total <- nrow(result_cell_lines$all_effects$k562)\ncommon_count <- length(result_cell_lines$common_targets)\n\ncat(\"\\nOverlap rates:\\n\")\ncat(\"HepG2 overlap:\", round(common_count / hepg2_total * 100, 1), \"%\\n\")\ncat(\"K-562 overlap:\", round(common_count / k562_total * 100, 1), \"%\\n\")\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# For complete workflows, see:\n# - Enrichment of context-specific targets: ?gpdb_enrich\n# - Visualize overlap: Venn diagram or UpSet plot\n# - Load context-specific raw data: ?gpdb_load_data\n# - Compare multiple genes: ?gpdb_compare_genes\n## End(No test)\n\n\n\n",
    "return_value": "List object with context comparison results containing 5 elements: **Return Structure**: gene Character. Query gene symbol (standardized format) contexts Character vector. Names of compared contexts (from input) common_targets Character vector. Genes affected in ALL contexts, representing conserved regulatory mechanisms independent of tissue/cell type. These are core targets of the perturbed gene. specific_targets Named list. For each context, genes affected ONLY in that context (not in others). Identifies tissue-specific or context-dependent regulatory relationships. Useful for finding tissue-specific drug targets or understanding context-dependent gene functions. all_effects Named list of data.frames. Complete perturbation effects for each context, with columns: perturbed_gene : Query gene target_gene : Affected gene logfc_mean : Average log2 fold change n_datasets : Number of supporting experiments in this context confidence : Evidence strength (high/medium/low) **Programmatic Access Examples**: Get common targets: result$common_targets Get liver-specific: result$specific_targets$liver Context-specific count: length(result$specific_targets$liver) Total targets per context: nrow(result$all_effects$liver) Overlap percentage: length(common) / length(all_targets) * 100 **What You Can Do Next**: Enrichment of common targets: gpdb_enrich (result$common_targets, enrich.type = \"GO\") Enrichment of context-specific: gpdb_enrich (result$specific_targets$liver) Visualize overlap: Create Venn diagram or UpSet plot with context-specific targets Compare effect sizes: Merge data.frames in result$all_effects by target_gene Load raw data: gpdb_list_datasets (gene, context = list(tissue = \"Liver\")) **Alternative Methods**: gpdb_compare_genes : Use when comparing DIFFERENT genes in same context (multiple genes, one condition) vs compare_contexts (one gene, multiple conditions). gpdb_what_happens : Use with context parameter for single-context analysis before comparison. compare_contexts internally calls what_happens for each context. Manual comparison: Call gpdb_what_happens () separately for each context and perform custom comparisons if you need more control over filtering or analysis.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "gene: Character. Gene symbol to query (e.g., \"TP53\", \"MYC\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended.\ncontexts: Named list. Context specifications for comparison. Each element should be a named list containing context filters: tissue : Tissue type (e.g., \"Liver\", \"Lung\", \"Brain\") cell_line : Specific cell line (e.g., \"HepG2\", \"A549\") Example: list(liver = list(tissue = \"Liver\"), lung = list(tissue = \"Lung\")) Minimum 2 contexts required for meaningful comparison.\nmetric: Character. Comparison metric (default: \"specificity\"). Currently only \"specificity\" is implemented, which calculates context-specific and shared targets. Future versions may support correlation-based metrics.",
    "simple_arguments": "gene: Character. Gene symbol to query (e.g., \"TP53\", \"MYC\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended.\ncontexts: Named list. Context specifications for comparison. Each element should be a named list containing context filters: tissue : Tissue type (e.g., \"Liver\", \"Lung\", \"Brain\") cell_line : Specific cell line (e.g., \"HepG2\", \"A549\") Example: list(liver = list(tissue = \"Liver\"), lung = list(tissue = \"Lung\")) Minimum 2 contexts required for meaningful comparison."
  },
  "gpdb_compare_genes": {
    "package": "GenePerturbR",
    "function_name": "gpdb_compare_genes",
    "title": "Compare Gene Perturbation Effects Across Multiple Genes",
    "description": "Identify common and unique regulatory targets across multiple gene perturbations, aggregated from 7,665 RNA-seq datasets for comparative pathway analysis and functional similarity assessment. **Database covers 2,810 genes across 1,063 cell lines** with fast multi-gene comparison using optimized SQL queries (IN clause).",
    "user_queries": ["How do I compare regulatory targets between TP53 and RB1?", "Which genes are commonly regulated by METTL3 and METTL14?", "What targets are unique to MYC vs other oncogenes?", "How similar are the effects of paralogous genes?", "Can I compare more than 2 genes at once?", "How do I find pathways shared by multiple gene knockouts?", "What does high overlap in targets tell me biologically?", "Why does one gene have many more unique targets than others?", "How to filter comparison results by confidence level?", "Can I compare genes from the same pathway or complex?", "How to visualize gene comparison results as Venn diagram?", "What if one of my genes returns no data?", "How to identify convergent regulatory pathways?", "Can I compare genes across different species?", "How to validate common targets experimentally?", "What does asymmetric overlap indicate functionally?", "How many genes can I compare simultaneously?", "How to merge effect sizes for common targets?", "Why do related genes have low overlap sometimes?", "How to use comparison results for drug target selection?"],
    "usage": "gpdb_compare_genes( genes, metric = c(\"overlap\", \"correlation\", \"difference\"), context = NULL )",
    "parameters": [
      {
        "name": "genes",
        "has_default": false,
        "description": "Character vector. Gene symbols to compare (e.g., c(\"TP53\", \"RB1\"), c(\"METTL3\", \"METTL14\", \"WTAP\")). Minimum 2 genes required. All genes are case-insensitive and automatically formatted to standard symbols."
      },
      {
        "name": "metric",
        "has_default": true,
        "default_value": "c(\"overlap\", \"correlation\", \"difference\")",
        "description": "Character. Comparison metric: \"overlap\" (default, target overlap analysis), \"correlation\" (not yet implemented), \"difference\" (not yet implemented). Currently only \"overlap\" is fully supported for identifying common/unique targets."
      },
      {
        "name": "context",
        "has_default": true,
        "default_value": "NULL",
        "description": "List. Optional filters to restrict analysis to specific biological contexts. Not currently used but reserved for future tissue/cell line-specific comparisons."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Compare Tumor Suppressors (TESTED - runtime: 0.054 sec)\n# ===========================================================================\n# Scientific Question: Do TP53 and RB1 regulate similar pathways?\n# Expected output: High overlap due to shared cell cycle regulation\n\nlibrary(GenePerturbR)\n\nresult <- gpdb_compare_genes(c(\"TP53\", \"RB1\"))\n\n# Verify output structure\nstr(result, max.level = 1)\ncat(\"Common targets:\", result$n_common, \"\\n\")\ncat(\"TP53 unique:\", length(result$unique_targets$TP53), \"\\n\")\ncat(\"RB1 unique:\", length(result$unique_targets$RB1), \"\\n\")\n\n# Preview common targets\nhead(result$common_targets, 20)\n\n# ===========================================================================\n# Example 2: Compare Gene Family Members (m6A Writers)\n# ===========================================================================\n# Compare METTL3, METTL14, WTAP to identify complex-specific vs individual functions\n\nresult_m6a <- gpdb_compare_genes(c(\"METTL3\", \"METTL14\", \"WTAP\"))\n\ncat(\"All three regulate:\", result_m6a$n_common, \"genes\\n\")\ncat(\"METTL3-specific:\", length(result_m6a$unique_targets$METTL3), \"genes\\n\")\ncat(\"METTL14-specific:\", length(result_m6a$unique_targets$METTL14), \"genes\\n\")\ncat(\"WTAP-specific:\", length(result_m6a$unique_targets$WTAP), \"genes\\n\")\n\n# Find high-confidence common targets only\ncommon_high_conf <- Reduce(intersect, lapply(result_m6a$all_effects, function(x) {\n  x$target_gene[x$confidence == \"high\"]\n}))\ncat(\"High-confidence common targets:\", length(common_high_conf), \"\\n\")\n\n# ===========================================================================\n# Example 3: Effect Size Comparison\n# ===========================================================================\n# Compare magnitude of effects on common targets\n\nresult_comp <- gpdb_compare_genes(c(\"TP53\", \"MYC\"))\n\n# Merge effect sizes for common targets\ntp53_effects <- result_comp$all_effects$TP53\nmyc_effects <- result_comp$all_effects$MYC\n\n# Find targets in both\ncommon <- intersect(tp53_effects$target_gene, myc_effects$target_gene)\ncat(\"Comparing effect sizes for\", length(common), \"common targets\\n\")\n\n# Get effect sizes\ntp53_common <- tp53_effects[tp53_effects$target_gene %in% common, ]\nmyc_common <- myc_effects[myc_effects$target_gene %in% common, ]\n\n# Correlation (if same order)\ncat(\"Example targets with different effects:\\n\")\nprint(head(tp53_common[, c(\"target_gene\", \"logfc_mean\", \"n_datasets\")]))\n\n# ===========================================================================\n# Next Steps\n# ===========================================================================\n# For complete workflows, see:\n# - Enrichment of common targets: ?gpdb_enrich\n# - Context comparison (same gene, different tissues): ?gpdb_compare_contexts\n# - Network visualization: ?gpdb_plot_network\n## End(No test)\n\n\n\n",
    "return_value": "List object with comparative analysis results: **Return Structure**: genes Character vector of compared gene symbols (standardized format) n_common Integer count of targets regulated by ALL input genes common_targets Character vector of shared target gene symbols. These genes are affected by perturbation of ANY of the input genes, representing potential convergent pathways or shared regulatory mechanisms. unique_targets Named list where each element contains targets unique to that gene (not shared with others). Useful for identifying gene-specific functions. all_effects Named list of data.frames, one per gene, containing complete target information with columns: perturbed_gene : The knocked-out/down gene target_gene : Affected target gene symbol logfc_mean : Average log2 fold change (positive = upregulated) n_datasets : Number of supporting experiments confidence : Evidence strength (\"high\"/\"medium\"/\"low\") overlap_matrix Currently NULL. Reserved for pairwise overlap matrix visualization in future versions. **What You Can Do Next**: Analyze common targets: enrichr(result$common_targets) or gpdb_enrich(result$common_targets) Filter high-confidence common targets: Reduce(intersect, lapply(result$all_effects, function(x) x$target_gene[x$confidence == \"high\"])) Visualize overlap: Create Venn diagram with VennDiagram or UpSet plot Compare effect sizes: Merge data.frames in result$all_effects by target_gene **Alternative Methods**: gpdb_compare_contexts : Use when comparing SAME gene across different tissues/cell lines instead of comparing different genes. Manual comparison: Query individual genes with gpdb_find_targets () and perform custom set operations if you need more control.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "genes: Character vector. Gene symbols to compare (e.g., c(\"TP53\", \"RB1\"), c(\"METTL3\", \"METTL14\", \"WTAP\")). Minimum 2 genes required. All genes are case-insensitive and automatically formatted to standard symbols.\nmetric: Character. Comparison metric: \"overlap\" (default, target overlap analysis), \"correlation\" (not yet implemented), \"difference\" (not yet implemented). Currently only \"overlap\" is fully supported for identifying common/unique targets.\ncontext: List. Optional filters to restrict analysis to specific biological contexts. Not currently used but reserved for future tissue/cell line-specific comparisons.",
    "simple_arguments": "genes: Character vector. Gene symbols to compare (e.g., c(\"TP53\", \"RB1\"), c(\"METTL3\", \"METTL14\", \"WTAP\")). Minimum 2 genes required. All genes are case-insensitive and automatically formatted to standard symbols."
  },
  "gpdb_enrich": {
    "package": "GenePerturbR",
    "function_name": "gpdb_enrich",
    "title": "Pathway Enrichment Analysis with Over-Representation Test",
    "description": "Identify enriched biological pathways in upregulated and downregulated gene sets using over-representation analysis (ORA) with Fisher's exact test. Automatically filters protein-coding genes and performs separate enrichment for each direction to reveal distinct pathway changes. Supports 9 annotation databases including GO/KEGG/Reactome/MSigDB for comprehensive pathway discovery and functional interpretation.",
    "user_queries": ["What biological pathways are enriched in my upregulated genes?", "How do I interpret enrichment p-values and fold enrichment?", "Should I filter protein-coding genes for GO enrichment?", "What's the difference between GO biological process and molecular function?", "Can I analyze upregulated and downregulated genes separately?", "Which enrichment database should I use: GO, KEGG, or Reactome?", "How many genes do I need for reliable pathway enrichment?", "What does FDR q-value mean in enrichment analysis?", "How to customize background genes for tissue-specific enrichment?", "Can I run enrichment on mouse or rat gene lists?", "Why are there no significant pathways in my results?", "How to compare enrichment results between different conditions?", "What's the minimum p-value cutoff for pathway significance?", "Should I use Hallmark or Canonical pathways in MSigDB?", "How to export enrichment results for publication?", "Can I visualize enrichment results as dotplots or networks?", "What does \"10/100 genes in pathway\" mean?", "How to focus enrichment on top 50 strongest regulated genes?", "Why does GO enrichment take longer than KEGG enrichment?", "Can I run enrichment on gene symbols directly without IDs?"],
    "usage": "gpdb_enrich( targets, enrich.type = c(\"GO\", \"KEGG\", \"Wiki\", \"Reactome\", \"MsigDB\", \"Mesh\", \"HgDisease\", \"Enrichrdb\", \"Self\"), organism = \"hs\", filter.pcg = TRUE, min.genes = 10, split.by = c(\"auto\", \"direction\", \"none\"), top_up = NULL, top_down = NULL, p.cutoff = 0.05, q.cutoff = 0.05, background.genes = NULL, GO.ont = \"bp\", KEGG.category = \"pathway\", Msigdb.category = \"H\", return.all = TRUE, ... )",
    "parameters": [
      {
        "name": "targets",
        "has_default": false,
        "description": "Flexible input accepting multiple formats: gpdb_find_targets result (list with $upregulated and $downregulated ) Named list with $up and $down gene vectors Character vector of gene symbols (analyzed as single group)"
      },
      {
        "name": "enrich.type",
        "has_default": true,
        "default_value": "c(\"GO\", \"KEGG\", \"Wiki\", \"Reactome\", \"MsigDB\", \"Mesh\", \"HgDisease\", \"Enrichrdb\", \"Self\")",
        "description": "Character. Annotation database for pathway enrichment. Options: \"GO\" (Gene Ontology), \"KEGG\" (pathways), \"Wiki\" (WikiPathways), \"Reactome\", \"MsigDB\" (Molecular Signatures), \"Mesh\", \"HgDisease\", \"Enrichrdb\", \"Self\". Default: \"GO\"."
      },
      {
        "name": "organism",
        "has_default": true,
        "default_value": "\"hs\"",
        "description": "Character. Species code: \"hs\" (human), \"mm\" (mouse), \"rn\" (rat), etc. Default: \"hs\". Passed to geneset/genekitr2 for ID conversion."
      },
      {
        "name": "filter.pcg",
        "has_default": true,
        "default_value": "TRUE",
        "description": "Logical. Filter to protein-coding genes only (default: TRUE). Recommended for accurate enrichment as GO/KEGG primarily annotate PCGs. Set FALSE to include non-coding genes (lncRNA, miRNA)."
      },
      {
        "name": "min.genes",
        "has_default": true,
        "default_value": "10",
        "description": "Integer. Minimum protein-coding genes required after filtering (default: 10). Warns if below threshold. Consider increasing"
      },
      {
        "name": "split.by",
        "has_default": true,
        "default_value": "c(\"auto\", \"direction\", \"none\")",
        "description": "Character. Gene splitting strategy: \"auto\" (detect structure), \"direction\" (separate up/down), \"none\" (analyze together). Default: \"auto\". top_up Integer. Number of top upregulated genes to analyze (default: NULL, uses all). Useful for focusing on strongest perturbation effects. top_down Integer. Number of top downregulated genes to analyze (default: NULL, uses all)."
      },
      {
        "name": "top_up",
        "has_default": true,
        "default_value": "NULL"
      },
      {
        "name": "top_down",
        "has_default": true,
        "default_value": "NULL",
        "description": "or disable filter.pcg ."
      },
      {
        "name": "p.cutoff",
        "has_default": true,
        "default_value": "0.05",
        "description": "Numeric. Raw p-value cutoff for significance (default: 0.05). Pathways with p < 0.05 marked as significant."
      },
      {
        "name": "q.cutoff",
        "has_default": true,
        "default_value": "0.05",
        "description": "Numeric. Adjusted p-value (FDR) cutoff for significance (default: 0.05). More stringent than p-value for multiple testing correction."
      },
      {
        "name": "background.genes",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character vector. Custom background genes (default: NULL, uses database genes). Provide when analyzing specific gene sets (e.g., expressed genes in your dataset)."
      },
      {
        "name": "GO.ont",
        "has_default": true,
        "default_value": "\"bp\"",
        "description": "Character. GO ontology type: \"bp\" (biological process), \"cc\" (cellular component), \"mf\" (molecular function), \"all\". Default: \"bp\". Only used when enrich.type = \"GO\" ."
      },
      {
        "name": "KEGG.category",
        "has_default": true,
        "default_value": "\"pathway\"",
        "description": "Character. KEGG category to query (default: \"pathway\"). Only used when enrich.type = \"KEGG\" ."
      },
      {
        "name": "Msigdb.category",
        "has_default": true,
        "default_value": "\"H\"",
        "description": "Character. MSigDB category: \"H\" (Hallmark, default), \"C1-C8\". Only used when enrich.type = \"MsigDB\" ."
      },
      {
        "name": "return.all",
        "has_default": true,
        "default_value": "TRUE",
        "description": "Logical. Return all pathways or only significant ones (default: TRUE). FALSE returns only pathways passing p.cutoff and q.cutoff ."
      },
      {
        "name": "...",
        "has_default": false,
        "description": "Additional arguments passed to geneset/genekitr2::ORA() ."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage (TESTED - runtime: 29.8 sec)\n# ===========================================================================\n# Scientific Question: What pathways are enriched in TP53 perturbation?\n# Query: TP53 downstream targets with GO biological process enrichment\n# Expected output: Separate enrichment for upregulated and downregulated genes\n\n# Zero configuration - just run!\nlibrary(GenePerturbR)\n\n# Step 1: Get gene targets\ntargets <- gpdb_find_targets(\"TP53\", top_n = 100, min_confidence = \"high\")\ncat(\"Upregulated:\", nrow(targets$upregulated), \"genes\\n\")\ncat(\"Downregulated:\", nrow(targets$downregulated), \"genes\\n\")\n\n# Step 2: Perform enrichment\nresult <- gpdb_enrich(\n  targets,\n  enrich.type = \"GO\",\n  GO.ont = \"bp\", # Biological process\n  filter.pcg = TRUE, # Recommended for GO\n  p.cutoff = 0.05,\n  q.cutoff = 0.05\n)\n\n# Verify output structure\ncat(\"\\nResult class:\", class(result)[1], \"\\n\")\ncat(\"Elements:\", paste(names(result), collapse = \", \"), \"\\n\")\ncat(\"Significant UP pathways:\", nrow(result$upregulated$Sig), \"\\n\")\ncat(\"Significant DOWN pathways:\", nrow(result$downregulated$Sig), \"\\n\")\n\n# Quick preview of top pathways\nif (nrow(result$upregulated$Sig) > 0) {\n  head(result$upregulated$Sig[, c(\"Description\", \"pvalue\", \"p.adjust\", \"Count\")])\n}\n\n# ===========================================================================\n# Example 2: Database Comparison (GO vs KEGG vs Reactome)\n# ===========================================================================\n# Compare pathway enrichment across different annotation databases\n\n# GO enrichment (comprehensive, ~15K terms)\ngo_result <- gpdb_enrich(targets, enrich.type = \"GO\", GO.ont = \"bp\")\ncat(\"GO pathways tested:\", nrow(go_result$upregulated$All), \"\\n\")\n\n# KEGG enrichment (curated pathways, ~300 terms)\nkegg_result <- gpdb_enrich(targets, enrich.type = \"KEGG\")\ncat(\"KEGG pathways tested:\", nrow(kegg_result$upregulated$All), \"\\n\")\n\n# Reactome enrichment (detailed pathway hierarchy, ~2K terms)\nreactome_result <- gpdb_enrich(targets, enrich.type = \"Reactome\")\ncat(\"Reactome pathways tested:\", nrow(reactome_result$upregulated$All), \"\\n\")\n\n# Compare significant findings\ncat(\"\\nSignificant pathways found:\\n\")\ncat(\n  \"  GO:\", nrow(go_result$upregulated$Sig), \"(up)\",\n  nrow(go_result$downregulated$Sig), \"(down)\\n\"\n)\ncat(\n  \"  KEGG:\", nrow(kegg_result$upregulated$Sig), \"(up)\",\n  nrow(kegg_result$downregulated$Sig), \"(down)\\n\"\n)\n\n# ===========================================================================\n# Example 3: Parameter Optimization (PCG filtering and gene count)\n# ===========================================================================\n# Test impact of protein-coding gene filtering and input gene count\n\n# Default: Filter PCGs, top 100 genes\nresult_default <- gpdb_enrich(\n  targets,\n  enrich.type = \"GO\",\n  filter.pcg = TRUE, # Keep only protein-coding genes\n  top_up = 100,\n  top_down = 100\n)\n\n# Alternative: Include all genes, top 200\nresult_all <- gpdb_enrich(\n  targets,\n  enrich.type = \"GO\",\n  filter.pcg = FALSE, # Include non-coding genes\n  top_up = 200,\n  top_down = 200\n)\n\n# Compare gene counts after filtering\ncat(\"PCG filtering impact:\\n\")\ncat(\"  With filter:\", result_default$params$n_genes_up, \"genes (up)\\n\")\ncat(\"  Without filter:\", result_all$params$n_genes_up, \"genes (up)\\n\")\n\n# ===========================================================================\n# Example 4: Direct Gene List Input (custom analysis)\n# ===========================================================================\n# Enrich custom gene lists without database query\n\n# Named list format\ncustom_genes <- list(\n  up = c(\"MYC\", \"CCND1\", \"CDK4\", \"CDK6\", \"E2F1\"),\n  down = c(\"TP53\", \"RB1\", \"CDKN1A\", \"CDKN1B\", \"CDKN2A\")\n)\ncustom_result <- gpdb_enrich(custom_genes, enrich.type = \"KEGG\")\n\n# Single gene vector (analyzed as one group)\ngene_vector <- c(\"MYC\", \"TP53\", \"KRAS\", \"EGFR\", \"PIK3CA\")\nsingle_result <- gpdb_enrich(\n  gene_vector,\n  enrich.type = \"GO\",\n  split.by = \"none\" # Don't try to split by direction\n)\n\n# ===========================================================================\n# Next Steps (Complete Workflow)\n# ===========================================================================\n# For complete pathway analysis workflows, see:\n# - Visualization: ?gpdb_plot_enrichment\n# - Network analysis: ?gpdb_plot_network\n# - Query more targets: ?gpdb_find_targets\n# - Find regulators: ?gpdb_find_regulators\n# - Compare conditions: Run gpdb_enrich on multiple gene sets\n## End(No test)\n\n\n",
    "return_value": "gpdb_enrichment object (list) with three elements: **Return Structure**: upregulated List with $All and $Sig data.frames. Contains enrichment results for upregulated genes. $All : All pathways tested (e.g., 15461 GO terms) $Sig : Significant pathways (p < 0.05, q < 0.05) Key columns: Description (pathway name), pvalue , p.adjust , Count (genes in pathway), FoldEnrich (enrichment ratio) downregulated List with $All and $Sig data.frames. Contains enrichment results for downregulated genes (same structure as upregulated). params List of analysis parameters: enrich.type , organism , filter.pcg , split.by , p.cutoff , q.cutoff , GO.ont , n_genes_up , n_genes_down . **What You Can Do Next**: Visualize results: gpdb_plot_enrichment (result) for paired dotplots Filter significant pathways: result$upregulated$Sig[1:10, ] for top 10 Export results: write.csv(result$upregulated$Sig, \"enrichment.csv\") Compare databases: Run with different enrich.type (GO vs KEGG vs Reactome) Validate in network: gpdb_plot_network () to visualize gene-pathway relationships **Alternative Methods**: geneset/genekitr2::GSEA : Use when you have ranked gene list and want to detect subtle pathway changes. clusterProfiler::enrichGO : Use for advanced GO enrichment with custom background.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "targets: Flexible input accepting multiple formats: gpdb_find_targets result (list with $upregulated and $downregulated ) Named list with $up and $down gene vectors Character vector of gene symbols (analyzed as single group)\nenrich.type: Character. Annotation database for pathway enrichment. Options: \"GO\" (Gene Ontology), \"KEGG\" (pathways), \"Wiki\" (WikiPathways), \"Reactome\", \"MsigDB\" (Molecular Signatures), \"Mesh\", \"HgDisease\", \"Enrichrdb\", \"Self\". Default: \"GO\".\norganism: Character. Species code: \"hs\" (human), \"mm\" (mouse), \"rn\" (rat), etc. Default: \"hs\". Passed to geneset/genekitr2 for ID conversion.\nfilter.pcg: Logical. Filter to protein-coding genes only (default: TRUE). Recommended for accurate enrichment as GO/KEGG primarily annotate PCGs. Set FALSE to include non-coding genes (lncRNA, miRNA).\nmin.genes: Integer. Minimum protein-coding genes required after filtering (default: 10). Warns if below threshold. Consider increasing\nsplit.by: Character. Gene splitting strategy: \"auto\" (detect structure), \"direction\" (separate up/down), \"none\" (analyze together). Default: \"auto\". top_up Integer. Number of top upregulated genes to analyze (default: NULL, uses all). Useful for focusing on strongest perturbation effects. top_down Integer. Number of top downregulated genes to analyze (default: NULL, uses all).\ntop_up: [No description]\ntop_down: or disable filter.pcg .\np.cutoff: Numeric. Raw p-value cutoff for significance (default: 0.05). Pathways with p < 0.05 marked as significant.\nq.cutoff: Numeric. Adjusted p-value (FDR) cutoff for significance (default: 0.05). More stringent than p-value for multiple testing correction.\nbackground.genes: Character vector. Custom background genes (default: NULL, uses database genes). Provide when analyzing specific gene sets (e.g., expressed genes in your dataset).\nGO.ont: Character. GO ontology type: \"bp\" (biological process), \"cc\" (cellular component), \"mf\" (molecular function), \"all\". Default: \"bp\". Only used when enrich.type = \"GO\" .\nKEGG.category: Character. KEGG category to query (default: \"pathway\"). Only used when enrich.type = \"KEGG\" .\nMsigdb.category: Character. MSigDB category: \"H\" (Hallmark, default), \"C1-C8\". Only used when enrich.type = \"MsigDB\" .\nreturn.all: Logical. Return all pathways or only significant ones (default: TRUE). FALSE returns only pathways passing p.cutoff and q.cutoff .\n...: Additional arguments passed to geneset/genekitr2::ORA() .",
    "simple_arguments": "targets: Flexible input accepting multiple formats: gpdb_find_targets result (list with $upregulated and $downregulated ) Named list with $up and $down gene vectors Character vector of gene symbols (analyzed as single group)\n...: Additional arguments passed to geneset/genekitr2::ORA() ."
  },
  "gpdb_find_pathway_regulators": {
    "package": "GenePerturbR",
    "function_name": "gpdb_find_pathway_regulators",
    "title": "Find Genes Affecting Pathway",
    "description": "Identify perturbed genes whose downstream effects significantly enrich in a specific pathway. Queries 18.9M gene-gene relationships from GenePerturbR database to find which gene perturbations impact pathway members. **Database aggregates 7,665 experiments with multi-dataset confidence scoring**, enabling discovery of pathway-level regulatory mechanisms for drug target identification and systems biology.",
    "user_queries": ["Which genes regulate the cell cycle when perturbed?", "What perturbations affect apoptosis pathways in my system?", "How do I find genes that control specific biological processes?", "Which knockout experiments impact immune response pathways?", "Can I identify pathway-level drug targets from perturbation data?", "What genes have the strongest effect on metabolic pathways?", "How reliable are pathway-level perturbation effects?", "Which cell cycle regulators show high-confidence effects?", "Can I filter results by pathway coverage percentage?", "How do I compare pathway effects across different databases (GO vs KEGG)?", "What genes affect both cell cycle and apoptosis pathways?", "Which perturbations have mixed effects on pathway genes?", "How do I find tissue-specific pathway regulators?", "Can I identify genes that activate vs suppress pathways?", "What's the best confidence threshold for pathway analysis?", "How do I validate pathway-level predictions experimentally?", "Which databases work best for different pathway types?", "Can I analyze disease-related pathway perturbations?", "How do I interpret conflicting pathway directions?", "What's next after finding pathway regulators?"],
    "usage": "gpdb_find_pathway_regulators( pathway, database = c(\"GO\", \"KEGG\", \"Reactome\"), effect = c(\"any\", \"activate\", \"suppress\"), min_confidence = c(\"medium\", \"high\", \"low\"), min_pathway_genes = 5, organism = \"hs\", top_n = 50 )",
    "parameters": [
      {
        "name": "pathway",
        "has_default": false,
        "description": "Character. Pathway name (partial match supported, e.g., \"cell cycle\", \"apoptosis\"). Uses geneset/genekitr2 pathway"
      },
      {
        "name": "database",
        "has_default": true,
        "default_value": "c(\"GO\", \"KEGG\", \"Reactome\")",
        "description": "for gene set definition. Supports GO biological processes, KEGG pathways, and Reactome pathways. database Character. Pathway database to query: \"GO\", \"KEGG\", \"Reactome\" (default: \"GO\"). GO uses biological process ontology (GO:BP). KEGG includes metabolic and signaling pathways. Reactome provides hierarchical pathway annotations."
      },
      {
        "name": "effect",
        "has_default": true,
        "default_value": "c(\"any\", \"activate\", \"suppress\")",
        "description": "Character. Effect direction filter (default: \"any\"). Options: \"any\" (both directions), \"activate\" (upregulation), \"suppress\" (downregulation). Determines which perturbations to include based on their impact on pathway genes."
      },
      {
        "name": "min_confidence",
        "has_default": true,
        "default_value": "c(\"medium\", \"high\", \"low\")",
        "description": "Character. Evidence strength filter (default: \"medium\"). Options: \"high\" (5+ datasets, >80 % consistency), \"medium\" (2-4 datasets, >70% consistency), \"low\" (1 dataset, exploratory). Higher confidence = more reliable pathway effects."
      },
      {
        "name": "min_pathway_genes",
        "has_default": true,
        "default_value": "5",
        "description": "Integer. Minimum pathway genes affected to consider a perturbation relevant (default: 5). Filters out perturbations with insufficient pathway coverage."
      },
      {
        "name": "organism",
        "has_default": true,
        "default_value": "\"hs\"",
        "description": "Character. Organism code: \"hs\" (human, default), \"mm\" (mouse). Must match GenePerturbR database organism. Currently only human data available."
      },
      {
        "name": "top_n",
        "has_default": true,
        "default_value": "50",
        "description": "Integer. Maximum perturbations to return (default: 50). Results ranked by number of pathway genes affected and effect size."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage (TESTED - runtime: 17.05 sec)\n# ===========================================================================\n# Scientific Question: Which gene perturbations affect cell cycle?\n# Query: \"cell cycle\" GO biological process pathway\n# Expected output: Ranked list of perturbed genes with pathway impact metrics\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Find genes affecting cell cycle\ncc_regulators <- gpdb_find_pathway_regulators(\n  pathway = \"cell cycle\",\n  database = \"GO\",\n  min_confidence = \"medium\",\n  min_pathway_genes = 5,\n  top_n = 50\n)\n# Found: G1/S transition of mitotic cell cycle (12 genes)\n# Result: 50 perturbed genes affecting >= 5 pathway members\n\n# Verify output structure\nstr(cc_regulators, max.level = 1)\ncat(\"Perturbations found:\", nrow(cc_regulators), \"\\n\")\n# Output: 50 perturbed genes\n\n# Preview top regulators\nhead(cc_regulators, 10)\n# Top hits: OGT, SOX10, FLI1, EWSR1, CDK7, PPARG...\n\n# Examine strongest pathway impact\ncat(\"Top regulator:\", cc_regulators$perturbed_gene[1], \"\\n\")\n# Output: OGT\ncat(\n  \"Affects:\", cc_regulators$n_pathway_affected[1],\n  \"of\", cc_regulators$pathway_size[1], \"pathway genes\\n\"\n)\n# Output: 12 of 12 pathway genes (100%)\ncat(\"Coverage:\", round(cc_regulators$percent_affected[1], 2), \"%\\n\")\n# Output: 100%\ncat(\"Effect size:\", round(cc_regulators$mean_effect_size[1], 2), \"\\n\")\n# Output: 1.14\n\n# ===========================================================================\n# Example 2: Pathway Effect Direction (TESTED - runtime: 9.34 + 9.61 sec)\n# ===========================================================================\n# Compare genes that activate vs suppress apoptosis\n\n# Genes that activate apoptosis (upregulate pathway genes)\napop_activators <- gpdb_find_pathway_regulators(\n  pathway = \"apoptosis\",\n  database = \"GO\",\n  effect = \"activate\", # Only upregulation\n  min_pathway_genes = 3\n)\n# Found: Execution phase of apoptosis (3 genes)\n# Result: 28 activators\n\n# Genes that suppress apoptosis (downregulate pathway genes)\napop_suppressors <- gpdb_find_pathway_regulators(\n  pathway = \"apoptosis\",\n  database = \"GO\",\n  effect = \"suppress\", # Only downregulation\n  min_pathway_genes = 3\n)\n# Result: 30 suppressors\n\n# Compare results\ncat(\"Apoptosis activators:\", nrow(apop_activators), \"genes\\n\")\n# Output: 28 genes\ncat(\"Apoptosis suppressors:\", nrow(apop_suppressors), \"genes\\n\")\n# Output: 30 genes\n\n# Top activators and suppressors\ncat(\"\\nTop activators:\\n\")\nprint(head(apop_activators[, c(\"perturbed_gene\", \"n_pathway_affected\", \"effect_direction\")], 5))\n# Top: EIF3D, PRKDC, NFKB1, RELA, STAT3...\n\ncat(\"\\nTop suppressors:\\n\")\nprint(head(apop_suppressors[, c(\"perturbed_gene\", \"n_pathway_affected\", \"effect_direction\")], 5))\n# Top: BRD9, SMARCA4, ARID1A, SMARCC1, SMARCC2...\n\n# ===========================================================================\n# Example 3: Confidence Level Filtering\n# ===========================================================================\n# Focus on high-confidence pathway regulators for experimental validation\n\n# All confidence levels\nall_regulators <- gpdb_find_pathway_regulators(\n  pathway = \"DNA repair\",\n  database = \"GO\",\n  min_confidence = \"low\", # Include all evidence\n  min_pathway_genes = 5\n)\n\n# High confidence only (publication-grade)\nreliable_regulators <- gpdb_find_pathway_regulators(\n  pathway = \"DNA repair\",\n  database = \"GO\",\n  min_confidence = \"high\", # 5+ datasets, >80% consistency\n  min_pathway_genes = 5\n)\n\n# Compare reliability\ncat(\"All evidence:\", nrow(all_regulators), \"regulators\\n\")\ncat(\"High confidence:\", nrow(reliable_regulators), \"regulators\\n\")\ncat(\n  \"Average confidence (all):\",\n  round(mean(all_regulators$avg_confidence, na.rm = TRUE), 3), \"\\n\"\n)\ncat(\n  \"Average confidence (high):\",\n  round(mean(reliable_regulators$avg_confidence, na.rm = TRUE), 3), \"\\n\"\n)\n\n# ===========================================================================\n# Example 4: Database Comparison\n# ===========================================================================\n# Compare results from different pathway databases\n\n# GO Biological Process (broad, hierarchical)\ngo_results <- gpdb_find_pathway_regulators(\n  pathway = \"immune response\",\n  database = \"GO\",\n  min_pathway_genes = 5\n)\n\n# KEGG Pathway (curated, well-defined)\nkegg_results <- gpdb_find_pathway_regulators(\n  pathway = \"immune\",\n  database = \"KEGG\",\n  min_pathway_genes = 5\n)\n\n# Compare coverage\ncat(\"GO immune response:\", nrow(go_results), \"regulators\\n\")\ncat(\"KEGG immune pathways:\", nrow(kegg_results), \"regulators\\n\")\n\n# Find genes detected by both databases\ncommon_genes <- intersect(go_results$perturbed_gene, kegg_results$perturbed_gene)\ncat(\"Common regulators:\", length(common_genes), \"\\n\")\ncat(\n  \"Database-specific:\",\n  nrow(go_results) - length(common_genes), \"(GO),\",\n  nrow(kegg_results) - length(common_genes), \"(KEGG)\\n\"\n)\n\n# ===========================================================================\n# Next Steps (Analyze top pathway regulators)\n# ===========================================================================\n# For complete workflows, see:\n# - Query effects: result <- gpdb_what_happens(cc_regulators$perturbed_gene[1])\n# - Find targets: targets <- gpdb_find_targets(cc_regulators$perturbed_gene[1])\n# - Visualize: gpdb_plot_network(cc_regulators$perturbed_gene[1], top_targets = 50)\n# - Compare: gpdb_compare_genes(cc_regulators$perturbed_gene[1:3])\n# - Load data: gpdb_list_datasets(gene = cc_regulators$perturbed_gene[1])\n## End(No test)\n\n\n",
    "return_value": "Data.frame with perturbed genes affecting the pathway, ranked by impact strength. **Return Structure** (8 columns): perturbed_gene Gene whose perturbation affects pathway (e.g., \"TP53\", \"MYC\") pathway Matched pathway name from database pathway_size Total genes in pathway definition n_pathway_affected Number of pathway genes regulated by perturbation percent_affected Percentage of pathway genes affected (n_affected/pathway_size) mean_effect_size Average |logFC| across affected pathway genes n_upregulated Pathway genes upregulated by perturbation n_downregulated Pathway genes downregulated by perturbation avg_confidence Average confidence score (0.5-1.0) of pathway gene relationships effect_direction Dominant effect: \"activate\" (more up), \"suppress\" (more down), \"mixed\" **What You Can Do Next**: Examine specific perturbation: gpdb_what_happens(result$perturbed_gene[1]) Find affected genes: gpdb_find_targets(result$perturbed_gene[1], top_n = 100) Visualize network: gpdb_plot_network(result$perturbed_gene[1], top_targets = 50) Compare top hits: gpdb_compare_genes(result$perturbed_gene[1:3]) Load raw data: gpdb_list_datasets(gene = result$perturbed_gene[1]) **Alternative Methods**: gpdb_enrich : Perform enrichment on gene list. Use when: Have specific genes and want to find enriched pathways. gpdb_find_targets : Find downstream targets of gene. Use when: Focus on single gene perturbation rather than pathway level.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "pathway: Character. Pathway name (partial match supported, e.g., \"cell cycle\", \"apoptosis\"). Uses geneset/genekitr2 pathway\ndatabase: for gene set definition. Supports GO biological processes, KEGG pathways, and Reactome pathways. database Character. Pathway database to query: \"GO\", \"KEGG\", \"Reactome\" (default: \"GO\"). GO uses biological process ontology (GO:BP). KEGG includes metabolic and signaling pathways. Reactome provides hierarchical pathway annotations.\neffect: Character. Effect direction filter (default: \"any\"). Options: \"any\" (both directions), \"activate\" (upregulation), \"suppress\" (downregulation). Determines which perturbations to include based on their impact on pathway genes.\nmin_confidence: Character. Evidence strength filter (default: \"medium\"). Options: \"high\" (5+ datasets, >80 % consistency), \"medium\" (2-4 datasets, >70% consistency), \"low\" (1 dataset, exploratory). Higher confidence = more reliable pathway effects.\nmin_pathway_genes: Integer. Minimum pathway genes affected to consider a perturbation relevant (default: 5). Filters out perturbations with insufficient pathway coverage.\norganism: Character. Organism code: \"hs\" (human, default), \"mm\" (mouse). Must match GenePerturbR database organism. Currently only human data available.\ntop_n: Integer. Maximum perturbations to return (default: 50). Results ranked by number of pathway genes affected and effect size.",
    "simple_arguments": "pathway: Character. Pathway name (partial match supported, e.g., \"cell cycle\", \"apoptosis\"). Uses geneset/genekitr2 pathway"
  },
  "gpdb_find_regulators": {
    "package": "GenePerturbR",
    "function_name": "gpdb_find_regulators",
    "title": "Find Upstream Regulators of Target Gene",
    "description": "Identify genes that control target gene expression through perturbation analysis, aggregated from 7,665 RNA-seq datasets for regulatory network reconstruction. **Database covers 2,810 genes across 1,063 cell lines** with multi-dataset consistency validation. Returns regulators classified as activators (knockdown decreases target) or repressors (knockdown increases target).",
    "user_queries": ["What genes regulate MYC expression?", "Which transcription factors control my target gene?", "How do I find upstream regulators from perturbation data?", "What is the difference between activators and repressors?", "Can I filter regulators by confidence level or dataset count?", "How reliable are the predicted regulatory relationships?", "Which genes act as negative regulators (repressors) of my target?", "How do I identify positive regulators (activators) of a gene?", "Can I compare regulators across different genes or pathways?", "What tissue or cell line contexts support these regulatory relationships?", "How do I validate predicted regulators experimentally?", "Which databases provide evidence for these gene-gene interactions?", "How to find high-confidence regulators for CRISPR screen validation?", "Can I reconstruct upstream regulatory network for my gene of interest?", "How to interpret consistency scores and effect sizes for regulators?", "What if my target gene has no regulators found in the database?", "How to export regulator list for pathway analysis or network visualization?", "Can I filter regulators specific to cancer cell lines or primary tissues?", "How to identify context-dependent regulators (tissue-specific activation)?", "What is the best workflow to go from regulators to mechanistic validation?"],
    "usage": "gpdb_find_regulators( target_gene, direction = c(\"any\", \"up\", \"down\"), top_n = 50, min_datasets = 2, min_confidence = c(\"medium\", \"any\", \"high\", \"low\"), return_separate = TRUE )",
    "parameters": [
      {
        "name": "target_gene",
        "has_default": false,
        "description": "Character. Target gene symbol (e.g., \"MYC\", \"TP53\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended."
      },
      {
        "name": "direction",
        "has_default": true,
        "default_value": "c(\"any\", \"up\", \"down\")",
        "description": "Character. Regulation type to find: \"any\": Both activators and repressors (default) \"up\": Only repressors (genes whose knockdown increases target) \"down\": Only activators (genes whose knockdown decreases target)"
      },
      {
        "name": "top_n",
        "has_default": true,
        "default_value": "50",
        "description": "Integer. Maximum regulators per direction (default 50). Larger values provide comprehensive results but may include lower-confidence relationships. Recommended: 20-50 for focused analysis, 100+ for exploratory."
      },
      {
        "name": "min_datasets",
        "has_default": true,
        "default_value": "2",
        "description": "Integer. Minimum supporting datasets for evidence (default 2). Higher values increase reliability. Recommended: 1 (exploratory), 2 (standard), 5+ (high-confidence publication-grade)."
      },
      {
        "name": "min_confidence",
        "has_default": true,
        "default_value": "c(\"medium\", \"any\", \"high\", \"low\")",
        "description": "Character. Evidence strength filter: \"medium\": 2-4 datasets, 70 %+ consistency (default, balanced) \"high\": 5+ datasets, 80 %+ consistency (most reliable) \"low\": 1 dataset (preliminary findings) \"any\": All confidence levels"
      },
      {
        "name": "return_separate",
        "has_default": true,
        "default_value": "TRUE",
        "description": "Logical. When direction=\"any\", whether to return activators and repressors as separate list elements (TRUE, default) or combined data.frame (FALSE). Separate format clarifies regulatory logic."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage - Find MYC Regulators (TESTED - runtime: 0.218 sec)\n# ===========================================================================\n# Scientific Question: What genes control MYC oncogene expression?\n# Query: MYC upstream regulators (both activators and repressors)\n# Expected output: List with separate activators and repressors\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\nresult <- gpdb_find_regulators(\n  target_gene = \"MYC\",\n  top_n = 50\n)\n\n# Verify output structure\nstr(result, max.level = 1)\ncat(\"Repressors found:\", nrow(result$repressors), \"\\n\")\ncat(\"Activators found:\", nrow(result$activators), \"\\n\")\n\n# Quick preview of results\ncat(\"\\nTop 5 MYC repressors (knockdown increases MYC):\\n\")\nprint(head(result$repressors[, c(\"perturbed_gene\", \"logfc_mean\", \"n_datasets\", \"confidence\")], 5))\n\ncat(\"\\nTop 5 MYC activators (knockdown decreases MYC):\\n\")\nprint(head(result$activators[, c(\"perturbed_gene\", \"logfc_mean\", \"n_datasets\", \"confidence\")], 5))\n\n# ===========================================================================\n# Example 2: High-Confidence Regulators (Compare evidence levels)\n# ===========================================================================\n# Find publication-grade regulators with strong multi-dataset support\n\n# High confidence: 5+ datasets, most reliable\nresult_high <- gpdb_find_regulators(\n  target_gene = \"MYC\",\n  min_confidence = \"high\",\n  top_n = 30\n)\n\n# Medium confidence: 2-4 datasets, moderate evidence\nresult_medium <- gpdb_find_regulators(\n  target_gene = \"MYC\",\n  min_confidence = \"medium\",\n  top_n = 30\n)\n\n# Compare results\ncat(\n  \"High confidence regulators:\", nrow(result_high$repressors), \"repressors,\",\n  nrow(result_high$activators), \"activators\\n\"\n)\ncat(\n  \"Medium confidence regulators:\", nrow(result_medium$repressors), \"repressors,\",\n  nrow(result_medium$activators), \"activators\\n\"\n)\n\n# High confidence regulators are more reliable for validation experiments\nhigh_conf_repressors <- result_high$repressors$perturbed_gene\ncat(\"\\nHigh-confidence MYC repressors for CRISPR validation:\\n\")\nprint(head(high_conf_repressors, 10))\n\n# ===========================================================================\n# Example 3: Direction-Specific Queries (Find only repressors or activators)\n# ===========================================================================\n# Sometimes you only need one regulatory direction\n\n# Find only TP53 repressors (genes that normally suppress TP53)\ntp53_repressors <- gpdb_find_regulators(\n  target_gene = \"TP53\",\n  direction = \"up\", # Knockdown increases TP53\n  top_n = 20\n)\n\ncat(\"TP53 repressors (single data.frame):\\n\")\nstr(tp53_repressors)\nprint(head(tp53_repressors[, c(\"perturbed_gene\", \"logfc_mean\", \"consistency_score\")], 5))\n\n# Find only TP53 activators (genes that normally promote TP53)\ntp53_activators <- gpdb_find_regulators(\n  target_gene = \"TP53\",\n  direction = \"down\", # Knockdown decreases TP53\n  top_n = 20\n)\n\ncat(\"\\nTP53 activators:\\n\")\nprint(head(tp53_activators[, c(\"perturbed_gene\", \"logfc_mean\", \"consistency_score\")], 5))\n\n# ===========================================================================\n# Example 4: Combined Output Format (return_separate = FALSE)\n# ===========================================================================\n# Get all regulators in single data.frame for easier programmatic filtering\n\nmettl3_regs_combined <- gpdb_find_regulators(\n  target_gene = \"METTL3\",\n  return_separate = FALSE,\n  top_n = 40\n)\n\ncat(\"Combined regulators:\\n\")\ncat(\"Total regulators:\", nrow(mettl3_regs_combined), \"\\n\")\ncat(\"Repressors:\", sum(mettl3_regs_combined$regulation_type == \"repressor\"), \"\\n\")\ncat(\"Activators:\", sum(mettl3_regs_combined$regulation_type == \"activator\"), \"\\n\")\n\n# Easy filtering with combined format\nstrong_regulators <- mettl3_regs_combined[abs(mettl3_regs_combined$logfc_mean) > 1.5, ]\ncat(\"\\nStrong regulators (|logFC| > 1.5):\", nrow(strong_regulators), \"\\n\")\n\n# ===========================================================================\n# Example 5: Filtering by Dataset Count (Evidence strength)\n# ===========================================================================\n# Require minimum number of supporting datasets\n\n# Exploratory: Include single-dataset findings\nresult_min1 <- gpdb_find_regulators(\n  target_gene = \"MYC\",\n  min_datasets = 1,\n  top_n = 50\n)\n\n# Standard: Require 2+ datasets\nresult_min2 <- gpdb_find_regulators(\n  target_gene = \"MYC\",\n  min_datasets = 2,\n  top_n = 50\n)\n\n# Publication-grade: Require 5+ datasets\nresult_min5 <- gpdb_find_regulators(\n  target_gene = \"MYC\",\n  min_datasets = 5,\n  top_n = 50\n)\n\n# Compare dataset requirements impact\ncat(\"min_datasets = 1:\", nrow(result_min1$repressors), \"repressors\\n\")\ncat(\"min_datasets = 2:\", nrow(result_min2$repressors), \"repressors\\n\")\ncat(\"min_datasets = 5:\", nrow(result_min5$repressors), \"repressors\\n\")\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# For complete workflows, see:\n# - Network visualization: ?gpdb_plot_network\n# - Cascade analysis: ?gpdb_analyze_cascade\n# - Compare targets: ?gpdb_find_targets\n# - Enrichment: ?gpdb_enrich\n# - Load datasets: ?gpdb_list_datasets\n## End(No test)\n\n\n",
    "return_value": "When return_separate=TRUE and direction=\"any\" (default), returns list containing: **Return Structure**: result$repressors Data.frame of genes whose knockdown increases target expression (negative regulators) perturbed_gene : Regulator gene symbol target_gene : Target gene (your query gene) logfc_mean : Average log2 fold change (positive = target increases) n_datasets : Number of independent experiments consistency_score : Fraction showing same direction (0.5-1.0) confidence : Evidence classification (high/medium/low) regulation_type : \"repressor\" result$activators Data.frame of genes whose knockdown decreases target expression (positive regulators). Same columns as repressors. result$summary Natural language text summary When direction=\"up\" or direction=\"down\" , returns single data.frame. When return_separate=FALSE , returns combined data.frame with both types. **Programmatic Access Examples**: Get top 10 repressors: head(result$repressors, 10) Filter high confidence: result$activators[result$activators$confidence == \"high\", ] Sort by effect size: result$repressors[order(-result$repressors$logfc_mean), ] Get regulator names: result$repressors$perturbed_gene **What You Can Do Next**: Network visualization: gpdb_plot_network (target_gene, mode = \"regulators\") Cascade analysis: gpdb_analyze_cascade (regulators$repressors$perturbed_gene[1], steps = 3) Compare with targets: gpdb_find_targets (regulators$repressors$perturbed_gene[1]) Enrichment analysis: gpdb_enrich (regulators$repressors$perturbed_gene, enrich.type = \"GO\") Load raw data: gpdb_list_datasets (gene = target_gene) **Alternative Methods**: gpdb_find_targets : Find downstream targets of a gene. Use when you want to know what a gene regulates (opposite direction). gpdb_what_happens : Comprehensive perturbation overview. Use when you need all effects (not just regulation of one target). gpdb_predict_interaction : Predict regulatory mechanism. Use when you have a specific regulator-target pair to validate.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "target_gene: Character. Target gene symbol (e.g., \"MYC\", \"TP53\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended.\ndirection: Character. Regulation type to find: \"any\": Both activators and repressors (default) \"up\": Only repressors (genes whose knockdown increases target) \"down\": Only activators (genes whose knockdown decreases target)\ntop_n: Integer. Maximum regulators per direction (default 50). Larger values provide comprehensive results but may include lower-confidence relationships. Recommended: 20-50 for focused analysis, 100+ for exploratory.\nmin_datasets: Integer. Minimum supporting datasets for evidence (default 2). Higher values increase reliability. Recommended: 1 (exploratory), 2 (standard), 5+ (high-confidence publication-grade).\nmin_confidence: Character. Evidence strength filter: \"medium\": 2-4 datasets, 70 %+ consistency (default, balanced) \"high\": 5+ datasets, 80 %+ consistency (most reliable) \"low\": 1 dataset (preliminary findings) \"any\": All confidence levels\nreturn_separate: Logical. When direction=\"any\", whether to return activators and repressors as separate list elements (TRUE, default) or combined data.frame (FALSE). Separate format clarifies regulatory logic.",
    "simple_arguments": "target_gene: Character. Target gene symbol (e.g., \"MYC\", \"TP53\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended."
  },
  "gpdb_find_targets": {
    "package": "GenePerturbR",
    "function_name": "gpdb_find_targets",
    "title": "Find Downstream Target Genes of Perturbation",
    "description": "Identify genes affected by gene perturbation, aggregated from 7,665 RNA-seq datasets with multi-dataset confidence scoring and effect size filtering. **Database covers 2,810 genes across 1,063 cell lines** with 826,650 high-confidence relationships. Returns upregulated and downregulated targets ranked by effect size for drug target discovery, pathway analysis, and functional genomics.",
    "user_queries": ["What genes does METTL3 regulate?", "Which genes are affected when TP53 is knocked out?", "How do I find downstream targets with high confidence?", "What's the difference between upregulated and downregulated targets?", "Can I filter targets by effect size or dataset count?", "How do I identify strong regulatory relationships vs weak ones?", "What does logFC mean and how should I interpret it?", "How reliable are predicted targets with medium confidence?", "Can I get targets specific to certain tissues or cell lines?", "How to choose between find_targets and what_happens?", "What's the minimum effect size for biological significance?", "How many datasets should I require for publication-grade evidence?", "Can I compare targets across multiple perturbations?", "How to validate predicted targets experimentally?", "What if my gene has very few high-confidence targets?", "How to interpret consistency scores below 0.8?", "Can I use these targets for CRISPR screen design?", "How to filter targets for pathway enrichment analysis?", "What tissue/cell line information is available for targets?", "How to identify direct vs indirect regulatory relationships?"],
    "usage": "gpdb_find_targets( gene, direction = c(\"both\", \"up\", \"down\"), top_n = 50, min_confidence = \"medium\", min_effect_size = 0.5 )",
    "parameters": [
      {
        "name": "gene",
        "has_default": false,
        "description": "Character. Gene symbol to query (e.g., \"TP53\", \"METTL3\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended."
      },
      {
        "name": "direction",
        "has_default": true,
        "default_value": "c(\"both\", \"up\", \"down\")",
        "description": "Character. Target direction filter (default \"both\"): \"both\": Return both upregulated and downregulated targets (returns list) \"up\": Only genes increased by perturbation (returns data.frame) \"down\": Only genes decreased by perturbation (returns data.frame)"
      },
      {
        "name": "top_n",
        "has_default": true,
        "default_value": "50",
        "description": "Integer. Maximum targets per direction to return (default 50). Targets are ranked by effect size (|logFC|). Larger values provide comprehensive results. Recommended: 50 (focused), 100 (exploratory), or use gpdb_what_happens () for complete unfiltered data."
      },
      {
        "name": "min_confidence",
        "has_default": true,
        "default_value": "\"medium\"",
        "description": "Character. Evidence strength filter (default \"medium\"): \"high\": 5+ datasets, >80 % consistency (most reliable, publication-grade) \"medium\": 2-4 datasets, >70 % consistency (balanced, standard analysis) \"low\": 1 dataset (exploratory, requires validation) Higher confidence reduces false positives but may miss context-specific effects."
      },
      {
        "name": "min_effect_size",
        "has_default": true,
        "default_value": "0.5",
        "description": "Numeric. Minimum absolute log2 fold change threshold (default 0.5). Filters targets by biological significance. Recommended: 0.5 (all significant), 1.0 (moderate effects), 1.5 (strong effects, >2.8-fold change). Higher thresholds focus on major regulatory relationships."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage (TESTED - runtime: 0.028 sec)\n# ===========================================================================\n# Scientific Question: What genes does METTL3 m6A methyltransferase regulate?\n# Query: METTL3 downstream targets (both directions)\n# Expected output: List with upregulated and downregulated targets\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\nresult <- gpdb_find_targets(\"METTL3\", top_n = 50)\n\n# Verify output structure\nstr(result, max.level = 1)\ncat(\"Upregulated targets:\", nrow(result$upregulated), \"\\n\")\ncat(\"Downregulated targets:\", nrow(result$downregulated), \"\\n\")\n\n# Quick preview of results\ncat(\"\\nTop 5 upregulated (normally repressed by METTL3):\\n\")\nprint(head(result$upregulated[, c(\"target_gene\", \"logfc_mean\", \"n_datasets\", \"confidence\")], 5))\n\ncat(\"\\nTop 5 downregulated (normally activated by METTL3):\\n\")\nprint(head(result$downregulated[, c(\"target_gene\", \"logfc_mean\", \"n_datasets\", \"confidence\")], 5))\n\n# ===========================================================================\n# Example 2: High-Confidence Targets (Compare evidence levels)\n# ===========================================================================\n# Find publication-grade targets with strong multi-dataset support\n\n# High confidence: 5+ datasets, most reliable\nresult_high <- gpdb_find_targets(\n  \"TP53\",\n  min_confidence = \"high\",\n  top_n = 30\n)\n\n# Medium confidence: 2-4 datasets (default)\nresult_medium <- gpdb_find_targets(\n  \"TP53\",\n  min_confidence = \"medium\",\n  top_n = 30\n)\n\n# Compare results\ncat(\n  \"High confidence targets:\", nrow(result_high$upregulated), \"up,\",\n  nrow(result_high$downregulated), \"down\\n\"\n)\ncat(\n  \"Medium confidence targets:\", nrow(result_medium$upregulated), \"up,\",\n  nrow(result_medium$downregulated), \"down\\n\"\n)\n\n# High confidence targets are more reliable for validation\nhigh_conf_targets <- result_high$upregulated$target_gene\ncat(\"\\nHigh-confidence TP53 targets for experimental validation:\\n\")\nprint(head(high_conf_targets, 10))\n\n# ===========================================================================\n# Example 3: Strong Effect Filtering (Biological significance)\n# ===========================================================================\n# Focus on major regulatory relationships with large effect sizes\n\n# All effects: min_effect_size = 0.5 (default)\nresult_all <- gpdb_find_targets(\n  \"MYC\",\n  min_effect_size = 0.5,\n  top_n = 50\n)\n\n# Moderate effects: |logFC| > 1.0 (2-fold change)\nresult_moderate <- gpdb_find_targets(\n  \"MYC\",\n  min_effect_size = 1.0,\n  top_n = 50\n)\n\n# Strong effects: |logFC| > 1.5 (2.8-fold change)\nresult_strong <- gpdb_find_targets(\n  \"MYC\",\n  min_effect_size = 1.5,\n  top_n = 50\n)\n\n# Compare effect size filtering\ncat(\"All effects (>0.5):\", nrow(result_all$upregulated), \"targets\\n\")\ncat(\"Moderate effects (>1.0):\", nrow(result_moderate$upregulated), \"targets\\n\")\ncat(\"Strong effects (>1.5):\", nrow(result_strong$upregulated), \"targets\\n\")\n\n# Strong effects are major regulatory relationships\ncat(\n  \"\\nAverage logFC (strong effects):\",\n  mean(result_strong$upregulated$logfc_mean), \"\\n\"\n)\n\n# ===========================================================================\n# Example 4: Direction-Specific Queries (Single direction)\n# ===========================================================================\n# Sometimes you only need upregulated or downregulated targets\n\n# Only upregulated targets (genes METTL3 normally represses)\nup_only <- gpdb_find_targets(\n  \"METTL3\",\n  direction = \"up\",\n  top_n = 30\n)\n\ncat(\"Upregulated targets (single data.frame):\\n\")\nstr(up_only)\nprint(head(up_only[, c(\"target_gene\", \"logfc_mean\", \"consistency_score\")], 5))\n\n# Only downregulated targets (genes METTL3 normally activates)\ndown_only <- gpdb_find_targets(\n  \"METTL3\",\n  direction = \"down\",\n  top_n = 30\n)\n\ncat(\"\\nDownregulated targets:\\n\")\nprint(head(down_only[, c(\"target_gene\", \"logfc_mean\", \"consistency_score\")], 5))\n\n# ===========================================================================\n# Example 5: Combined Filtering (High confidence + Strong effects)\n# ===========================================================================\n# Most stringent filtering for high-quality target list\n\nresult_stringent <- gpdb_find_targets(\n  \"TP53\",\n  min_confidence = \"high\", # 5+ datasets\n  min_effect_size = 1.5, # >2.8-fold change\n  top_n = 20\n)\n\ncat(\"Stringent filtering results:\\n\")\ncat(\n  \"Targets:\", nrow(result_stringent$upregulated), \"up,\",\n  nrow(result_stringent$downregulated), \"down\\n\"\n)\n\n# These are the most reliable targets for follow-up experiments\ncat(\"\\nTop stringent upregulated targets:\\n\")\nprint(result_stringent$upregulated[1:5, c(\"target_gene\", \"logfc_mean\", \"n_datasets\")])\n\n# Average consistency should be very high\ncat(\n  \"Average consistency (upregulated):\",\n  mean(result_stringent$upregulated$consistency_score), \"\\n\"\n)\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# For complete workflows, see:\n# - Enrichment analysis: ?gpdb_enrich\n# - Network visualization: ?gpdb_plot_network\n# - Cascade analysis: ?gpdb_analyze_cascade\n# - Compare genes: ?gpdb_compare_genes\n# - Load raw data: ?gpdb_load_data\n## End(No test)\n\n\n\n",
    "return_value": "When direction=\"both\" (default), returns list with three elements. When direction=\"up\" or direction=\"down\" , returns single data.frame. **Return Structure (direction=\"both\")**: result$upregulated Data.frame of genes increased by perturbation (knockdown/knockout causes upregulation), suggesting normally repressed targets target_gene : Affected gene symbol logfc_mean : Average log2 fold change (positive values) logfc_sd : Standard deviation of logFC across datasets n_datasets : Number of independent experiments consistency_score : Fraction showing same direction (0.5-1.0) effect_size : Classification (small/medium/large) confidence : Evidence strength (high/medium/low) tissues : Tissue types where observed celllines : Cell lines where observed direction : \"up\" result$downregulated Data.frame of genes decreased by perturbation (knockdown/knockout causes downregulation), suggesting normally activated targets. Same column structure as upregulated. result$summary Natural language text summary (LLM-friendly format) **Programmatic Access Examples**: Get top 10 upregulated: head(result$upregulated, 10) Filter high confidence: result$upregulated[result$upregulated$confidence == \"high\", ] Filter strong effects: result$upregulated[result$upregulated$logfc_mean > 1.5, ] Get target names: result$upregulated$target_gene Combined targets: c(result$upregulated$target_gene, result$downregulated$target_gene) **What You Can Do Next**: Enrichment analysis: gpdb_enrich (result$upregulated$target_gene, enrich.type = \"GO\") Network visualization: gpdb_plot_network (gene, top_targets = 50) Cascade analysis: gpdb_analyze_cascade (gene, steps = 2) Compare with other genes: gpdb_compare_genes (c(gene, \"GENE2\")) Load raw data: gpdb_list_datasets (gene = gene) then gpdb_load_data (dataset_id) **Alternative Methods**: gpdb_what_happens : Use when you want ALL targets without filtering. Returns complete unfiltered dataset (thousands of targets) vs find_targets (top N filtered). gpdb_find_regulators : Use when you want UPSTREAM regulators instead of downstream targets (reverse direction: who controls X?). gpdb_predict_targets : Use when you have a DISEASE SIGNATURE and want to predict therapeutic targets (drug repurposing) vs find_targets (single gene perturbation).",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "gene: Character. Gene symbol to query (e.g., \"TP53\", \"METTL3\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended.\ndirection: Character. Target direction filter (default \"both\"): \"both\": Return both upregulated and downregulated targets (returns list) \"up\": Only genes increased by perturbation (returns data.frame) \"down\": Only genes decreased by perturbation (returns data.frame)\ntop_n: Integer. Maximum targets per direction to return (default 50). Targets are ranked by effect size (|logFC|). Larger values provide comprehensive results. Recommended: 50 (focused), 100 (exploratory), or use gpdb_what_happens () for complete unfiltered data.\nmin_confidence: Character. Evidence strength filter (default \"medium\"): \"high\": 5+ datasets, >80 % consistency (most reliable, publication-grade) \"medium\": 2-4 datasets, >70 % consistency (balanced, standard analysis) \"low\": 1 dataset (exploratory, requires validation) Higher confidence reduces false positives but may miss context-specific effects.\nmin_effect_size: Numeric. Minimum absolute log2 fold change threshold (default 0.5). Filters targets by biological significance. Recommended: 0.5 (all significant), 1.0 (moderate effects), 1.5 (strong effects, >2.8-fold change). Higher thresholds focus on major regulatory relationships.",
    "simple_arguments": "gene: Character. Gene symbol to query (e.g., \"TP53\", \"METTL3\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended."
  },
  "gpdb_get_info": {
    "package": "GenePerturbR",
    "function_name": "gpdb_get_info",
    "title": "Get Detailed Dataset Metadata",
    "description": "Query comprehensive metadata for a specific dataset from the GenePerturbR database. Returns experimental details including gene, perturbation method, cell line, tissue type, sample size, and data source for validation before loading raw data. Database contains 7,665 perturbation experiments with standardized metadata across 2,810 genes, 1,063 cell lines, and 71 tissue types.",
    "user_queries": ["How do I check dataset details before loading raw data?", "What information is available for each perturbation experiment?", "How do I verify the cell line and tissue type for a dataset?", "What perturbation methods are used in the database?", "How many samples does my dataset have?", "Where can I find the original publication for a dataset?", "How do I check if a dataset uses CRISPR or RNAi?", "What's the difference between gene symbol and Ensembl ID?", "Can I filter datasets by experimental method before analysis?", "How do I validate dataset quality before loading expression data?", "What metadata is needed for reproducible analysis?", "How do I trace data provenance back to GEO/SRA?", "Can I check tissue type distribution for my gene of interest?", "What cell lines are most commonly used for my gene?", "How do I verify dataset ID format before querying?", "Is there a way to batch check metadata for multiple datasets?", "What information do I need to cite a dataset in my paper?", "How do I identify protein-coding vs non-coding gene perturbations?", "Can I check sample size adequacy before differential expression?", "What's included in the metadata compared to raw data loading?"],
    "usage": "gpdb_get_info(dataset_id)",
    "parameters": [
      {
        "name": "dataset_id",
        "has_default": false,
        "description": "Character. Unique dataset identifier (e.g., \"D10001\", \"D28200\"). Obtain valid IDs using gpdb_list_datasets() . Function validates ID format and checks database existence before query."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage - Get Dataset Metadata (TESTED - runtime: 0.001 sec)\n# ===========================================================================\n# Scientific Question: What are the experimental details for a specific dataset?\n# Expected output: List with 10 metadata fields (gene, method, cell line, tissue, etc.)\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Get detailed information for dataset D28200\ninfo <- gpdb_get_info(\"D28200\")\n\n# View complete metadata\nstr(info)\n\n# Access specific fields\ncat(\"Gene:\", info$gene, \"\\n\")\ncat(\"Cell line:\", info$cell_line, \"\\n\")\ncat(\"Tissue:\", info$tissue, \"\\n\")\ncat(\"Method:\", info$method, \"\\n\")\ncat(\"Samples:\", info$n_samples, \"\\n\")\ncat(\"Accession:\", info$accession, \"\\n\")\n\n# ===========================================================================\n# Example 2: Workflow - Find → Verify → Load Data\n# ===========================================================================\n# Systematic approach: Search datasets → Check metadata → Load expression\n\n# Step 1: Find datasets for gene of interest\ndatasets <- gpdb_list_datasets(gene = \"TP53\", cell_line = \"PANC-1\")\ncat(\"Found\", nrow(datasets), \"datasets\\n\")\n\n# Step 2: Check metadata for first dataset\nif (nrow(datasets) > 0) {\n  dataset_id <- datasets$dataset_id[1]\n  info <- gpdb_get_info(dataset_id)\n\n  # Verify experimental conditions\n  cat(\"\\n=== Dataset Verification ===\\n\")\n  cat(\"Dataset:\", info$dataset_id, \"\\n\")\n  cat(\"Gene:\", info$gene, \"(\", info$ensembl_id, \")\\n\")\n  cat(\"Biotype:\", info$gene_biotype, \"\\n\")\n  cat(\"Method:\", info$method, \"\\n\")\n  cat(\"Cell line:\", info$cell_line, \"\\n\")\n  cat(\"Tissue:\", info$tissue, \"\\n\")\n  cat(\"Samples:\", info$n_samples, \"\\n\")\n  cat(\"Source:\", info$Datasource, \"-\", info$accession, \"\\n\")\n\n  # Step 3: Decide whether to load based on metadata\n  if (info$method %in% c(\"knockout\", \"siRNA\", \"shRNA\") && info$n_samples >= 6) {\n    cat(\"\\n✓ Dataset meets quality criteria - proceed to load\\n\")\n    # data <- gpdb_load_data(dataset_id)\n  }\n}\n\n# ===========================================================================\n# Example 3: Filter by Perturbation Method\n# ===========================================================================\n# Compare CRISPR vs RNAi experiments for same gene\n\n# Get all TP53 datasets\nall_datasets <- gpdb_list_datasets(gene = \"TP53\")\n\n# Check methods for each dataset\nmethods_summary <- data.frame(\n  dataset_id = character(),\n  method = character(),\n  cell_line = character(),\n  n_samples = integer(),\n  stringsAsFactors = FALSE\n)\n\nfor (i in 1:min(5, nrow(all_datasets))) {\n  info <- gpdb_get_info(all_datasets$dataset_id[i])\n  methods_summary <- rbind(methods_summary, data.frame(\n    dataset_id = info$dataset_id,\n    method = info$method,\n    cell_line = info$cell_line,\n    n_samples = info$n_samples\n  ))\n}\n\n# Compare experimental approaches\ncat(\"\\n=== TP53 Perturbation Methods ===\\n\")\nprint(methods_summary)\ncat(\"\\nMethod distribution:\\n\")\nprint(table(methods_summary$method))\n\n# ===========================================================================\n# Example 4: Data Provenance Tracing\n# ===========================================================================\n# Extract accession IDs for literature citation\n\n# Get metadata for multiple datasets\ntarget_datasets <- all_datasets$dataset_id[1:3]\naccessions <- sapply(target_datasets, function(id) {\n  info <- gpdb_get_info(id)\n  paste0(info$Datasource, \": \", info$accession)\n})\n\ncat(\"\\n=== Data Provenance ===\\n\")\nfor (i in seq_along(accessions)) {\n  cat(target_datasets[i], \"→\", accessions[i], \"\\n\")\n}\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# After verifying metadata, proceed to:\n# - Load data: ?gpdb_load_data (expression matrix + sample metadata)\n# - Load DEG: ?gpdb_load_deg (pre-computed differential expression)\n# - Batch load: ?gpdb_load_batch (multiple datasets with progress)\n# - Visualize: ?gpdb_plot_volcano (DEG visualization)\n## End(No test)\n\n\n\n",
    "return_value": "List with 10 metadata elements: dataset_id Unique identifier for the experiment gene Perturbed gene symbol (e.g., \"TP53\", \"MYC\") ensembl_id Ensembl gene ID (e.g., \"ENSG00000141510\") gene_biotype Gene type (e.g., \"protein_coding\", \"lncRNA\") method Perturbation approach: \"knockout\", \"siRNA\", \"shRNA\", \"CRISPRi\", \"mutation\", \"inhibit\" (chemical inhibition) n_samples Total samples in experiment (treatment + control) cell_line Cell line name (e.g., \"HeLa\", \"A549\", \"K562\") tissue Tissue origin (e.g., \"Lung\", \"Blood\", \"Pancreas\") Datasource Repository: \"GEO\", \"SRA\", \"ArrayExpress\" accession Public accession ID (e.g., \"GSE123456\") **What You Can Do Next**: Load raw data: gpdb_load_data(dataset_id) - Get expression matrix + metadata Load DEG results: gpdb_load_deg(dataset_id) - Pre-computed differential expression Check experimental design: Verify cell_line and method match your research question Batch processing: Use metadata to filter datasets before batch loading Trace data provenance: Use accession to access original publication/data **Alternative Methods**: gpdb_list_datasets : Search datasets by gene/cell line/tissue. Use when: Need to find dataset IDs matching specific criteria. gpdb_load_data : Load expression data with auto-included metadata. Use when: Ready to analyze data (includes gpdb_get_info results in $info).",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "dataset_id: Character. Unique dataset identifier (e.g., \"D10001\", \"D28200\"). Obtain valid IDs using gpdb_list_datasets() . Function validates ID format and checks database existence before query.",
    "simple_arguments": "dataset_id: Character. Unique dataset identifier (e.g., \"D10001\", \"D28200\"). Obtain valid IDs using gpdb_list_datasets() . Function validates ID format and checks database existence before query."
  },
  "gpdb_list_datasets": {
    "package": "GenePerturbR",
    "function_name": "gpdb_list_datasets",
    "title": "Query Available Perturbation Datasets with Filtering",
    "description": "Search and filter perturbation experiments from GenePerturbR database containing 7,665 RNA-seq datasets across 2,810 genes, 1,063 cell lines, and 71 tissue types. **Database includes knockout, siRNA, shRNA, CRISPRi, and chemical inhibition experiments**. Returns metadata for datasets matching specified criteria, enabling targeted data loading and exploratory analysis.",
    "user_queries": ["How many datasets are available for my gene of interest?", "Which cell lines have been used to study TP53 knockout?", "Are there any lung cancer datasets with MYC perturbation?", "What perturbation methods are available for my gene?", "Can I find CRISPR knockout experiments in a specific tissue?", "How do I filter datasets by experimental method and cell type?", "Which datasets should I load for downstream DEG analysis?", "Are there datasets with large sample sizes for robust statistics?", "How do I explore all available genes in the database?", "Can I query datasets by accession number or data source?", "What is the tissue distribution for perturbation experiments?", "How many cell lines are represented in the database?", "Can I find experiments using specific siRNA or shRNA methods?", "How do I identify datasets suitable for meta-analysis?", "What information is included in the dataset metadata?", "Can I filter by both gene and cell line simultaneously?", "How do I find datasets for pathway members or gene families?", "Are there datasets with chemical inhibition experiments?", "What is the distribution of knockout vs knockdown experiments?", "How do I select representative datasets for validation studies?"],
    "usage": "gpdb_list_datasets( gene = NULL, cell_line = NULL, tissue = NULL, method = NULL, min_quality = NULL, quality_tier = NULL )",
    "parameters": [
      {
        "name": "gene",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character. Gene symbol to query (e.g., \"TP53\", \"MYC\"). Default: NULL (all genes). Case-insensitive but uppercase recommended. Use gpdb_search() to find available genes or check aliases."
      },
      {
        "name": "cell_line",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character. Cell line name to filter (e.g., \"A549\", \"HeLa\"). Default: NULL (all cell lines). Exact match required. Check available cell lines with gpdb_list_datasets()$cell_line ."
      },
      {
        "name": "tissue",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character. Tissue type to filter (e.g., \"Lung\", \"Liver\", \"Brain\"). Default: NULL (all tissues). Exact match required. Database covers 71 tissue types including cancer and normal tissues."
      },
      {
        "name": "method",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character. Perturbation method to filter. Default: NULL (all methods). Options: \"knockout\", \"siRNA\", \"shRNA\", \"CRISPRi\", \"inhibit\" (chemical inhibition), \"mutation\". Method distribution: siRNA (2,371), shRNA (2,848), knockout (2,192)."
      },
      {
        "name": "min_quality",
        "has_default": true,
        "default_value": "NULL",
        "description": "Numeric. Reserved for future quality scoring system (not currently implemented). Current workaround: Filter by n_samples after querying (e.g., result[result$n_samples >= 6, ] )."
      },
      {
        "name": "quality_tier",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character. Reserved for future quality tier classification (not currently implemented). Current approach: All datasets undergo standardized QC and are analysis-ready."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage - Query datasets for specific gene (TESTED - 0.017 sec)\n# ===========================================================================\n# Scientific Question: What datasets are available for TP53 perturbation?\n# Expected output: Data.frame with 71 datasets across 39 cell lines and 23 tissues\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Query all TP53 datasets\ntp53_datasets <- gpdb_list_datasets(gene = \"TP53\")\n\n# Verify output structure\ncat(\"Found\", nrow(tp53_datasets), \"datasets\\n\")\nhead(tp53_datasets)\n\n# Explore dataset distribution\ntable(tp53_datasets$method) # Perturbation methods\ntable(tp53_datasets$tissue) # Tissue types\nlength(unique(tp53_datasets$cell_line)) # Number of cell lines\n\n# ===========================================================================\n# Example 2: Context-Specific Filtering - Cell line and tissue\n# ===========================================================================\n# Scientific Question: Are there TP53 datasets specifically in A549 lung cancer cells?\n\n# Filter by cell line\ntp53_a549 <- gpdb_list_datasets(\n  gene = \"TP53\",\n  cell_line = \"A549\"\n)\ncat(\"TP53 in A549:\", nrow(tp53_a549), \"datasets\\n\")\n\n# Filter by tissue (all lung cell lines)\ntp53_lung <- gpdb_list_datasets(\n  gene = \"TP53\",\n  tissue = \"Lung\"\n)\ncat(\"TP53 in Lung tissue:\", nrow(tp53_lung), \"datasets\\n\")\nprint(unique(tp53_lung$cell_line)) # Show all lung cell lines\n\n# ===========================================================================\n# Example 3: Method-Specific Queries - Compare perturbation approaches\n# ===========================================================================\n# Scientific Question: How many datasets use genetic knockout vs RNAi knockdown?\n\n# Genetic knockout (permanent deletion)\nmyc_knockout <- gpdb_list_datasets(\n  gene = \"MYC\",\n  method = \"knockout\"\n)\n\n# siRNA knockdown (transient suppression)\nmyc_sirna <- gpdb_list_datasets(\n  gene = \"MYC\",\n  method = \"siRNA\"\n)\n\n# Compare results\ncat(\"MYC knockout:\", nrow(myc_knockout), \"datasets\\n\")\ncat(\"MYC siRNA:\", nrow(myc_sirna), \"datasets\\n\")\n\n# ===========================================================================\n# Example 4: Exploratory Analysis - Database coverage\n# ===========================================================================\n# Scientific Question: What is the overall scope of the database?\n\n# Query all datasets (no filters)\nall_datasets <- gpdb_list_datasets()\n\n# Summary statistics\ncat(\"Total datasets:\", nrow(all_datasets), \"\\n\")\ncat(\"Unique genes:\", length(unique(all_datasets$gene)), \"\\n\")\ncat(\"Unique cell lines:\", length(unique(all_datasets$cell_line)), \"\\n\")\ncat(\"Unique tissues:\", length(unique(all_datasets$tissue)), \"\\n\")\n\n# Method distribution\nprint(table(all_datasets$method))\n\n# Top 10 most studied genes\ngene_counts <- sort(table(all_datasets$gene), decreasing = TRUE)\nprint(head(gene_counts, 10))\n\n# ===========================================================================\n# Example 5: Select Datasets for Loading - Quality filtering\n# ===========================================================================\n# Scientific Question: Which TP53 datasets have sufficient sample size for DEG analysis?\n\n# Get TP53 datasets\ntp53_all <- gpdb_list_datasets(gene = \"TP53\")\n\n# Filter by sample size (at least 6 samples = 3 treatment + 3 control)\ntp53_robust <- tp53_all[tp53_all$n_samples >= 6, ]\ncat(\"Robust datasets (n>=6):\", nrow(tp53_robust), \"\\n\")\n\n# Select top 5 for detailed analysis\nselected_ids <- head(tp53_robust$dataset_id, 5)\n\n# Preview what you'll load\ncat(\"Selected datasets:\\n\")\nprint(tp53_robust[1:5, c(\"dataset_id\", \"cell_line\", \"tissue\", \"method\", \"n_samples\")])\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# After identifying relevant datasets:\n# 1. Load data: gpdb_load_data(selected_ids[1])\n# 2. Batch load: gpdb_load_batch(selected_ids, type = \"deg\")\n# 3. Get metadata: gpdb_get_info(selected_ids[1])\n# 4. Aggregated effects: gpdb_what_happens(\"TP53\")\n# 5. Find targets: gpdb_find_targets(\"TP53\", min_confidence = \"high\")\n## End(No test)\n\n\n",
    "return_value": "Data.frame with dataset metadata. Returns empty data.frame if no matches found. **Return Structure** (10 columns): dataset_id Unique dataset identifier (e.g., \"D28200\"). Use with gpdb_load_data() to load expression data. gene Perturbed gene symbol (e.g., \"TP53\") ensembl_id Ensembl gene ID (e.g., \"ENSG00000141510\") gene_biotype Gene type (usually \"protein_coding\") method Perturbation method (knockout/siRNA/shRNA/CRISPRi/inhibit/mutation) n_samples Number of samples in dataset (treatment + control) cell_line Cell line name (e.g., \"A549\", \"HeLa\") tissue Tissue type (e.g., \"Lung\", \"Liver\") Datasource Data repository (e.g., \"SRA\", \"GEO\") accession Accession number (e.g., \"GSE291033\") **What You Can Do Next**: Load expression data: gpdb_load_data(result$dataset_id[1]) Load DEG results: gpdb_load_deg(result$dataset_id[1]) Batch load multiple datasets: gpdb_load_batch(result$dataset_id[1:10]) Get detailed metadata: gpdb_get_info(result$dataset_id[1]) Explore dataset distribution: table(result$method) , table(result$tissue) **Alternative Methods**: gpdb_search : Find genes by symbol or alias. Use when: Need to verify gene name before querying datasets. gpdb_get_info : Get detailed info for single dataset. Use when: Already have dataset ID and need metadata. gpdb_what_happens : Query aggregated effects of perturbation. Use when: Want biological insights rather than individual datasets.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "gene: Character. Gene symbol to query (e.g., \"TP53\", \"MYC\"). Default: NULL (all genes). Case-insensitive but uppercase recommended. Use gpdb_search() to find available genes or check aliases.\ncell_line: Character. Cell line name to filter (e.g., \"A549\", \"HeLa\"). Default: NULL (all cell lines). Exact match required. Check available cell lines with gpdb_list_datasets()$cell_line .\ntissue: Character. Tissue type to filter (e.g., \"Lung\", \"Liver\", \"Brain\"). Default: NULL (all tissues). Exact match required. Database covers 71 tissue types including cancer and normal tissues.\nmethod: Character. Perturbation method to filter. Default: NULL (all methods). Options: \"knockout\", \"siRNA\", \"shRNA\", \"CRISPRi\", \"inhibit\" (chemical inhibition), \"mutation\". Method distribution: siRNA (2,371), shRNA (2,848), knockout (2,192).\nmin_quality: Numeric. Reserved for future quality scoring system (not currently implemented). Current workaround: Filter by n_samples after querying (e.g., result[result$n_samples >= 6, ] ).\nquality_tier: Character. Reserved for future quality tier classification (not currently implemented). Current approach: All datasets undergo standardized QC and are analysis-ready.",
    "simple_arguments": ""
  },
  "gpdb_load_batch": {
    "package": "GenePerturbR",
    "function_name": "gpdb_load_batch",
    "title": "Batch Load Multiple Datasets with Progress Tracking",
    "description": "Load expression data, DEG results, or metadata for multiple datasets in a single call. Returns named list with results for each dataset, enabling systematic comparison across perturbation experiments. **Includes progress bar, error handling, and optimized loading** for meta-analysis workflows. Database contains 7,665 datasets covering 2,810 genes, allowing batch queries for cross-dataset analysis and validation studies.",
    "user_queries": ["How do I load multiple datasets at once for comparison?", "Can I batch load DEG results for the same gene across different cell lines?", "What is the fastest way to load metadata for many datasets?", "How do I handle errors when some datasets fail to load?", "Can I see progress when loading multiple datasets?", "What's the difference between batch loading and individual loading?", "How long does it take to batch load 10 datasets?", "Can I pass additional parameters to the batch loading function?", "How do I access individual datasets from batch results?", "What format does batch loading return?", "Can I batch load expression data for meta-analysis?", "How do I compare DEG results across multiple experiments?", "What if I want to filter DEG results during batch loading?", "Can I normalize expression data during batch loading?", "How do I batch load datasets for the same gene in different tissues?", "What's the memory usage for batch loading many datasets?", "Can I turn off the progress bar for scripting?", "How do I identify which datasets failed to load?", "Can I batch load a mix of different dataset types?", "What's the recommended batch size for efficient loading?"],
    "usage": "gpdb_load_batch( dataset_ids, type = c(\"data\", \"deg\", \"metadata\"), show_progress = TRUE, ... )",
    "parameters": [
      {
        "name": "dataset_ids",
        "has_default": false,
        "description": "Character vector. Dataset IDs to load (e.g., c(\"D28200\", \"D28199\", \"D27994\") ). Obtain valid IDs using gpdb_list_datasets . Function validates each ID format and handles errors gracefully (failed loads don't stop batch processing)."
      },
      {
        "name": "type",
        "has_default": true,
        "default_value": "c(\"data\", \"deg\", \"metadata\")",
        "description": "Character. Data type to load (default: \"data\"). Options: \"data\" (expression matrix + metadata, ~0.3 sec per dataset), \"deg\" (pre-computed differential expression, ~0.02 sec per dataset), \"metadata\" (sample metadata only, ~0.001 sec per dataset). Choose based on analysis needs: \"deg\" for quick comparison, \"data\" for custom re-analysis."
      },
      {
        "name": "show_progress",
        "has_default": true,
        "default_value": "TRUE",
        "description": "Logical. Display progress bar during loading (default: TRUE ). Set FALSE to suppress progress output (useful in non-interactive scripts). Progress bar shows: current/total datasets, elapsed time, estimated remaining time."
      },
      {
        "name": "...",
        "has_default": false,
        "description": "Additional arguments passed to underlying load functions ( gpdb_load_data , gpdb_load_deg , or gpdb_load_metadata ). For example: normalize=TRUE for gpdb_load_data, filter=TRUE for gpdb_load_deg."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Batch Load DEG Results (TESTED - runtime: 0.073 sec for 3 datasets)\n# ===========================================================================\n# Scientific Question: Compare differential expression across multiple TP53 experiments\n# Expected output: Named list of data.frames with DEG results\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Find TP53 datasets\ntp53_datasets <- gpdb_list_datasets(gene = \"TP53\")\nselected_ids <- head(tp53_datasets$dataset_id, 3)\n\n# Batch load DEG results with progress bar\nbatch_deg <- gpdb_load_batch(\n  dataset_ids = selected_ids,\n  type = \"deg\",\n  show_progress = TRUE\n)\n\n# Check structure\ncat(\"Loaded\", length(batch_deg), \"datasets\\n\")\nnames(batch_deg) # Dataset IDs\n\n# Access individual results\ndeg1 <- batch_deg[[\"D28200\"]]\ncat(\"Dataset D28200:\", nrow(deg1), \"genes\\n\")\n\n# ===========================================================================\n# Example 2: Compare Significant Genes Across Datasets\n# ===========================================================================\n# Count significant genes in each dataset\n\nsig_counts <- sapply(batch_deg, function(deg) {\n  sum(deg$adj.P.Val < 0.05 & abs(deg$logFC) > 1, na.rm = TRUE)\n})\n\ncat(\"=== Significant Genes per Dataset ===\\n\")\nprint(sig_counts)\n\n# Get cell line info for each dataset\ncell_lines <- sapply(names(batch_deg), function(id) {\n  gpdb_get_info(id)$cell_line\n})\n\n# Create comparison table\ncomparison <- data.frame(\n  dataset_id = names(batch_deg),\n  cell_line = cell_lines,\n  sig_genes = sig_counts\n)\nprint(comparison)\n\n# ===========================================================================\n# Example 3: Batch Load with Filtering (Pass parameters via ...)\n# ===========================================================================\n# Load only significant genes to save memory\n\n# Batch load with filter=TRUE passed to gpdb_load_deg\nbatch_sig <- gpdb_load_batch(\n  dataset_ids = selected_ids,\n  type = \"deg\",\n  filter = TRUE, # Passed to gpdb_load_deg\n  padj_cutoff = 0.05, # Passed to gpdb_load_deg\n  logfc_cutoff = 1.0, # Passed to gpdb_load_deg\n  show_progress = FALSE\n)\n\n# Check filtered results\ncat(\"Filtered gene counts:\\n\")\nprint(sapply(batch_sig, nrow))\n\n# ===========================================================================\n# Example 4: Batch Load Metadata - Quick Experimental Design Check\n# ===========================================================================\n# Check sample balance across multiple datasets\n\n# Batch load metadata (fastest)\nbatch_meta <- gpdb_load_batch(\n  dataset_ids = head(tp53_datasets$dataset_id, 5),\n  type = \"metadata\",\n  show_progress = TRUE\n)\n\n# Check sample balance for each dataset\ncat(\"=== Sample Balance per Dataset ===\\n\")\nfor (id in names(batch_meta)) {\n  groups <- table(batch_meta[[id]]$group)\n  cat(id, \":\", paste(names(groups), \"=\", groups, collapse = \", \"), \"\\n\")\n}\n\n# Compare perturbation methods\nmethods <- sapply(batch_meta, function(m) unique(m$method)[1])\ncat(\"\\n=== Perturbation Methods ===\\n\")\nprint(table(methods))\n\n# ===========================================================================\n# Example 5: Batch Load Expression Data - Meta-Analysis\n# ===========================================================================\n# Load raw counts for multiple datasets (slower but complete)\n\n# Batch load expression data\nbatch_data <- gpdb_load_batch(\n  dataset_ids = head(tp53_datasets$dataset_id, 2),\n  type = \"data\",\n  normalize = FALSE, # Keep raw counts for DESeq2\n  show_progress = TRUE\n)\n\n# Check expression dimensions\ncat(\"=== Expression Matrix Dimensions ===\\n\")\nfor (id in names(batch_data)) {\n  expr <- batch_data[[id]]$expression\n  cat(id, \":\", nrow(expr), \"genes ×\", ncol(expr), \"samples\\n\")\n}\n\n# Extract common genes across datasets\ngene_lists <- lapply(batch_data, function(x) rownames(x$expression))\ncommon_genes <- Reduce(intersect, gene_lists)\ncat(\"\\nCommon genes across all datasets:\", length(common_genes), \"\\n\")\n\n# ===========================================================================\n# Example 6: Extract Consensus Signals Across Datasets\n# ===========================================================================\n# Find genes consistently changed across multiple experiments\n\n# Load DEG for multiple datasets\nbatch_deg <- gpdb_load_batch(\n  dataset_ids = head(tp53_datasets$dataset_id, 5),\n  type = \"deg\",\n  show_progress = FALSE\n)\n\n# For each gene, count how many datasets show significance\nall_genes <- unique(unlist(lapply(batch_deg, function(x) x$gene)))\nall_genes <- all_genes[all_genes != \"\" & !is.na(all_genes)]\n\nconsensus_table <- data.frame(\n  gene = character(),\n  n_sig_datasets = integer(),\n  mean_logfc = numeric(),\n  stringsAsFactors = FALSE\n)\n\n# Example: Check TP53 target genes\ntarget_genes <- c(\"CDKN1A\", \"MDM2\", \"BAX\", \"PUMA\", \"GADD45A\")\n\nfor (gene in target_genes) {\n  sig_count <- sum(sapply(batch_deg, function(deg) {\n    gene_row <- deg[deg$gene == gene, ]\n    if (nrow(gene_row) > 0) {\n      return(gene_row$adj.P.Val[1] < 0.05 & abs(gene_row$logFC[1]) > 1)\n    }\n    return(FALSE)\n  }))\n\n  mean_fc <- mean(sapply(batch_deg, function(deg) {\n    gene_row <- deg[deg$gene == gene, ]\n    if (nrow(gene_row) > 0) {\n      return(gene_row$logFC[1])\n    }\n    return(NA)\n  }), na.rm = TRUE)\n\n  cat(\n    gene, \": significant in\", sig_count, \"/\", length(batch_deg),\n    \"datasets, mean logFC =\", round(mean_fc, 2), \"\\n\"\n  )\n}\n\n# ===========================================================================\n# Example 7: Error Handling - Robust Batch Loading\n# ===========================================================================\n# Batch loading continues even if some datasets fail\n\n# Mix valid and invalid IDs\nmixed_ids <- c(\"D28200\", \"INVALID\", \"D28199\", \"D27994\")\n\n# Batch load (warnings for failed IDs, but continues)\nbatch_result <- gpdb_load_batch(\n  dataset_ids = mixed_ids,\n  type = \"deg\",\n  show_progress = FALSE\n)\n\ncat(\"Requested:\", length(mixed_ids), \"datasets\\n\")\ncat(\"Successfully loaded:\", length(batch_result), \"datasets\\n\")\ncat(\"Success rate:\", round(length(batch_result) / length(mixed_ids) * 100, 1), \"%\\n\")\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# After batch loading, proceed to:\n# - Compare results: lapply() to extract metrics across datasets\n# - Visualize: Plot significant gene counts, effect size distributions\n# - Consensus analysis: Find genes changed in ≥N datasets\n# - Export: write.csv() or save() batch results for reporting\n# - Integrate: Use with gpdb_compare_genes() or gpdb_enrich()\n## End(No test)\n\n\n\n",
    "return_value": "Named list where each element corresponds to a loaded dataset: **Return Structure** (depends on type parameter): When type=\"data\" Named list of lists, each containing: $expression : Data.frame (genes × samples, ~30K genes) $metadata : Data.frame (samples × 11 columns) $info : List (14 metadata fields) Names: dataset_ids (e.g., \"D28200\", \"D28199\", \"D27994\") When type=\"deg\" Named list of data.frames, each containing: Data.frame (genes × 7 columns: gene_id, AveExpr, logFC, lfcSE, P.Value, adj.P.Val, gene) ~30K genes per dataset (or fewer if filter=TRUE passed via ...) Names: dataset_ids When type=\"metadata\" Named list of data.frames, each containing: Data.frame (samples × 11 columns: GSE, GSM, gene, method, celline, group, etc.) 4-12 samples per dataset Names: dataset_ids **What You Can Do Next**: Compare DEG across datasets: lapply(batch_deg, function(x) sum(x$adj.P.Val < 0.05)) Extract specific genes: lapply(batch_deg, function(x) x[x$gene == \"MYC\", ]) Meta-analysis: Combine results across datasets for consensus signals Visualize comparison: Plot significant gene counts, effect sizes across datasets Quality check: Compare library sizes, sample counts, methods across experiments Export results: Save batch results for downstream analysis or reporting **Alternative Methods**: gpdb_load_data , gpdb_load_deg , gpdb_load_metadata : Load single dataset. Use when: Only need one dataset or want to process individually. gpdb_find_targets : Query aggregated targets across all datasets. Use when: Want consensus targets from multiple experiments, not individual dataset results. gpdb_compare_genes : Compare perturbation effects between genes. Use when: Systematic comparison already implemented with built-in statistics.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "dataset_ids: Character vector. Dataset IDs to load (e.g., c(\"D28200\", \"D28199\", \"D27994\") ). Obtain valid IDs using gpdb_list_datasets . Function validates each ID format and handles errors gracefully (failed loads don't stop batch processing).\ntype: Character. Data type to load (default: \"data\"). Options: \"data\" (expression matrix + metadata, ~0.3 sec per dataset), \"deg\" (pre-computed differential expression, ~0.02 sec per dataset), \"metadata\" (sample metadata only, ~0.001 sec per dataset). Choose based on analysis needs: \"deg\" for quick comparison, \"data\" for custom re-analysis.\nshow_progress: Logical. Display progress bar during loading (default: TRUE ). Set FALSE to suppress progress output (useful in non-interactive scripts). Progress bar shows: current/total datasets, elapsed time, estimated remaining time.\n...: Additional arguments passed to underlying load functions ( gpdb_load_data , gpdb_load_deg , or gpdb_load_metadata ). For example: normalize=TRUE for gpdb_load_data, filter=TRUE for gpdb_load_deg.",
    "simple_arguments": "dataset_ids: Character vector. Dataset IDs to load (e.g., c(\"D28200\", \"D28199\", \"D27994\") ). Obtain valid IDs using gpdb_list_datasets . Function validates each ID format and handles errors gracefully (failed loads don't stop batch processing).\n...: Additional arguments passed to underlying load functions ( gpdb_load_data , gpdb_load_deg , or gpdb_load_metadata ). For example: normalize=TRUE for gpdb_load_data, filter=TRUE for gpdb_load_deg."
  },
  "gpdb_load_data": {
    "package": "GenePerturbR",
    "function_name": "gpdb_load_data",
    "title": "Load Expression Matrix and Sample Metadata from Dataset",
    "description": "Load complete gene expression data and sample metadata for a specific perturbation experiment. Returns pre-processed expression matrix with gene symbols as rownames, ready for differential expression analysis with DESeq2, edgeR, or limma. **Expression data stored as compressed .qs files** for fast loading (~0.2-0.6 seconds per dataset). Database contains 7,665 datasets covering 2,810 genes across 1,063 cell lines and 71 tissue types.",
    "user_queries": ["How do I load expression data for differential expression analysis?", "What format is the expression matrix (genes in rows or columns)?", "Should I use raw counts or normalized values for DESeq2?", "How do I access gene symbols from the expression matrix?", "What metadata is included with each dataset?", "How do I check if samples are balanced between control and treatment?", "Can I load expression data for custom DEG analysis?", "What is the typical size of an expression matrix?", "How long does it take to load a dataset?", "How do I match expression data with sample metadata?", "Can I load multiple datasets at once for meta-analysis?", "What's the difference between loading expression vs DEG results?", "How do I prepare loaded data for DESeq2 analysis?", "What file format is used to store expression data?", "How do I check data quality after loading?", "Can I normalize the expression data during loading?", "What information is in the info element of the result?", "How many genes are typically included in a dataset?", "What should I do if metadata is missing?", "How do I cite a dataset loaded from GenePerturbR?"],
    "usage": "gpdb_load_data(dataset_id, normalize = FALSE)",
    "parameters": [
      {
        "name": "dataset_id",
        "has_default": false,
        "description": "Character. Unique dataset identifier (e.g., \"D28200\", \"D10001\"). Obtain valid IDs using gpdb_list_datasets . Function validates ID format and checks file existence before loading. Each dataset contains ~30,000 genes."
      },
      {
        "name": "normalize",
        "has_default": true,
        "default_value": "FALSE",
        "description": "Logical. Apply log2(CPM+1) normalization to raw counts (default: FALSE ). Set TRUE for visualization or correlation analysis. Keep FALSE for differential expression (DESeq2/edgeR expect raw counts). Normalization adds ~0.1 sec."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage - Load Raw Counts (TESTED - runtime: 0.233 sec)\n# ===========================================================================\n# Scientific Question: Get expression data for custom differential expression analysis\n# Expected output: List with expression matrix (genes × samples), metadata, and info\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Load raw expression data (for DESeq2/edgeR)\ndata <- gpdb_load_data(\"D28200\", normalize = FALSE)\n\n# Verify structure\ncat(\"Dimensions:\", nrow(data$expression), \"genes ×\", ncol(data$expression), \"samples\\n\")\ncat(\"Groups:\", table(data$metadata$group), \"\\n\")\n\n# Check gene symbols\nhead(rownames(data$expression))\n# [1] \"A1BG\"     \"A1BG-AS1\" \"A1CF\"     \"A2M\"      \"A2M-AS1\"  \"A2ML1\"\n\n# Check value range (raw counts)\ncat(\"Expression range:\", min(data$expression), \"to\", max(data$expression), \"\\n\")\n\n# ===========================================================================\n# Example 2: DESeq2 Workflow - Differential Expression Analysis\n# ===========================================================================\n# Complete workflow: Load data → DESeq2 → Extract results\n\n# Load raw counts (required for DESeq2)\ndata <- gpdb_load_data(\"D28200\", normalize = FALSE)\n\n# Create DESeq2 object\nlibrary(DESeq2)\ndds <- DESeqDataSetFromMatrix(\n  countData = data$expression, # Genes × samples matrix\n  colData = data$metadata, # Sample metadata\n  design = ~group # Compare treatment vs control\n)\n\n# Run differential expression\ndds <- DESeq(dds)\nres <- results(dds)\n\n# Extract significant genes\nsig_genes <- subset(res, padj < 0.05 & abs(log2FoldChange) > 1)\ncat(\"Significant DEGs:\", nrow(sig_genes), \"\\n\")\n\n# ===========================================================================\n# Example 3: Load with Normalization - For Visualization\n# ===========================================================================\n# Use normalized data for heatmaps, PCA, correlation analysis\n\n# Load with log2(CPM+1) normalization\ndata_norm <- gpdb_load_data(\"D28200\", normalize = TRUE)\n\n# Check normalized value range\ncat(\n  \"Normalized range:\", round(min(data_norm$expression), 2), \"to\",\n  round(max(data_norm$expression), 2), \"\\n\"\n)\n# Expected: 0 to ~12-15 (log2 scale)\n\n# Use for heatmap visualization\ntop_genes <- head(order(rowMeans(data_norm$expression), decreasing = TRUE), 50)\nheatmap_data <- data_norm$expression[top_genes, ]\n\n# Plot heatmap\npheatmap::pheatmap(\n  heatmap_data,\n  annotation_col = data_norm$metadata[, \"group\", drop = FALSE],\n  scale = \"row\",\n  main = paste(data_norm$info$gene, \"perturbation in\", data_norm$info$cell_line)\n)\n\n# ===========================================================================\n# Example 4: Quality Check - Verify Data Before Analysis\n# ===========================================================================\n# Always check data quality after loading\n\ndata <- gpdb_load_data(\"D28200\")\n\n# Check 1: Sample balance\ncat(\"=== Sample Balance ===\\n\")\nprint(table(data$metadata$group))\n# Should be balanced: control = 3, treat = 3\n\n# Check 2: Library sizes\ncat(\"\\n=== Library Sizes ===\\n\")\nlib_sizes <- colSums(data$expression)\ncat(\"Range:\", min(lib_sizes), \"to\", max(lib_sizes), \"reads\\n\")\ncat(\"Mean:\", round(mean(lib_sizes)), \"reads\\n\")\n# Should be similar across samples (±30%)\n\n# Check 3: Gene detection\ncat(\"\\n=== Gene Detection ===\\n\")\ngenes_detected <- rowSums(data$expression > 0)\ncat(\"Genes detected in all samples:\", sum(genes_detected == ncol(data$expression)), \"\\n\")\ncat(\"Genes detected in ≥3 samples:\", sum(genes_detected >= 3), \"\\n\")\n\n# Check 4: Dataset info\ncat(\"\\n=== Dataset Info ===\\n\")\ncat(\"Gene:\", data$info$gene, \"\\n\")\ncat(\"Method:\", data$info$method, \"\\n\")\ncat(\"Cell line:\", data$info$cell_line, \"\\n\")\ncat(\"Tissue:\", data$info$tissue, \"\\n\")\ncat(\"Accession:\", data$info$accession, \"\\n\")\n\n# ===========================================================================\n# Example 5: Batch Loading - Compare Multiple Datasets\n# ===========================================================================\n# Load multiple datasets for same gene across cell lines\n\n# Find TP53 datasets\ntp53_datasets <- gpdb_list_datasets(gene = \"TP53\")\nselected_ids <- head(tp53_datasets$dataset_id, 3)\n\n# Batch load expression data\nbatch_data <- gpdb_load_batch(\n  dataset_ids = selected_ids,\n  type = \"data\",\n  show_progress = TRUE\n)\n\n# Compare library sizes across datasets\nfor (id in names(batch_data)) {\n  lib_size <- mean(colSums(batch_data[[id]]$expression))\n  cell_line <- batch_data[[id]]$info$cell_line\n  cat(id, \"-\", cell_line, \": \", round(lib_size / 1e6, 1), \"M reads\\n\")\n}\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# After loading data, proceed to:\n# - DESeq2 analysis: Use countData for differential expression\n# - Compare with pre-computed: gpdb_load_deg() for limma-voom results\n# - Visualize patterns: gpdb_plot_heatmap_expr() or custom plots\n# - Pathway analysis: Extract sig genes → gpdb_enrich()\n# - Meta-analysis: Batch load → combine results across datasets\n## End(No test)\n\n\n\n",
    "return_value": "List with 3 elements providing complete dataset: **Return Structure**: expression Data.frame of gene expression (genes × samples). Rownames: Gene symbols (e.g., \"TP53\", \"MYC\", \"GAPDH\") - 29,000-30,000 genes Columns: Sample IDs (e.g., \"GSM8827856\") - typically 4-12 samples per dataset Values: Raw read counts (if normalize=FALSE) or log2(CPM+1) (if normalize=TRUE) Missing genes: Removed during preprocessing (genes with zero counts across all samples) metadata Data.frame of sample-level annotations (samples × variables). Key column: group - \"control\" or \"treat\" (critical for DESeq2 design) Other columns (11 total): GSE, GSM, gene, method, celline, group_name, type, platform, SRR, paired Row count matches ncol(expression) - one row per sample info List with 14 metadata elements (from gpdb_get_info + computed stats). Dataset info: dataset_id, gene, ensembl_id, method, cell_line, tissue, accession Computed stats: n_genes, n_samples, sample_groups, expression_format Use for: Result reporting, method citation, quality check **What You Can Do Next**: Differential expression: DESeq2::DESeqDataSetFromMatrix(countData = data$expression, colData = data$metadata, design = ~group) Load DEG results: gpdb_load_deg (dataset_id) - Pre-computed limma-voom results Visualize expression: gpdb_plot_heatmap_expr (data$expression) Quality control: Check dimensions, groups, value ranges before analysis Batch processing: Use gpdb_load_batch for multiple datasets **Alternative Methods**: gpdb_load_deg : Load pre-computed differential expression results. Use when: Don't need raw counts, want ready-to-use DEG table (faster, ~0.04 sec). gpdb_load_metadata : Load sample metadata only. Use when: Need to check experimental design without loading large expression matrix. gpdb_load_batch : Batch load multiple datasets with progress tracking. Use when: Comparing effects across experiments or meta-analysis.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "dataset_id: Character. Unique dataset identifier (e.g., \"D28200\", \"D10001\"). Obtain valid IDs using gpdb_list_datasets . Function validates ID format and checks file existence before loading. Each dataset contains ~30,000 genes.\nnormalize: Logical. Apply log2(CPM+1) normalization to raw counts (default: FALSE ). Set TRUE for visualization or correlation analysis. Keep FALSE for differential expression (DESeq2/edgeR expect raw counts). Normalization adds ~0.1 sec.",
    "simple_arguments": "dataset_id: Character. Unique dataset identifier (e.g., \"D28200\", \"D10001\"). Obtain valid IDs using gpdb_list_datasets . Function validates ID format and checks file existence before loading. Each dataset contains ~30,000 genes."
  },
  "gpdb_load_deg": {
    "package": "GenePerturbR",
    "function_name": "gpdb_load_deg",
    "title": "Load Pre-Computed Differential Expression Results",
    "description": "Retrieve differential expression analysis results from the GenePerturbR database. Loads pre-computed DEG results (limma-voom pipeline) with optional filtering for significant genes. **DEG files contain ~30,000 genes per dataset** with logFC, p-values, and expression statistics.",
    "user_queries": ["How do I load differential expression results for a specific dataset?", "What genes are significantly changed in this perturbation experiment?", "Can I filter DEG results by fold-change and p-value thresholds?", "How do I find which genes are upregulated vs downregulated?", "What columns are included in the DEG results?", "How do I choose appropriate logFC and padj cutoffs?", "Can I load DEG results for multiple datasets at once?", "What is the difference between loading DEG vs raw expression data?", "How do I visualize the differential expression results?", "Can I compare DEG results across different cell lines or tissues?", "What statistical method was used to compute these DEG results?", "How do I filter for strongly affected genes only?", "Can I get DEG results for a specific gene across all datasets?", "What does the AveExpr column tell me about data quality?", "How many genes typically pass significance thresholds?", "Can I use these results for pathway enrichment analysis?", "What if some genes don't have gene symbols?", "How do I handle genes with missing adjusted p-values?"],
    "usage": "gpdb_load_deg(dataset_id, filter = FALSE, padj_cutoff = 0.05, logfc_cutoff = 0)",
    "parameters": [
      {
        "name": "dataset_id",
        "has_default": false,
        "description": "Character. Dataset ID (e.g., \"D28200\"). Use gpdb_list_datasets to find available datasets for your gene of interest."
      },
      {
        "name": "filter",
        "has_default": true,
        "default_value": "FALSE",
        "description": "Logical. Apply significance filters (default: FALSE , return all genes). Set TRUE to keep only significant genes passing"
      },
      {
        "name": "padj_cutoff",
        "has_default": true,
        "default_value": "0.05"
      },
      {
        "name": "logfc_cutoff",
        "has_default": true,
        "default_value": "0",
        "description": "Useful for focusing on biologically relevant changes. padj_cutoff Numeric. Adjusted p-value threshold (default: 0.05 ). Only used when filter = TRUE . Standard cutoff is 0.05 for FDR control; use 0.01 for stricter evidence. logfc_cutoff Numeric. Absolute log2 fold-change threshold (default: 0 ). Only used when filter = TRUE . Recommended values: 0.5 (moderate effect), 1.0 (2-fold change, strong effect), 1.5 (3-fold change, very strong)."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage - Load All DEG Results (TESTED - runtime: 0.059 sec)\n# ===========================================================================\n# Scientific Question: What genes are differentially expressed in this perturbation?\n# Expected output: Data.frame with ~30,000 genes and 7 columns\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Load all DEG results (no filtering)\ndeg <- gpdb_load_deg(\"D28200\", filter = FALSE)\n\n# Verify structure\ncat(\"Total genes:\", nrow(deg), \"\\n\")\nhead(deg)\n\n# Check columns\nnames(deg)\n# [1] \"gene_id\"   \"AveExpr\"   \"logFC\"     \"lfcSE\"     \"P.Value\"   \"adj.P.Val\" \"gene\"\n\n# Check value ranges\ncat(\"logFC range:\", range(deg$logFC, na.rm = TRUE), \"\\n\")\ncat(\"adj.P.Val range:\", range(deg$adj.P.Val, na.rm = TRUE), \"\\n\")\n\n# ===========================================================================\n# Example 2: Filter Significant Genes (TESTED - runtime: 0.006 sec)\n# ===========================================================================\n# Get only significant genes with strong effects\n\n# Load with built-in filtering\ndeg_sig <- gpdb_load_deg(\n  \"D28200\",\n  filter = TRUE,\n  padj_cutoff = 0.05, # FDR < 5%\n  logfc_cutoff = 1.0 # 2-fold change\n)\n\ncat(\"Significant genes:\", nrow(deg_sig), \"\\n\")\n# Output: Filtered to 359 significant genes\n\n# Separate upregulated and downregulated\nup_genes <- deg_sig[deg_sig$logFC > 0, ]\ndown_genes <- deg_sig[deg_sig$logFC < 0, ]\n\ncat(\"Upregulated:\", nrow(up_genes), \"\\n\")\ncat(\"Downregulated:\", nrow(down_genes), \"\\n\")\n\n# ===========================================================================\n# Example 3: Identify Top Changed Genes\n# ===========================================================================\n# Find most strongly affected genes\n\n# Load all genes first\ndeg <- gpdb_load_deg(\"D28200\")\n\n# Filter significant genes manually\nsig_genes <- deg[deg$adj.P.Val < 0.05 & abs(deg$logFC) > 1, ]\n\n# Sort by logFC to find top changed genes\ntop_up <- head(sig_genes[order(-sig_genes$logFC), ], 10)\ntop_down <- head(sig_genes[order(sig_genes$logFC), ], 10)\n\ncat(\"=== Top 10 Upregulated Genes ===\\n\")\nprint(top_up[, c(\"gene\", \"logFC\", \"adj.P.Val\", \"AveExpr\")])\n\ncat(\"\\n=== Top 10 Downregulated Genes ===\\n\")\nprint(top_down[, c(\"gene\", \"logFC\", \"adj.P.Val\", \"AveExpr\")])\n\n# ===========================================================================\n# Example 4: Volcano Plot Visualization\n# ===========================================================================\n# Visualize DEG results with volcano plot\n\ndeg <- gpdb_load_deg(\"D28200\")\n\n# Create volcano plot data\ndeg$neg_log10_p <- -log10(deg$adj.P.Val)\ndeg$significance <- \"NS\"\ndeg$significance[deg$adj.P.Val < 0.05 & deg$logFC > 1] <- \"Up\"\ndeg$significance[deg$adj.P.Val < 0.05 & deg$logFC < -1] <- \"Down\"\n\n# Plot with ggplot2\nlibrary(ggplot2)\nggplot(deg, aes(x = logFC, y = neg_log10_p, color = significance)) +\n  geom_point(alpha = 0.5, size = 1) +\n  scale_color_manual(values = c(\"Up\" = \"red\", \"Down\" = \"blue\", \"NS\" = \"grey\")) +\n  geom_hline(yintercept = -log10(0.05), linetype = \"dashed\") +\n  geom_vline(xintercept = c(-1, 1), linetype = \"dashed\") +\n  labs(\n    title = \"Volcano Plot: TP53 Perturbation\",\n    x = \"Log2 Fold Change\",\n    y = \"-Log10(Adjusted P-value)\"\n  ) +\n  theme_classic()\n\n# Or use built-in function\ngpdb_plot_volcano(\"D28200\")\n\n# ===========================================================================\n# Example 5: Pathway Enrichment Analysis\n# ===========================================================================\n# Use significant genes for functional enrichment\n\n# Get significant genes\ndeg_sig <- gpdb_load_deg(\"D28200\", filter = TRUE, padj_cutoff = 0.05, logfc_cutoff = 1)\n\n# Extract upregulated genes for enrichment\nup_genes <- deg_sig$gene[deg_sig$logFC > 0 & !is.na(deg_sig$gene) & deg_sig$gene != \"\"]\ncat(\"Upregulated genes for enrichment:\", length(up_genes), \"\\n\")\n\n# Run enrichment analysis\nenrich_result <- gpdb_enrich(\n  genes = up_genes,\n  enrich.type = \"GO\",\n  species = \"hsa\"\n)\n\n# View top enriched pathways\nif (!is.null(enrich_result)) {\n  cat(\"\\n=== Top Enriched GO Terms ===\\n\")\n  print(head(enrich_result$result, 10))\n}\n\n# ===========================================================================\n# Example 6: Compare with Raw Data Loading\n# ===========================================================================\n# Compare speed: Pre-computed DEG vs. custom analysis\n\n# Option 1: Load pre-computed DEG (fast)\nstart1 <- Sys.time()\ndeg_precomp <- gpdb_load_deg(\"D28200\")\ntime1 <- as.numeric(difftime(Sys.time(), start1, units = \"secs\"))\ncat(\"Pre-computed DEG loading:\", round(time1, 3), \"sec\\n\")\n# ~0.06 seconds\n\n# Option 2: Load raw data + run DESeq2 (slower but customizable)\nstart2 <- Sys.time()\ndata <- gpdb_load_data(\"D28200\")\n# dds <- DESeqDataSetFromMatrix(...) # Would take ~30-60 seconds\n# dds <- DESeq(dds)\n# res <- results(dds)\ntime2 <- as.numeric(difftime(Sys.time(), start2, units = \"secs\"))\ncat(\"Raw data loading:\", round(time2, 3), \"sec (+ ~30-60 sec for DESeq2)\\n\")\n\n# Pre-computed is much faster for standard analysis\ncat(\"\\nSpeed advantage: \", round(time2 / time1, 1), \"x faster (not including DESeq2 time)\\n\")\n\n# ===========================================================================\n# Example 7: Batch Load DEG for Multiple Datasets\n# ===========================================================================\n# Compare perturbation effects across experiments\n\n# Find datasets for same gene\ntp53_datasets <- gpdb_list_datasets(gene = \"TP53\")\nselected_ids <- head(tp53_datasets$dataset_id, 3)\n\n# Batch load DEG results\nbatch_deg <- gpdb_load_batch(\n  dataset_ids = selected_ids,\n  type = \"deg\",\n  show_progress = TRUE\n)\n\n# Compare number of significant genes across datasets\nfor (id in names(batch_deg)) {\n  sig_count <- sum(\n    batch_deg[[id]]$adj.P.Val < 0.05 &\n      abs(batch_deg[[id]]$logFC) > 1,\n    na.rm = TRUE\n  )\n  cell_line <- gpdb_get_info(id)$cell_line\n  cat(id, \"-\", cell_line, \":\", sig_count, \"significant genes\\n\")\n}\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# After loading DEG results, proceed to:\n# - Visualize: gpdb_plot_volcano() or gpdb_plot_heatmap_deg()\n# - Enrich: gpdb_enrich() for pathway analysis\n# - Compare: gpdb_find_targets() for consensus targets across datasets\n# - Validate: Load raw data with gpdb_load_data() for custom re-analysis\n# - Export: write.csv(deg_sig, \"significant_genes.csv\") for downstream tools\n## End(No test)\n\n\n\n",
    "return_value": "Data.frame containing differential expression results with the following structure: **Return Structure**: gene_id Ensembl gene ID (e.g., \"ENSG00000141510\") gene Gene symbol (e.g., \"TP53\") - may be empty for unannotated genes logFC Log2 fold-change (treatment vs control). Positive = upregulated, negative = downregulated in perturbation condition adj.P.Val FDR-adjusted p-value (Benjamini-Hochberg). Use < 0.05 for significance AveExpr Average log2 expression across samples. Higher values indicate more reliably measured genes P.Value Nominal p-value (before multiple testing correction) lfcSE Standard error of log-fold-change estimate **What You Can Do Next**: Filter by significance: deg[deg$adj.P.Val < 0.05 & abs(deg$logFC) > 1, ] Visualize volcano plot: gpdb_plot_volcano (dataset_id) Compare with other datasets: gpdb_find_targets (gene) Enrichment analysis: gpdb_enrich (deg$gene[deg$logFC > 1]) Heatmap visualization: gpdb_plot_heatmap_deg (dataset_id) Load expression data: gpdb_load_data (dataset_id) **Alternative Functions**: gpdb_load_data : Load raw expression matrix + metadata together. Use when you need to re-analyze data with custom parameters or methods. gpdb_find_targets : Query aggregated targets across all datasets. Use when you want consensus targets from multiple experiments, not single-dataset DEG. gpdb_load_batch : Batch load DEG results for multiple datasets. Use when comparing perturbation effects across experiments.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "dataset_id: Character. Dataset ID (e.g., \"D28200\"). Use gpdb_list_datasets to find available datasets for your gene of interest.\nfilter: Logical. Apply significance filters (default: FALSE , return all genes). Set TRUE to keep only significant genes passing\npadj_cutoff: [No description]\nlogfc_cutoff: Useful for focusing on biologically relevant changes. padj_cutoff Numeric. Adjusted p-value threshold (default: 0.05 ). Only used when filter = TRUE . Standard cutoff is 0.05 for FDR control; use 0.01 for stricter evidence. logfc_cutoff Numeric. Absolute log2 fold-change threshold (default: 0 ). Only used when filter = TRUE . Recommended values: 0.5 (moderate effect), 1.0 (2-fold change, strong effect), 1.5 (3-fold change, very strong).",
    "simple_arguments": "dataset_id: Character. Dataset ID (e.g., \"D28200\"). Use gpdb_list_datasets to find available datasets for your gene of interest."
  },
  "gpdb_load_metadata": {
    "package": "GenePerturbR",
    "function_name": "gpdb_load_metadata",
    "title": "Load Sample-Level Metadata from GenePerturbR Database",
    "description": "Retrieve sample-level metadata for a specific dataset without loading the full expression matrix. Useful for checking experimental design, sample grouping, sequencing platform, and technical details before loading raw data. **Database covers 7,665 perturbation experiments** with comprehensive sample annotations including treatment groups, cell lines, sequencing platforms, and accession IDs.",
    "user_queries": ["How do I check sample groups before loading the full dataset?", "What metadata is available for each perturbation experiment?", "How can I verify if a dataset has balanced controls and treatments?", "Which sequencing platform was used for my dataset of interest?", "How do I get sample IDs for custom analysis pipelines?", "What is the difference between loading metadata vs. full data?", "How can I check if samples are paired-end or single-end sequenced?", "What perturbation method was used (CRISPR, siRNA, shRNA)?", "How do I find the GEO accession numbers for a dataset?", "Can I load metadata for multiple datasets at once?", "What information is needed to design a DESeq2 analysis?", "How do I identify batch effects in the sample metadata?", "Which columns in metadata correspond to treatment groups?", "How can I verify the cell line used in an experiment?", "What are the SRA accession numbers for raw data download?", "How do I check if replicates are present in the dataset?", "Can I filter datasets by sequencing platform before loading?", "What metadata fields are consistent across all datasets?", "How do I use metadata to create custom DESeq2 designs?", "Where can I find detailed experimental descriptions?"],
    "usage": "gpdb_load_metadata(dataset_id)",
    "parameters": [
      {
        "name": "dataset_id",
        "has_default": false,
        "description": "Character. Dataset identifier (e.g., \"D10001\", \"D28200\"). Must be a valid dataset ID from gpdb_list_datasets() . Format: \"D\" followed by 5 digits (e.g., D10001, D28200)."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage (TESTED - runtime: 0.052 sec first call, 0.001 sec subsequent)\n# ===========================================================================\n# Scientific Question: What is the experimental design for TP53 perturbation?\n# Query: Load metadata to check sample groups before full data loading\n# Expected output: Data frame with 6 samples and 11 metadata columns\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Find TP53 datasets\ndatasets <- gpdb_list_datasets(gene = \"TP53\")\ndataset_id <- datasets$dataset_id[1] # Select first dataset\n\n# Load metadata only (fast!)\nmetadata <- gpdb_load_metadata(dataset_id)\n\n# Verify output structure\nstr(metadata)\ncat(\"Number of samples:\", nrow(metadata), \"\\n\")\n\n# Quick preview of sample annotations\nhead(metadata)\n\n# ===========================================================================\n# Example 2: Check Sample Balance (Before DESeq2 Analysis)\n# ===========================================================================\n# Verify balanced experimental design\n\n# Check treatment groups\ntable(metadata$group)\n# control   treat\n#       3       3\n\n# Check perturbation method\nunique(metadata$method)\n# [1] \"siRNA\"\n\n# Check sequencing platform (for batch effects)\nunique(metadata$platform)\n# [1] \"GPL20301\"\n\n# Check read type (paired vs single)\ntable(metadata$paired)\n# SINGLE\n#      6\n\n# ===========================================================================\n# Example 3: Extract Sample IDs for Custom Analysis\n# ===========================================================================\n# Get GEO and SRA accessions for data retrieval\n\n# GEO sample accessions\ngeo_samples <- metadata$GSM\ncat(\"GEO samples:\", paste(geo_samples, collapse = \", \"), \"\\n\")\n\n# SRA run accessions (for raw data download)\nsra_runs <- metadata$SRR\ncat(\"SRA runs:\", paste(sra_runs, collapse = \", \"), \"\\n\")\n\n# Control vs treatment sample IDs\ncontrol_samples <- metadata$GSM[metadata$group == \"control\"]\ntreat_samples <- metadata$GSM[metadata$group == \"treat\"]\n\ncat(\"Control samples:\", length(control_samples), \"\\n\")\ncat(\"Treatment samples:\", length(treat_samples), \"\\n\")\n\n# ===========================================================================\n# Example 4: Batch Load Metadata for Multiple Datasets\n# ===========================================================================\n# Compare experimental designs across studies\n\n# Get top 5 TP53 datasets\ntp53_datasets <- gpdb_list_datasets(gene = \"TP53\")\ntop5_ids <- tp53_datasets$dataset_id[1:5]\n\n# Batch load metadata (faster than individual calls)\nbatch_metadata <- gpdb_load_batch(\n  dataset_ids = top5_ids,\n  type = \"metadata\",\n  show_progress = TRUE\n)\n\n# Compare sample sizes\nsample_counts <- sapply(batch_metadata, nrow)\ncat(\"Sample counts per dataset:\\n\")\nprint(sample_counts)\n\n# Compare perturbation methods\nmethods <- sapply(batch_metadata, function(x) unique(x$method)[1])\ncat(\"\\nPerturbation methods:\\n\")\nprint(methods)\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# After checking metadata, proceed to:\n# - Full data loading: data <- gpdb_load_data(dataset_id)\n# - Get dataset info: info <- gpdb_get_info(dataset_id)\n# - DEG analysis: deg <- gpdb_load_deg(dataset_id, filter = TRUE)\n# - Query perturbation effects: results <- gpdb_what_happens(gene = \"TP53\")\n# - Custom DESeq2: Use metadata$group in design formula\n## End(No test)\n\n\n",
    "return_value": "Data frame with sample-level metadata. **Return Structure**: Columns Standard metadata columns (may vary by dataset): GSE : GEO series accession (e.g., \"GSE291033\") GSM : GEO sample accession (e.g., \"GSM8827856\") gene : Perturbed gene symbol (e.g., \"TP53\") method : Perturbation method (e.g., \"siRNA\", \"CRISPR\", \"shRNA\") celline : Cell line name (e.g., \"PANC-1\", \"HeLa\") group : Treatment status - \"control\" or \"treat\" (key column for DESeq2) group_name : Descriptive sample name (e.g., \"PANC1, sip53, 1\") platform : Sequencing platform (e.g., \"GPL20301\") SRR : SRA run accession (e.g., \"SRR32571800\") paired : Read type - \"SINGLE\" or \"PAIRED\" **What You Can Do Next**: Load full dataset: data <- gpdb_load_data(dataset_id) Check sample balance: table(metadata$group) Get dataset info: info <- gpdb_get_info(dataset_id) Filter datasets: datasets <- gpdb_list_datasets(gene = \"TP53\") Custom DESeq2 design: Use metadata$group in design formula **Alternative Methods**: gpdb_load_data : Load expression matrix + metadata together. Use when: Need complete dataset for differential expression analysis. gpdb_get_info : Get dataset-level information only. Use when: Need summary info (gene, cell line, tissue) without sample details. gpdb_load_batch : Batch load metadata for multiple datasets. Use when: Comparing experimental designs across studies.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "dataset_id: Character. Dataset identifier (e.g., \"D10001\", \"D28200\"). Must be a valid dataset ID from gpdb_list_datasets() . Format: \"D\" followed by 5 digits (e.g., D10001, D28200).",
    "simple_arguments": "dataset_id: Character. Dataset identifier (e.g., \"D10001\", \"D28200\"). Must be a valid dataset ID from gpdb_list_datasets() . Format: \"D\" followed by 5 digits (e.g., D10001, D28200)."
  },
  "gpdb_plot_cascade": {
    "package": "GenePerturbR",
    "function_name": "gpdb_plot_cascade",
    "title": "Visualize Regulatory Cascade as Network Graph",
    "description": "Renders cascade analysis results as an interactive network graph using force-directed layout algorithms. Displays gene-gene regulatory relationships with effect size encoding, highlighting the starting gene and multi-layer cascade structure discovered by gpdb_analyze_cascade . Uses publication-ready academic theme optimized for scientific figures.",
    "user_queries": ["How do I visualize the cascade network I discovered with gpdb_analyze_cascade?", "What do the colors and sizes in the cascade plot represent?", "Can I change the network layout algorithm for better visualization?", "How do I save the cascade plot as a high-resolution figure for publication?", "What layout works best for hierarchical regulatory cascades?", "Can I customize the plot colors or node sizes?", "How do I export the cascade network to Cytoscape for further analysis?", "Why are some edges thicker than others in the cascade plot?", "How do I add a custom title to my cascade network visualization?", "What do the red and blue nodes represent in the cascade plot?", "Can I use a different ggplot2 theme for the cascade visualization?", "How long does it take to render a cascade plot with 100+ genes?", "What packages do I need installed to use gpdb_plot_cascade?", "Can I overlay additional annotations on the cascade network?", "How do I interpret the arrows and edge directions in the cascade plot?", "What is the difference between fr and kk layout algorithms?", "Can I filter the cascade before plotting to show only strong effects?", "How do I make the plot larger for a presentation slide?", "Can I extract the igraph object for custom network analysis?", "What resolution (DPI) should I use for publication figures?"],
    "usage": "gpdb_plot_cascade(cascade_result, layout = \"fr\", title = NULL, theme = NULL)",
    "parameters": [
      {
        "name": "cascade_result",
        "has_default": false,
        "description": "List. Output from gpdb_analyze_cascade containing: $paths (data.frame of edges), $start_gene (focal gene), and $n_paths (edge count). Function validates structure before plotting."
      },
      {
        "name": "layout",
        "has_default": true,
        "default_value": "\"fr\"",
        "description": "Character. igraph layout algorithm: \"fr\" (Fruchterman-Reingold, default), \"kk\" (Kamada-Kawai), \"circle\", \"tree\", \"graphopt\", or other igraph layouts. \"fr\" provides best results for biological networks; \"kk\" works well for hierarchical cascades."
      },
      {
        "name": "title",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character. Plot title (optional). If NULL (default), auto-generates title: \"Regulatory Cascade from [GENE] ([N] edges)\". Provide custom string to override."
      },
      {
        "name": "theme",
        "has_default": true,
        "default_value": "NULL",
        "description": "ggplot2 theme object (optional). If NULL (default), uses .gpdb_theme_default() for publication-ready styling. Pass custom theme to match your figure style (e.g., theme_minimal() )."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Cascade Visualization (TESTED - runtime: 0.086 sec)\n# ===========================================================================\n# Scientific Question: How to visualize TP53 regulatory cascade network?\n# Input: Cascade result from gpdb_analyze_cascade\n# Expected output: Network graph with focal gene and downstream targets\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Step 1: Generate cascade data\ncascade <- gpdb_analyze_cascade(\n  start_gene = \"TP53\",\n  max_depth = 2,\n  min_confidence = \"high\",\n  direction = \"forward\"\n)\n\n# Step 2: Visualize cascade network\nplot <- gpdb_plot_cascade(cascade_result = cascade)\n\n# Display plot\nprint(plot)\n\n# Verify plot structure\ncat(\"Plot class:\", class(plot), \"\\n\")\ncat(\"Number of layers:\", length(plot$layers), \"\\n\")\n\n# ===========================================================================\n# Example 2: Layout Algorithm Comparison\n# ===========================================================================\n# Compare different layout algorithms to find best visualization\n\n# Fruchterman-Reingold: minimizes edge crossings (best for general networks)\nplot_fr <- gpdb_plot_cascade(\n  cascade_result = cascade,\n  layout = \"fr\"\n)\n\n# Kamada-Kawai: emphasizes shortest paths (good for hierarchical cascades)\nplot_kk <- gpdb_plot_cascade(\n  cascade_result = cascade,\n  layout = \"kk\"\n)\n\n# Circle: nodes on perimeter (useful for connectivity patterns)\nplot_circle <- gpdb_plot_cascade(\n  cascade_result = cascade,\n  layout = \"circle\"\n)\n\n# Display for comparison\n# print(plot_fr)\n# print(plot_kk)\n# print(plot_circle)\n\ncat(\"Tested layouts: fr, kk, circle - all render successfully\\n\")\n\n# ===========================================================================\n# Example 3: Custom Title and Theme\n# ===========================================================================\n# Customize plot appearance for publication or presentation\n\n# Custom title\nplot_custom <- gpdb_plot_cascade(\n  cascade_result = cascade,\n  layout = \"fr\",\n  title = \"TP53 Regulatory Network (Depth 2, High Confidence)\"\n)\n\n# Add ggplot2 layers for further customization\nplot_enhanced <- plot_custom +\n  ggplot2::labs(subtitle = \"Direct and secondary downstream targets\") +\n  ggplot2::theme(\n    plot.title = ggplot2::element_text(size = 16, face = \"bold\"),\n    plot.subtitle = ggplot2::element_text(size = 12, color = \"grey40\")\n  )\n\nprint(plot_enhanced)\n\n# ===========================================================================\n# Example 4: Bidirectional Cascade Network\n# ===========================================================================\n# Visualize both upstream and downstream regulatory relationships\n\n# Generate bidirectional cascade (depth 3, both directions)\ncascade_both <- gpdb_analyze_cascade(\n  start_gene = \"TP53\",\n  max_depth = 3,\n  min_confidence = \"medium\",\n  direction = \"both\" # Include forward and backward relationships\n)\n\n# Visualize comprehensive network\nplot_both <- gpdb_plot_cascade(\n  cascade_result = cascade_both,\n  layout = \"fr\",\n  title = paste0(\n    \"TP53 Regulatory Network (\",\n    cascade_both$n_paths, \" edges, \",\n    cascade_both$n_genes, \" genes)\"\n  )\n)\n\nprint(plot_both)\n\ncat(\"\\nNetwork statistics:\\n\")\ncat(\"  Edges:\", cascade_both$n_paths, \"\\n\")\ncat(\"  Genes:\", cascade_both$n_genes, \"\\n\")\ncat(\"  Direction breakdown:\\n\")\nprint(table(cascade_both$paths$direction))\n\n# ===========================================================================\n# Example 5: Save High-Resolution Figure for Publication\n# ===========================================================================\n# Export plot as publication-ready figure\n\n# Generate plot\ncascade_pub <- gpdb_analyze_cascade(\n  start_gene = \"MYC\",\n  max_depth = 2,\n  min_confidence = \"high\",\n  direction = \"forward\"\n)\n\nplot_pub <- gpdb_plot_cascade(\n  cascade_result = cascade_pub,\n  layout = \"kk\",\n  title = \"MYC Downstream Regulatory Cascade\"\n)\n\n# Save as PDF (vector format, best for journals)\n# ggsave(\"myc_cascade.pdf\", plot_pub, width = 12, height = 10, dpi = 300)\n\n# Save as PNG (raster format, good for presentations)\n# ggsave(\"myc_cascade.png\", plot_pub, width = 12, height = 10, dpi = 300)\n\ncat(\"\\nPublication tips:\\n\")\ncat(\"  - Use width=12, height=10 for standard figures\\n\")\ncat(\"  - Set dpi=300 for journal submission\\n\")\ncat(\"  - PDF format for vector graphics (preferred by journals)\\n\")\ncat(\"  - PNG format for slides and posters\\n\")\n\n# ===========================================================================\n# Example 6: Filter and Export for Cytoscape\n# ===========================================================================\n# Prepare cascade data for external network analysis tools\n\n# Generate cascade\ncascade_export <- gpdb_analyze_cascade(\n  start_gene = \"TP53\",\n  max_depth = 3,\n  min_confidence = \"medium\",\n  direction = \"both\"\n)\n\n# Filter to strong effects only (|effect| > 1.5)\ncascade_filtered <- cascade_export\ncascade_filtered$paths <- cascade_export$paths[\n  abs(cascade_export$paths$effect) > 1.5,\n]\ncascade_filtered$n_paths <- nrow(cascade_filtered$paths)\n\ncat(\"\\nFiltering effect:\\n\")\ncat(\"  Original:\", cascade_export$n_paths, \"edges\\n\")\ncat(\"  Filtered (|effect| > 1.5):\", cascade_filtered$n_paths, \"edges\\n\")\n\n# Visualize filtered network (cleaner, fewer edges)\nplot_filtered <- gpdb_plot_cascade(\n  cascade_result = cascade_filtered,\n  layout = \"fr\",\n  title = \"TP53 Cascade (Strong Effects Only, |logFC| > 1.5)\"\n)\n\nprint(plot_filtered)\n\n# Export edge list for Cytoscape\n# write.csv(cascade_filtered$paths, \"tp53_cascade_edges.csv\", row.names = FALSE)\n\ncat(\"\\nCytoscape import:\\n\")\ncat(\"  1. Save edge list: write.csv(cascade$paths, 'edges.csv')\\n\")\ncat(\"  2. Import in Cytoscape: File → Import → Network from File\\n\")\ncat(\"  3. Map columns: 'from' = Source, 'to' = Target, 'effect' = Edge Weight\\n\")\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# For complete workflows, see:\n# - Generate cascade: ?gpdb_analyze_cascade (required input for this function)\n# - Pathway enrichment: ?gpdb_enrich (analyze genes in cascade)\n# - Compare genes: ?gpdb_compare_genes (compare cascades of multiple genes)\n# - Load raw data: ?gpdb_load_data (expression data for cascade genes)\n# - Alternative viz: ?gpdb_plot_network (simpler network plot for direct relationships)\n## End(No test)\n\n\n",
    "return_value": "ggplot2 object (class: ggraph, ggplot, gg) with network visualization. Can be further customized using standard ggplot2 syntax or saved with ggsave() . **Plot Structure**: Nodes Genes in cascade network. Size = node degree (connectivity), Color = focal gene (red) vs other genes (blue) Edges Regulatory relationships. Color = effect size (spectral gradient), Width/Alpha = absolute effect magnitude, Arrow = direction of regulation Labels Gene symbols with repulsion to avoid overlap (via ggrepel) **Programmatic Customization**: Change layout: gpdb_plot_cascade(result, layout = \"kk\") Custom title: gpdb_plot_cascade(result, title = \"My Network\") Add theme layer: gpdb_plot_cascade(result) + theme_minimal() Adjust node size: gpdb_plot_cascade(result) + scale_size(range = c(8, 20)) Save figure: ggsave(\"cascade.pdf\", width = 10, height = 8) **What You Can Do Next**: Save high-res figure: ggsave(\"cascade_network.pdf\", plot, width = 12, height = 10, dpi = 300) Enrich cascade genes: gpdb_enrich (unique(c(cascade$paths$from, cascade$paths$to))) Export for Cytoscape: write.csv(cascade$paths, \"edges.csv\") Compare with other genes: gpdb_compare_genes (c(\"TP53\", \"MYC\")) Re-run with different depth: gpdb_analyze_cascade (gene, max_depth = 4)",
    "references": ["Fruchterman, T. M., & Reingold, E. M. (1991). Graph drawing by force-directed placement. Software: Practice and Experience, 21(11), 1129-1164. doi:10.1002/spe.4380211102", "Pedersen, T. L. (2021). ggraph: An Implementation of Grammar of Graphics for Graphs and Networks. R package version 2.0.5.", "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066"],
    "formatted_arguments": "cascade_result: List. Output from gpdb_analyze_cascade containing: $paths (data.frame of edges), $start_gene (focal gene), and $n_paths (edge count). Function validates structure before plotting.\nlayout: Character. igraph layout algorithm: \"fr\" (Fruchterman-Reingold, default), \"kk\" (Kamada-Kawai), \"circle\", \"tree\", \"graphopt\", or other igraph layouts. \"fr\" provides best results for biological networks; \"kk\" works well for hierarchical cascades.\ntitle: Character. Plot title (optional). If NULL (default), auto-generates title: \"Regulatory Cascade from [GENE] ([N] edges)\". Provide custom string to override.\ntheme: ggplot2 theme object (optional). If NULL (default), uses .gpdb_theme_default() for publication-ready styling. Pass custom theme to match your figure style (e.g., theme_minimal() ).",
    "simple_arguments": "cascade_result: List. Output from gpdb_analyze_cascade containing: $paths (data.frame of edges), $start_gene (focal gene), and $n_paths (edge count). Function validates structure before plotting."
  },
  "gpdb_plot_comparison": {
    "package": "GenePerturbR",
    "function_name": "gpdb_plot_comparison",
    "title": "Compare Dataset Distribution Across Experimental Contexts",
    "description": "Create publication-ready bar plot visualizing how datasets for a gene are distributed across different experimental contexts (tissues, cell lines, or perturbation methods). **Summarizes data availability** for exploring context-specific vs universal gene functions and identifying well-studied vs understudied experimental systems.",
    "user_queries": ["How do I see which tissues have been studied for my gene?", "Which cell lines are commonly used for TP53 experiments?", "How many datasets are available for each perturbation method?", "What's the distribution of datasets across experimental contexts?", "How do I identify well-studied vs understudied tissue types?", "Can I visualize data availability before starting analysis?", "Which experimental systems have the most datasets?", "How do I choose appropriate cell lines for my analysis?", "Are there enough CRISPR datasets for my gene of interest?", "What tissue types are missing from the database?", "How do I compare dataset coverage between different genes?", "Can I see which methods are most commonly used?", "How do I assess data availability for experimental design?", "What's the best way to visualize dataset distribution?", "Which contexts should I prioritize for robust findings?", "How do I identify gaps in experimental coverage?", "Can I customize the colors and appearance of the bar plot?", "How do I export high-resolution comparison plots?", "What does the ordering of bars tell me about data availability?", "How do I interpret dataset counts for analysis planning?"],
    "usage": "gpdb_plot_comparison( gene, stratify_by = c(\"tissue\", \"cell_line\", \"method\"), colors = NULL, title = NULL, x.text.angle = 45, bar.alpha = 0.9, bar.width = 0.7, add.text = TRUE, theme.plot = NULL )",
    "parameters": [
      {
        "name": "gene",
        "has_default": false,
        "description": "Character. Gene symbol to query. Default: None (required). Gene name will be formatted automatically (case-insensitive). Example: \"TP53\" or \"tp53\" . Use gpdb_search() to verify gene availability."
      },
      {
        "name": "stratify_by",
        "has_default": true,
        "default_value": "c(\"tissue\", \"cell_line\", \"method\")",
        "description": "Character. Stratification variable for grouping datasets. Default: \"tissue\" (first option). Options: \"tissue\", \"cell_line\", \"method\". Determines how datasets are categorized in bar plot. Each choice reveals different aspects: - \"tissue\": Shows tissue-type coverage (e.g., Lung, Liver, Brain) - \"cell_line\": Shows specific cell line usage (e.g., HeLa, A549, MCF7) - \"method\": Shows perturbation method distribution (e.g., CRISPR, siRNA, shRNA)"
      },
      {
        "name": "colors",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character vector. Custom color palette for bars. Default: NULL (uses gradient blue-green palette, auto-scaled to number of categories). Provide vector of colors for custom palette. Colors interpolated if fewer than categories."
      },
      {
        "name": "title",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character. Custom plot title. Default: NULL (auto-generated: \"Gene Datasets by Stratification\"). Provide custom title to override. Title is centered and bolded."
      },
      {
        "name": "x.text.angle",
        "has_default": true,
        "default_value": "45",
        "description": "Numeric. Rotation angle for x-axis labels in degrees. Default: 45 . Range: 0-90. Use 45-90 for long category names (e.g., cell lines). Set 0 for horizontal labels if category names are short."
      },
      {
        "name": "bar.alpha",
        "has_default": true,
        "default_value": "0.9",
        "description": "Numeric. Transparency of bars. Default: 0.9 . Range: 0-1. Lower values create semi-transparent bars. Use 0.7-0.9 for overlapping plots or layered visualizations."
      },
      {
        "name": "bar.width",
        "has_default": true,
        "default_value": "0.7",
        "description": "Numeric. Width of bars relative to category spacing. Default: 0.7 . Range: 0.3-1.0. Higher values create wider bars with less spacing. Use 0.5-0.7 for cleaner appearance with many categories."
      },
      {
        "name": "add.text",
        "has_default": true,
        "default_value": "TRUE",
        "description": "Logical. Display count labels on top of bars. Default: TRUE . Shows exact dataset count above each bar. Set FALSE for cleaner appearance when counts are not critical."
      },
      {
        "name": "theme.plot",
        "has_default": true,
        "default_value": "NULL",
        "description": "ggplot2 theme object. Custom theme for plot styling. Default: NULL (uses .gpdb_theme_default() , publication-ready academic theme). Can provide custom ggplot2 theme."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Tissue Distribution (TESTED - runtime: 0.44 sec)\n# ===========================================================================\n# Scientific Question: Which tissues have been studied for TP53?\n# Use Case: Select tissue-relevant contexts for analysis\n# Expected output: Bar plot showing 23 tissue types with TP53 data\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Visualize TP53 dataset distribution by tissue\np1_tissue <- gpdb_plot_comparison(\n  gene = \"TP53\",\n  stratify_by = \"tissue\"\n)\n\n# Plot is ready\nprint(p1_tissue)\n\n# Interpretation: Taller bars (right) = more studied tissues\n# Look for tissues relevant to your research question\n\n# Save to file\n# ggplot2::ggsave(\"tp53_tissue_distribution.pdf\", p1_tissue, width = 12, height = 6)\n\n# ===========================================================================\n# Example 2: Cell Line Distribution\n# ===========================================================================\n# Question: Which cell lines are commonly used for TP53 studies?\n\np2_cellline <- gpdb_plot_comparison(\n  gene = \"TP53\",\n  stratify_by = \"cell_line\"\n)\n\nprint(p2_cellline)\n\n# Interpretation: Identifies most frequently used cell models\n# Right side = well-established cell line models\n# Left side = less common but potentially novel models\n\n# ===========================================================================\n# Example 3: Method Distribution\n# ===========================================================================\n# Question: What perturbation methods are available for TP53?\n\np3_method <- gpdb_plot_comparison(\n  gene = \"TP53\",\n  stratify_by = \"method\"\n)\n\nprint(p3_method)\n\n# Interpretation: Shows method diversity and availability\n# Compare CRISPR vs siRNA vs shRNA data availability\n# Multiple methods = cross-validation opportunity\n\n# ===========================================================================\n# Example 4: Customize Appearance\n# ===========================================================================\n# Publication-ready customization\n\nlibrary(ggplot2)\n\n# Custom color palette (warm colors)\ncustom_colors <- c(\"#FEE5D9\", \"#FCAE91\", \"#FB6A4A\", \"#DE2D26\", \"#A50F15\")\n\np4_custom <- gpdb_plot_comparison(\n  gene = \"TP53\",\n  stratify_by = \"tissue\",\n  colors = custom_colors, # Custom gradient\n  x.text.angle = 60, # Steeper angle\n  bar.alpha = 0.85, # Slightly transparent\n  bar.width = 0.6, # Narrower bars\n  title = \"TP53 Perturbation Studies: Tissue Coverage\"\n)\n\n# Further customization with ggplot2\np4_final <- p4_custom +\n  labs(\n    subtitle = \"Based on GPSAdb (71 datasets)\",\n    caption = \"Data source: Guo et al. (2022) Nucleic Acids Res\"\n  ) +\n  theme(\n    plot.subtitle = element_text(hjust = 0.5, size = 11, color = \"grey30\")\n  )\n\n# ===========================================================================\n# Example 5: Compare Multiple Genes\n# ===========================================================================\n# Question: How does data availability compare between genes?\n\n# Compare TP53 vs MYC tissue coverage\np5_tp53 <- gpdb_plot_comparison(\"TP53\", stratify_by = \"tissue\")\np5_myc <- gpdb_plot_comparison(\"MYC\", stratify_by = \"tissue\")\n\n# Print side-by-side comparison\n# library(patchwork)  # For combining plots\n# p5_tp53 + p5_myc\n\ncat(\"Compare which gene has broader tissue coverage\\n\")\n\n# ===========================================================================\n# Example 6: Workflow Integration - From Comparison to Analysis\n# ===========================================================================\n# Complete workflow: Explore → Select → Analyze\n\n# Step 1: Visualize tissue distribution\np6 <- gpdb_plot_comparison(\"TP53\", stratify_by = \"tissue\")\nprint(p6)\n\n# Step 2: List datasets to see details\ndatasets <- gpdb_list_datasets(gene = \"TP53\")\ncat(\"Total datasets:\", nrow(datasets), \"\\n\")\n\n# Step 3: Filter by high-coverage tissue (example: if \"Lung\" has most data)\n# lung_datasets <- datasets[datasets$tissue == \"Lung\", ]\n# cat(\"Lung datasets:\", nrow(lung_datasets), \"\\n\")\n\n# Step 4: Select representative datasets for analysis\n# selected_ids <- head(lung_datasets$dataset_id, 5)\n\n# Step 5: Compare expression patterns\n# heatmap <- gpdb_plot_heatmap_deg(selected_ids, top_n = 30)\n\ncat(\"Workflow: Comparison plot → Dataset selection → Expression analysis\\n\")\n\n# ===========================================================================\n# Example 7: Identify Research Gaps\n# ===========================================================================\n# Find understudied contexts for novel research\n\n# Get raw data for analysis\ndatasets_all <- gpdb_list_datasets(gene = \"TP53\")\n\n# Summarize tissue coverage\ntissue_summary <- table(datasets_all$tissue)\ntissue_sorted <- sort(tissue_summary)\n\ncat(\"\\n=== Research Gap Analysis ===\\n\")\ncat(\"Understudied tissues (≤2 datasets):\\n\")\nprint(tissue_sorted[tissue_sorted <= 2])\n\ncat(\"\\n Well-studied tissues (≥5 datasets):\\n\")\nprint(tissue_sorted[tissue_sorted >= 5])\n\n# Visualize\np7 <- gpdb_plot_comparison(\"TP53\", stratify_by = \"tissue\")\ncat(\"\\nLeft bars = potential for novel discoveries\\n\")\ncat(\"Right bars = robust data for validation\\n\")\n\n# ===========================================================================\n# Next Steps (Workflow Integration)\n# ===========================================================================\n# For complete workflows, see:\n# - List datasets: ?gpdb_list_datasets\n# - Get dataset info: ?gpdb_get_info\n# - Cross-dataset heatmap: ?gpdb_plot_heatmap_deg\n# - Find targets: ?gpdb_find_targets\n# - Network analysis: ?gpdb_plot_network\n## End(No test)\n\n\n\n",
    "return_value": "ggplot object showing dataset distribution bar plot. **Plot Elements**: X-axis Categories (tissues, cell lines, or methods) sorted by dataset count (ascending) Y-axis Number of datasets in each category Bars Each bar represents one category, colored with gradient (left = fewer, right = more) Labels Dataset counts displayed on top of bars (if add.text = TRUE) Sorting Categories ordered from fewest to most datasets for easy comparison **What You Can Do Next**: Save plot: ggplot2::ggsave(\"comparison.pdf\", p, width = 10, height = 6) Identify well-studied contexts: Focus on categories with most datasets (right side) Find understudied contexts: Target categories with few datasets (left side) for novelty Select datasets for analysis: Use top categories to choose representative experiments Compare across stratifications: Create all three plots (tissue/cell_line/method) for comprehensive view Filter datasets: Use gpdb_list_datasets() with context filters based on plot insights Plan experiments: Identify gaps in experimental coverage for new studies **Alternative Visualizations**: gpdb_plot_heatmap_deg : Heatmap comparing expression changes across selected datasets. Use when: Want to see actual perturbation effects after identifying datasets. gpdb_plot_network : Gene regulatory network for the gene. Use when: Interested in gene-gene relationships rather than dataset distribution.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "gene: Character. Gene symbol to query. Default: None (required). Gene name will be formatted automatically (case-insensitive). Example: \"TP53\" or \"tp53\" . Use gpdb_search() to verify gene availability.\nstratify_by: Character. Stratification variable for grouping datasets. Default: \"tissue\" (first option). Options: \"tissue\", \"cell_line\", \"method\". Determines how datasets are categorized in bar plot. Each choice reveals different aspects: - \"tissue\": Shows tissue-type coverage (e.g., Lung, Liver, Brain) - \"cell_line\": Shows specific cell line usage (e.g., HeLa, A549, MCF7) - \"method\": Shows perturbation method distribution (e.g., CRISPR, siRNA, shRNA)\ncolors: Character vector. Custom color palette for bars. Default: NULL (uses gradient blue-green palette, auto-scaled to number of categories). Provide vector of colors for custom palette. Colors interpolated if fewer than categories.\ntitle: Character. Custom plot title. Default: NULL (auto-generated: \"Gene Datasets by Stratification\"). Provide custom title to override. Title is centered and bolded.\nx.text.angle: Numeric. Rotation angle for x-axis labels in degrees. Default: 45 . Range: 0-90. Use 45-90 for long category names (e.g., cell lines). Set 0 for horizontal labels if category names are short.\nbar.alpha: Numeric. Transparency of bars. Default: 0.9 . Range: 0-1. Lower values create semi-transparent bars. Use 0.7-0.9 for overlapping plots or layered visualizations.\nbar.width: Numeric. Width of bars relative to category spacing. Default: 0.7 . Range: 0.3-1.0. Higher values create wider bars with less spacing. Use 0.5-0.7 for cleaner appearance with many categories.\nadd.text: Logical. Display count labels on top of bars. Default: TRUE . Shows exact dataset count above each bar. Set FALSE for cleaner appearance when counts are not critical.\ntheme.plot: ggplot2 theme object. Custom theme for plot styling. Default: NULL (uses .gpdb_theme_default() , publication-ready academic theme). Can provide custom ggplot2 theme.",
    "simple_arguments": "gene: Character. Gene symbol to query. Default: None (required). Gene name will be formatted automatically (case-insensitive). Example: \"TP53\" or \"tp53\" . Use gpdb_search() to verify gene availability."
  },
  "gpdb_plot_enrichment": {
    "package": "GenePerturbR",
    "function_name": "gpdb_plot_enrichment",
    "title": "Paired Dotplot Visualization for Pathway Enrichment",
    "description": "Create side-by-side dotplots comparing enriched pathways in upregulated versus downregulated genes using publication-ready aesthetics. Visualizes top pathways ranked by significance with customizable color gradients (p-value/FoldEnrich) and point sizes (gene count). Returns a patchwork object combining two dotplots for direct comparison of directional pathway changes.",
    "user_queries": ["How do I visualize pathway enrichment results as dotplots?", "What's the best way to compare upregulated vs downregulated pathways?", "How to customize enrichment dotplot colors and sizes?", "Can I show top 20 pathways instead of default 15?", "How do I save enrichment plots for publication?", "What does point size represent in the enrichment dotplot?", "Should I use FoldEnrich or p-value for the X-axis?", "How to interpret color gradients in enrichment plots?", "Can I plot all pathways even if not significant?", "What are the recommended plot dimensions for enrichment figures?", "How do I export enrichment plots to PowerPoint?", "Can I extract individual panels from the paired dotplot?", "How to change the color palette to viridis or custom colors?", "Why do enrichment plots show different colors for up vs down?", "How to adjust point size range for better visualization?", "Can I remove legends to maximize plot area?", "How to customize pathway label formatting?", "What if I have no significant pathways to plot?", "How to create publication-quality enrichment figures?", "Can I combine multiple enrichment plots into one figure?"],
    "usage": "gpdb_plot_enrichment( enrich_result, show.term.num = 15, use.all = FALSE, x = \"FoldEnrich\", color.by = \"p.adjust\", size.by = \"Count\", colors = c(\"#003c30\", \"#01665e\", \"#35978f\", \"#80cdc1\", \"#c7eae5\", \"#f6e8c3\", \"#dfc27d\", \"#bf812d\", \"#8c510a\", \"#543005\"), size.range = c(3, 8), title = NULL, up.title = \"Upregulated Genes\", down.title = \"Downregulated Genes\", legend.position = \"right\", theme = ggplot2::theme_bw(base_rect_size = 1.5) )",
    "parameters": [
      {
        "name": "enrich_result",
        "has_default": false,
        "description": "gpdb_enrichment object from gpdb_enrich . Must contain $upregulated and $downregulated enrichment results."
      },
      {
        "name": "show.term.num",
        "has_default": true,
        "default_value": "15",
        "description": "Integer. Number of top pathways to display per panel (default: 15). Pathways ranked by p-value. Increase to 20-30 for comprehensive view, decrease to 5-10 for focus."
      },
      {
        "name": "use.all",
        "has_default": true,
        "default_value": "FALSE",
        "description": "Logical. Plot all pathways or only significant ones (default: FALSE, significant only). Set TRUE to visualize trends even without significant enrichment (p < 0.05)."
      },
      {
        "name": "x",
        "has_default": true,
        "default_value": "\"FoldEnrich\"",
        "description": "Character. X-axis variable: \"FoldEnrich\" (enrichment ratio, default), \"pvalue\" (raw p-value), \"p.adjust\" (FDR-corrected), \"Count\" (gene count). \"FoldEnrich\" emphasizes biological magnitude; \"pvalue\" emphasizes statistical significance."
      },
      {
        "name": "color.by",
        "has_default": true,
        "default_value": "\"p.adjust\"",
        "description": "Character. Variable mapped to point color: \"p.adjust\" (FDR, default), \"pvalue\", \"FoldEnrich\", \"Count\". Color gradient shows continuous scale."
      },
      {
        "name": "size.by",
        "has_default": true,
        "default_value": "\"Count\"",
        "description": "Character. Variable mapped to point size: \"Count\" (gene count, default), \"pvalue\", \"p.adjust\", \"FoldEnrich\". Larger points indicate more genes or stronger significance."
      },
      {
        "name": "colors",
        "has_default": true,
        "default_value": "c(\"#003c30\", \"#01665e\", \"#35978f\", \"#80cdc1\", \"#c7eae5\", \"#f6e8c3\", \"#dfc27d\", \"#bf812d\", \"#8c510a\", \"#543005\")",
        "description": "Character vector. Color palette for gradient (default: BrBG diverging palette). Provide custom colors like c(\"blue\", \"white\", \"red\") or use viridis scales. Reversed automatically for downregulated panel to maintain visual symmetry."
      },
      {
        "name": "size.range",
        "has_default": true,
        "default_value": "c(3, 8)",
        "description": "Numeric vector of length 2. Point size range in mm (default: c(3, 8)). Adjust for visual clarity: smaller range for dense plots, larger for emphasis."
      },
      {
        "name": "title",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character. Main plot title (default: auto-generated from database and ontology). Set to custom text or NULL to remove."
      },
      {
        "name": "up.title",
        "has_default": true,
        "default_value": "\"Upregulated Genes\"",
        "description": "Character. Title for upregulated panel (default: \"Upregulated Genes\")."
      },
      {
        "name": "down.title",
        "has_default": true,
        "default_value": "\"Downregulated Genes\"",
        "description": "Character. Title for downregulated panel (default: \"Downregulated Genes\")."
      },
      {
        "name": "legend.position",
        "has_default": true,
        "default_value": "\"right\"",
        "description": "Character. Legend placement: \"right\" (default), \"bottom\", \"none\". Use \"bottom\" for wide plots, \"none\" to maximize plot area."
      },
      {
        "name": "theme",
        "has_default": true,
        "default_value": "ggplot2::theme_bw(base_rect_size = 1.5)",
        "description": "ggplot2 theme object (default: theme_bw(base_rect_size = 1.5) ). Publication-ready theme with clean white background. Customize with theme_minimal() , etc."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage (TESTED - runtime: 0.096 sec)\n# ===========================================================================\n# Scientific Question: How do upregulated vs downregulated pathways differ?\n# Input: gpdb_enrichment object from TP53 perturbation analysis\n# Expected output: Side-by-side dotplots showing top pathways per direction\n\n# Zero configuration - just run!\nlibrary(GenePerturbR)\n\n# Step 1: Get enrichment results\ntargets <- gpdb_find_targets(\"TP53\", top_n = 200, min_confidence = \"medium\")\nenrich_result <- gpdb_enrich(targets, enrich.type = \"KEGG\", p.cutoff = 0.05)\n\n# Step 2: Create visualization\nplot <- gpdb_plot_enrichment(enrich_result)\n\n# Print plot (in RStudio/interactive session)\nprint(plot)\n\n# Check plot properties\ncat(\"Plot class:\", class(plot)[1], \"\\n\")\ncat(\"Recommended dimensions:\", attr(plot, \"width\"), \"x\", attr(plot, \"height\"), \"inches\\n\")\n\n# Save to file with recommended dimensions\n# ggsave(\"enrichment.pdf\", plot,\n#        width = attr(plot, \"width\"),\n#        height = attr(plot, \"height\"))\n\n# ===========================================================================\n# Example 2: Customize Visual Encoding (X-axis and color mapping)\n# ===========================================================================\n# Compare different ways to emphasize enrichment\n\n# Default: FoldEnrich (X) + p.adjust (color)\nplot1 <- gpdb_plot_enrichment(\n  enrich_result,\n  show.term.num = 10,\n  x = \"FoldEnrich\", # Biological magnitude\n  color.by = \"p.adjust\" # Statistical significance\n)\n\n# Alternative: p-value (X) + FoldEnrich (color)\nplot2 <- gpdb_plot_enrichment(\n  enrich_result,\n  show.term.num = 10,\n  x = \"pvalue\", # Statistical significance\n  color.by = \"FoldEnrich\" # Biological magnitude\n)\n\n# Emphasize gene count\nplot3 <- gpdb_plot_enrichment(\n  enrich_result,\n  show.term.num = 10,\n  x = \"Count\", # Number of genes\n  color.by = \"p.adjust\",\n  size.by = \"FoldEnrich\" # Size by enrichment ratio\n)\n\n# ===========================================================================\n# Example 3: Custom Color Palettes and Sizes\n# ===========================================================================\n# Use custom colors for publication or aesthetic preference\n\n# Viridis-style colors\nplot_viridis <- gpdb_plot_enrichment(\n  enrich_result,\n  show.term.num = 15,\n  colors = viridis::viridis(10),\n  size.range = c(4, 10) # Larger points\n)\n\n# Red-blue diverging (classic)\nplot_rdb <- gpdb_plot_enrichment(\n  enrich_result,\n  show.term.num = 15,\n  colors = c(\n    \"#2166AC\", \"#4393C3\", \"#92C5DE\", \"#D1E5F0\",\n    \"#F7F7F7\", \"#FDDBC7\", \"#F4A582\", \"#D6604D\", \"#B2182B\"\n  ),\n  size.range = c(2, 6) # Smaller, tighter range\n)\n\n# ===========================================================================\n# Example 4: Handle Non-Significant Results\n# ===========================================================================\n# Visualize trends even when no pathways pass significance threshold\n\n# If no significant pathways, use.all = TRUE shows top pathways anyway\nplot_all <- gpdb_plot_enrichment(\n  enrich_result,\n  show.term.num = 10,\n  use.all = TRUE, # Show all pathways (not just p < 0.05)\n  x = \"FoldEnrich\",\n  color.by = \"pvalue\" # Still color by p-value to show trends\n)\n\n# Useful for exploratory analysis or when enrichment is weak\n\n# ===========================================================================\n# Example 5: Advanced Customization (patchwork + ggplot2)\n# ===========================================================================\n# Modify plot after creation for publication needs\n\nlibrary(patchwork)\nlibrary(ggplot2)\n\nplot <- gpdb_plot_enrichment(enrich_result, show.term.num = 10)\n\n# Add overall title and caption\nplot_final <- plot +\n  plot_annotation(\n    title = \"TP53 Perturbation: Pathway Enrichment Analysis\",\n    subtitle = \"KEGG Pathways (Fisher's Exact Test)\",\n    caption = \"Source: GenePerturbR (GPSAdb database)\",\n    theme = theme(plot.title = element_text(size = 16, face = \"bold\"))\n  )\n\n# Modify both panels with unified theme\nplot_minimal <- plot & theme_minimal(base_size = 12)\n\n# Extract and customize individual panels\nplot_up <- plot[[1]] +\n  labs(title = \"Activated Pathways\") +\n  theme(axis.text.y = element_text(color = \"darkred\"))\n\n# ===========================================================================\n# Next Steps (Complete Workflow)\n# ===========================================================================\n# For complete visualization workflows, see:\n# - Network visualization: ?gpdb_plot_network\n# - Run enrichment first: ?gpdb_enrich\n# - Get gene targets: ?gpdb_find_targets\n# - Export options: ?ggplot2::ggsave\n# - Combine plots: ?patchwork::plot_layout\n## End(No test)\n\n\n",
    "return_value": "patchwork object (combined ggplot) with two side-by-side dotplots. **Return Structure**: Combined plot Two-panel layout showing upregulated (left) vs downregulated (right) pathways. X-axis : Enrichment metric (FoldEnrich, p-value, etc.) Y-axis : Pathway descriptions (auto-formatted, capitalized) Point color : Continuous gradient (e.g., FDR from low to high) Point size : Proportional to selected variable (e.g., gene count) Dimensions : Auto-calculated based on pathway count and label length Attributes attr(plot, \"width\") : Recommended width in inches (typically 14-20) attr(plot, \"height\") : Recommended height in inches (typically 6-12) **What You Can Do Next**: Save to file: ggsave(\"enrichment.pdf\", plot, width = attr(plot, \"width\"), height = attr(plot, \"height\")) Customize further: plot + patchwork::plot_annotation(tag_levels = 'A') Extract individual panels: plot[[1]] (upregulated), plot[[2]] (downregulated) Modify theme: plot & ggplot2::theme_minimal() Export to PowerPoint: Use rvg or officer packages for editable vector graphics **Alternative Visualization Methods**: gpdb_plot_network : Use when you want gene-pathway network instead of dotplot. enrichplot::dotplot : Use for single-direction enrichment (not paired comparison). enrichplot::barplot : Use for simpler bar chart representation.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "enrich_result: gpdb_enrichment object from gpdb_enrich . Must contain $upregulated and $downregulated enrichment results.\nshow.term.num: Integer. Number of top pathways to display per panel (default: 15). Pathways ranked by p-value. Increase to 20-30 for comprehensive view, decrease to 5-10 for focus.\nuse.all: Logical. Plot all pathways or only significant ones (default: FALSE, significant only). Set TRUE to visualize trends even without significant enrichment (p < 0.05).\nx: Character. X-axis variable: \"FoldEnrich\" (enrichment ratio, default), \"pvalue\" (raw p-value), \"p.adjust\" (FDR-corrected), \"Count\" (gene count). \"FoldEnrich\" emphasizes biological magnitude; \"pvalue\" emphasizes statistical significance.\ncolor.by: Character. Variable mapped to point color: \"p.adjust\" (FDR, default), \"pvalue\", \"FoldEnrich\", \"Count\". Color gradient shows continuous scale.\nsize.by: Character. Variable mapped to point size: \"Count\" (gene count, default), \"pvalue\", \"p.adjust\", \"FoldEnrich\". Larger points indicate more genes or stronger significance.\ncolors: Character vector. Color palette for gradient (default: BrBG diverging palette). Provide custom colors like c(\"blue\", \"white\", \"red\") or use viridis scales. Reversed automatically for downregulated panel to maintain visual symmetry.\nsize.range: Numeric vector of length 2. Point size range in mm (default: c(3, 8)). Adjust for visual clarity: smaller range for dense plots, larger for emphasis.\ntitle: Character. Main plot title (default: auto-generated from database and ontology). Set to custom text or NULL to remove.\nup.title: Character. Title for upregulated panel (default: \"Upregulated Genes\").\ndown.title: Character. Title for downregulated panel (default: \"Downregulated Genes\").\nlegend.position: Character. Legend placement: \"right\" (default), \"bottom\", \"none\". Use \"bottom\" for wide plots, \"none\" to maximize plot area.\ntheme: ggplot2 theme object (default: theme_bw(base_rect_size = 1.5) ). Publication-ready theme with clean white background. Customize with theme_minimal() , etc.",
    "simple_arguments": "enrich_result: gpdb_enrichment object from gpdb_enrich . Must contain $upregulated and $downregulated enrichment results."
  },
  "gpdb_plot_heatmap_deg": {
    "package": "GenePerturbR",
    "function_name": "gpdb_plot_heatmap_deg",
    "title": "Compare Differential Expression Across Multiple Datasets with Heatmap",
    "description": "Create publication-ready heatmap comparing gene expression changes (log2FC) across multiple perturbation experiments. Each column represents one dataset, each row represents one gene. **Visualizes cross-dataset DEG patterns** for identifying consistent perturbation effects across cell lines, methods, or conditions.",
    "user_queries": ["How do I compare gene expression changes across multiple experiments?", "Which genes are consistently affected by TP53 perturbation in different cell lines?", "How do I visualize DEG patterns across multiple datasets?", "Can I create a heatmap comparing CRISPR vs siRNA knockdown effects?", "How do I identify cell-type-specific vs universal targets?", "What's the best way to visualize perturbation reproducibility?", "How do I cluster datasets by similar expression patterns?", "Can I show specific genes of interest across experiments?", "How do I compare the same perturbation in different tissues?", "What do the colors mean in cross-dataset heatmaps?", "How do I interpret z-score scaling in heatmaps?", "Should I use row or column scaling for my comparison?", "How do I identify genes with context-dependent regulation?", "Can I disable clustering to keep my dataset order?", "How many datasets should I include in heatmap comparison?", "What's the difference between DEG heatmap and expression heatmap?", "How do I export high-resolution heatmaps for publication?", "Can I customize the color palette for my heatmap?", "How do I handle missing values in cross-dataset comparisons?", "What size heatmap is optimal for readability?"],
    "usage": "gpdb_plot_heatmap_deg( dataset_ids, genes = NULL, top_n = 50, cluster_rows = TRUE, cluster_cols = TRUE, scale = \"row\", colors = NULL, show_values = FALSE, title = NULL, theme = NULL )",
    "parameters": [
      {
        "name": "dataset_ids",
        "has_default": false,
        "description": "Character vector. Dataset IDs from GPSAdb to compare (minimum 2 required). Default: None (required). Use gpdb_list_datasets() to find datasets for same gene. Example: c(\"D28200\", \"D28199\", \"D27994\") for comparing TP53 perturbations."
      },
      {
        "name": "genes",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character vector. Specific genes to visualize in heatmap. Default: NULL (auto-select top DEGs). Provide gene symbols to focus on genes of interest. Example: c(\"TP53\", \"MDM2\", \"CDKN1A\", \"BAX\") . Case-insensitive."
      },
      {
        "name": "top_n",
        "has_default": true,
        "default_value": "50",
        "description": "Integer. Number of top DEGs to show when genes not specified. Default: 50 . Range: 10-200. Auto-selects most significantly changed genes across datasets. Higher values show more genes but may reduce readability for large heatmaps."
      },
      {
        "name": "cluster_rows",
        "has_default": true,
        "default_value": "TRUE",
        "description": "Logical. Perform hierarchical clustering on genes (rows). Default: TRUE . Groups genes with similar expression patterns across datasets. Set FALSE to preserve gene order or when genes have specific ordering."
      },
      {
        "name": "cluster_cols",
        "has_default": true,
        "default_value": "TRUE",
        "description": "Logical. Perform hierarchical clustering on datasets (columns). Default: TRUE . Groups datasets with similar perturbation effects. Set FALSE to preserve dataset order (e.g., time series)."
      },
      {
        "name": "scale",
        "has_default": true,
        "default_value": "\"row\"",
        "description": "Character. Data scaling method for visualization. Default: \"row\" (z-score per gene). Options: \"row\", \"column\", \"none\". \"row\" scaling highlights relative changes across datasets; \"none\" shows raw log2FC values."
      },
      {
        "name": "colors",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character vector. Custom color palette for heatmap gradient. Default: NULL (uses 11-color spectral palette: blue-white-red). Provide vector of colors for custom gradient. Diverging palettes recommended for log2FC."
      },
      {
        "name": "show_values",
        "has_default": true,
        "default_value": "FALSE",
        "description": "Logical. Display numeric values in heatmap cells. Default: FALSE . Set TRUE for small heatmaps (<20 genes) to show exact values. Not recommended for large heatmaps due to overcrowding."
      },
      {
        "name": "title",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character. Custom plot title. Default: NULL (auto-generated: \"Gene Expression (N datasets)\"). Provide custom title to override."
      },
      {
        "name": "theme",
        "has_default": true,
        "default_value": "NULL",
        "description": "ggplot2 theme object. Custom theme for plot styling. Default: NULL (uses .gpdb_theme_default() , publication-ready academic theme). Can provide custom ggplot2 theme."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Cross-Dataset Comparison (TESTED - runtime: 0.55 sec)\n# ===========================================================================\n# Scientific Question: Which genes are consistently affected by TP53 perturbation?\n# Compare: TP53 knockdown/knockout across 5 different cell lines\n# Expected output: Heatmap showing 30 top DEGs × 5 datasets\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Find available TP53 perturbation datasets\ndatasets <- gpdb_list_datasets(gene = \"TP53\")\ncat(\"Found\", nrow(datasets), \"datasets for TP53\\n\")\n\n# Select first 5 datasets for comparison\ndataset_ids <- head(datasets$dataset_id, 5)\n\n# Create cross-dataset DEG heatmap\np1 <- gpdb_plot_heatmap_deg(\n  dataset_ids = dataset_ids,\n  top_n = 30, # Show top 30 DEGs\n  cluster_rows = TRUE, # Cluster genes\n  cluster_cols = TRUE # Cluster datasets\n)\n\n# Plot is ready\nprint(p1)\n\n# Save to file\n# ggplot2::ggsave(\"tp53_heatmap.pdf\", p1, width = 10, height = 8)\n\n# ===========================================================================\n# Example 2: Focus on Specific Genes (Pathway-Centric)\n# ===========================================================================\n# Question: How do TP53 target genes respond across different contexts?\n# Focus on known TP53 pathway genes\n\n# Define TP53 pathway genes\ntp53_targets <- c(\n  \"CDKN1A\", # p21, cell cycle arrest\n  \"MDM2\", # Negative regulator\n  \"BAX\", # Apoptosis\n  \"PUMA\", # Apoptosis (BBC3)\n  \"NOXA\", # Apoptosis (PMAIP1)\n  \"GADD45A\", # DNA repair\n  \"TP53INP1\" # Cell cycle\n)\n\np2 <- gpdb_plot_heatmap_deg(\n  dataset_ids = dataset_ids,\n  genes = tp53_targets, # Specific genes only\n  cluster_rows = TRUE, # Group by expression pattern\n  scale = \"row\" # Z-score per gene\n)\n\n# Identify consistent vs variable targets\ncat(\"Heatmap shows which TP53 targets are universally vs context-specifically regulated\\n\")\n\n# ===========================================================================\n# Example 3: Compare Different Perturbation Methods\n# ===========================================================================\n# Question: Are CRISPR and siRNA knockdowns comparable?\n\n# Get datasets with different methods\ndatasets_all <- gpdb_list_datasets(gene = \"TP53\")\n\n# Select mix of methods (example)\n# Note: In real analysis, filter by 'method' column in datasets\ncrispr_ids <- datasets_all$dataset_id[grep(\"CRISPR\", datasets_all$method, ignore.case = TRUE)]\nsirna_ids <- datasets_all$dataset_id[grep(\"siRNA\", datasets_all$method, ignore.case = TRUE)]\n\n# Mix methods for comparison\nmixed_ids <- c(head(crispr_ids, 3), head(sirna_ids, 3))\n\nif (length(mixed_ids) >= 2) {\n  p3 <- gpdb_plot_heatmap_deg(\n    dataset_ids = mixed_ids,\n    top_n = 40,\n    cluster_cols = TRUE, # Will group by method similarity\n    title = \"TP53 Perturbation: CRISPR vs siRNA\"\n  )\n\n  cat(\"Check if datasets cluster by method (CRISPR vs siRNA)\\n\")\n}\n\n# ===========================================================================\n# Example 4: Customize Appearance\n# ===========================================================================\n# Publication-ready customization\n\n# Custom diverging color palette (RdBu - colorblind friendly)\nlibrary(ggplot2)\n\np4 <- gpdb_plot_heatmap_deg(\n  dataset_ids = dataset_ids,\n  top_n = 25,\n  scale = \"row\",\n  cluster_rows = TRUE,\n  cluster_cols = FALSE, # Keep dataset order\n  title = \"TP53 Target Gene Expression Across Cell Lines\"\n)\n\n# Further customization with ggplot2\np4_custom <- p4 +\n  theme(\n    axis.text.x = element_text(angle = 45, hjust = 1, size = 10),\n    axis.text.y = element_text(size = 8),\n    plot.title = element_text(size = 14, face = \"bold\")\n  ) +\n  labs(caption = \"Data source: GPSAdb\")\n\n# ===========================================================================\n# Example 5: Compare Same Gene Across Tissues\n# ===========================================================================\n# Question: Is TP53 effect tissue-specific?\n\n# Get dataset info to filter by tissue\nall_tp53 <- gpdb_list_datasets(gene = \"TP53\")\n\n# Example: Compare specific tissues (if available)\n# Note: Filter by tissue_type or cell_line in real analysis\ntissue_ids <- head(all_tp53$dataset_id, 6)\n\np5 <- gpdb_plot_heatmap_deg(\n  dataset_ids = tissue_ids,\n  top_n = 35,\n  cluster_cols = TRUE, # Cluster by tissue similarity\n  scale = \"row\",\n  title = \"TP53 Effects: Tissue Comparison\"\n)\n\ncat(\"Look for tissue-specific gene signatures in clustering\\n\")\n\n# ===========================================================================\n# Next Steps (Workflow Integration)\n# ===========================================================================\n# For complete workflows, see:\n# - Find datasets: ?gpdb_list_datasets\n# - Load batch DEGs: ?gpdb_load_batch\n# - Enrich consistent genes: ?gpdb_enrich\n# - Single dataset detail: ?gpdb_plot_volcano\n# - Network analysis: ?gpdb_plot_network\n## End(No test)\n\n\n\n",
    "return_value": "ggplot object showing DEG heatmap for cross-dataset comparison. **Plot Elements**: Rows Genes (auto-selected top DEGs or user-specified) Columns Datasets (each experiment/perturbation) Color Expression change (blue = downregulated, red = upregulated, white = no change) Scaling Default z-score normalization per gene for cross-dataset comparability Clustering Hierarchical clustering groups similar patterns (optional) **What You Can Do Next**: Save plot: ggplot2::ggsave(\"heatmap_deg.pdf\", p, width = 10, height = 8) Extract gene clusters: Identify genes with consistent up/down regulation Focus on specific genes: Re-plot with genes parameter for targets Compare conditions: Use to compare same gene across cell lines or methods Enrichment analysis: Feed consistent DEGs to gpdb_enrich() Investigate outliers: Identify datasets with unique expression patterns Single dataset detail: Use gpdb_plot_volcano() for individual dataset exploration **Alternative Visualizations**: gpdb_plot_heatmap_expr : Sample-level expression heatmap for ONE dataset. Use when: Need to see individual sample variation within experiment. gpdb_plot_volcano : Volcano plot for ONE dataset. Use when: Want to identify significant DEGs in single experiment. gpdb_plot_network : Gene regulatory network visualization. Use when: Exploring gene-gene relationships and regulatory interactions.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "dataset_ids: Character vector. Dataset IDs from GPSAdb to compare (minimum 2 required). Default: None (required). Use gpdb_list_datasets() to find datasets for same gene. Example: c(\"D28200\", \"D28199\", \"D27994\") for comparing TP53 perturbations.\ngenes: Character vector. Specific genes to visualize in heatmap. Default: NULL (auto-select top DEGs). Provide gene symbols to focus on genes of interest. Example: c(\"TP53\", \"MDM2\", \"CDKN1A\", \"BAX\") . Case-insensitive.\ntop_n: Integer. Number of top DEGs to show when genes not specified. Default: 50 . Range: 10-200. Auto-selects most significantly changed genes across datasets. Higher values show more genes but may reduce readability for large heatmaps.\ncluster_rows: Logical. Perform hierarchical clustering on genes (rows). Default: TRUE . Groups genes with similar expression patterns across datasets. Set FALSE to preserve gene order or when genes have specific ordering.\ncluster_cols: Logical. Perform hierarchical clustering on datasets (columns). Default: TRUE . Groups datasets with similar perturbation effects. Set FALSE to preserve dataset order (e.g., time series).\nscale: Character. Data scaling method for visualization. Default: \"row\" (z-score per gene). Options: \"row\", \"column\", \"none\". \"row\" scaling highlights relative changes across datasets; \"none\" shows raw log2FC values.\ncolors: Character vector. Custom color palette for heatmap gradient. Default: NULL (uses 11-color spectral palette: blue-white-red). Provide vector of colors for custom gradient. Diverging palettes recommended for log2FC.\nshow_values: Logical. Display numeric values in heatmap cells. Default: FALSE . Set TRUE for small heatmaps (<20 genes) to show exact values. Not recommended for large heatmaps due to overcrowding.\ntitle: Character. Custom plot title. Default: NULL (auto-generated: \"Gene Expression (N datasets)\"). Provide custom title to override.\ntheme: ggplot2 theme object. Custom theme for plot styling. Default: NULL (uses .gpdb_theme_default() , publication-ready academic theme). Can provide custom ggplot2 theme.",
    "simple_arguments": "dataset_ids: Character vector. Dataset IDs from GPSAdb to compare (minimum 2 required). Default: None (required). Use gpdb_list_datasets() to find datasets for same gene. Example: c(\"D28200\", \"D28199\", \"D27994\") for comparing TP53 perturbations."
  },
  "gpdb_plot_heatmap_expr": {
    "package": "GenePerturbR",
    "function_name": "gpdb_plot_heatmap_expr",
    "title": "Visualize Sample-Level Expression with Heatmap for Single Dataset",
    "description": "Create publication-ready heatmap showing raw expression values across samples within a single perturbation experiment. Each column represents one sample (control or treatment), each row represents one gene. **Visualizes sample-to-sample variation** for top upregulated and downregulated genes with automatic sample group annotations.",
    "user_queries": ["How do I visualize gene expression across samples in my experiment?", "How do I check if control and treatment samples cluster separately?", "Can I see which genes show consistent expression patterns across replicates?", "How do I identify outlier samples in my perturbation experiment?", "What's the difference between expression heatmap and DEG heatmap?", "How do I visualize top upregulated and downregulated genes?", "Can I create a heatmap showing sample-to-sample variation?", "How do I assess replicate consistency in RNA-seq data?", "What do the colors mean in sample-level expression heatmaps?", "How do I interpret hierarchical clustering of samples?", "Should I use row or column scaling for expression heatmaps?", "How many genes should I include in the heatmap?", "Can I disable gene name labels for cleaner visualization?", "How do I check quality control of my perturbation experiment?", "What indicates a successful perturbation in expression heatmap?", "How do I identify co-expressed gene modules?", "Can I customize which genes to show in the heatmap?", "How do I export high-resolution heatmaps for publication?", "What's the best visualization for within-experiment variation?", "How do I validate DEG results visually?"],
    "usage": "gpdb_plot_heatmap_expr( dataset_id, top_up = 20, top_down = 20, scale = \"row\", cluster_rows = TRUE, cluster_cols = TRUE, show_gene_names = TRUE, colors = NULL, show_values = FALSE, title = NULL, theme = NULL )",
    "parameters": [
      {
        "name": "dataset_id",
        "has_default": false,
        "description": "Character. Dataset ID from GPSAdb to visualize. Default: None (required). Use gpdb_list_datasets() to find available datasets. Example: \"D28200\" for TP53 siRNA in PANC-1 cells."
      },
      {
        "name": "top_up",
        "has_default": true,
        "default_value": "20",
        "description": "Integer. Number of top upregulated genes to show. Default: 20 . Range: 5-50. Genes ranked by log2 fold change (highest first). Higher values show more upregulated genes but may reduce readability."
      },
      {
        "name": "top_down",
        "has_default": true,
        "default_value": "20",
        "description": "Integer. Number of top downregulated genes to show. Default: 20 . Range: 5-50. Genes ranked by log2 fold change (lowest first). Total genes displayed = top_up + top_down."
      },
      {
        "name": "scale",
        "has_default": true,
        "default_value": "\"row\"",
        "description": "Character. Data scaling method for visualization. Default: \"row\" (z-score per gene). Options: \"row\", \"column\", \"none\". \"row\" scaling highlights relative expression across samples; \"none\" shows raw normalized expression."
      },
      {
        "name": "cluster_rows",
        "has_default": true,
        "default_value": "TRUE",
        "description": "Logical. Perform hierarchical clustering on genes (rows). Default: TRUE . Groups genes with similar expression patterns across samples. Set FALSE to preserve up/down gene ordering."
      },
      {
        "name": "cluster_cols",
        "has_default": true,
        "default_value": "TRUE",
        "description": "Logical. Perform hierarchical clustering on samples (columns). Default: TRUE . Groups samples by expression similarity (may separate control vs treatment). Set FALSE to preserve sample order from metadata."
      },
      {
        "name": "show_gene_names",
        "has_default": true,
        "default_value": "TRUE",
        "description": "Logical. Display gene names on y-axis. Default: TRUE . Set FALSE for cleaner appearance when showing many genes (>40)."
      },
      {
        "name": "colors",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character vector. Custom color palette for heatmap gradient. Default: NULL (uses 11-color spectral palette: blue-white-red). Provide vector of colors for custom gradient."
      },
      {
        "name": "show_values",
        "has_default": true,
        "default_value": "FALSE",
        "description": "Logical. Display numeric values in heatmap cells. Default: FALSE . Set TRUE for small heatmaps (<20 genes) to show exact values. Not recommended for large heatmaps due to overcrowding."
      },
      {
        "name": "title",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character. Custom plot title. Default: NULL (auto-generated: \"Gene in CellLine (Method)\"). Provide custom title to override."
      },
      {
        "name": "theme",
        "has_default": true,
        "default_value": "NULL",
        "description": "ggplot2 theme object. Custom theme for plot styling. Default: NULL (uses .gpdb_theme_default() , publication-ready academic theme). Can provide custom ggplot2 theme."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Sample-Level Expression Heatmap (TESTED - runtime: 1.04 sec)\n# ===========================================================================\n# Scientific Question: Do control and treatment samples cluster separately?\n# Dataset: TP53 siRNA in PANC-1 cells (3 control + 3 treatment samples)\n# Expected output: Heatmap showing 39 genes (20 up + 19 down) × 6 samples\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Find available datasets\ndatasets <- gpdb_list_datasets(gene = \"TP53\")\ncat(\"Found\", nrow(datasets), \"datasets for TP53\\n\")\n\n# Select first dataset\ndataset_id <- datasets$dataset_id[1]\n\n# Get dataset info\ninfo <- gpdb_get_info(dataset_id)\ncat(\"Dataset:\", info$gene, \"in\", info$cell_line, \"\\n\")\ncat(\n  \"Samples:\", info$n_samples, \"(\", info$n_control, \"control +\",\n  info$n_treat, \"treatment)\\n\"\n)\n\n# Create sample-level expression heatmap\np1 <- gpdb_plot_heatmap_expr(\n  dataset_id = dataset_id,\n  top_up = 20, # Top 20 upregulated genes\n  top_down = 20, # Top 20 downregulated genes\n  scale = \"row\", # Z-score per gene\n  cluster_rows = TRUE, # Cluster genes\n  cluster_cols = TRUE # Cluster samples\n)\n\n# Plot is ready\nprint(p1)\n\n# Check: Do treatment samples cluster together?\ncat(\"Check column dendrogram to verify sample grouping\\n\")\n\n# Save to file\n# ggplot2::ggsave(\"expression_heatmap.pdf\", p1, width = 10, height = 12)\n\n# ===========================================================================\n# Example 2: Customize Gene Number for Focused View\n# ===========================================================================\n# Focus on fewer genes for cleaner visualization\n\n# Small focused heatmap (top 10 up + down)\np2_small <- gpdb_plot_heatmap_expr(\n  dataset_id = dataset_id,\n  top_up = 10, # Fewer genes\n  top_down = 10,\n  scale = \"row\"\n)\n\n# Large comprehensive heatmap (top 30 up + down)\np2_large <- gpdb_plot_heatmap_expr(\n  dataset_id = dataset_id,\n  top_up = 30, # More genes\n  top_down = 30,\n  scale = \"row\",\n  show_gene_names = FALSE # Hide labels for many genes\n)\n\n# ===========================================================================\n# Example 3: Disable Clustering to Preserve Ordering\n# ===========================================================================\n# Keep genes ordered by fold change (up at top, down at bottom)\n\np3 <- gpdb_plot_heatmap_expr(\n  dataset_id = dataset_id,\n  top_up = 15,\n  top_down = 15,\n  cluster_rows = FALSE, # Preserve up/down ordering\n  cluster_cols = FALSE, # Preserve sample order from metadata\n  scale = \"row\"\n)\n\ncat(\"Genes ordered by fold change: upregulated (top) → downregulated (bottom)\\n\")\n\n# ===========================================================================\n# Example 4: Compare Different Scaling Methods\n# ===========================================================================\n# Understand impact of scaling on visualization\n\n# Row scaling (default) - compare across samples\np4_row <- gpdb_plot_heatmap_expr(\n  dataset_id = dataset_id,\n  top_up = 15,\n  top_down = 15,\n  scale = \"row\", # Z-score per gene\n  title = \"Row Scaling: Z-score per Gene\"\n)\n\n# No scaling - raw normalized values\np4_none <- gpdb_plot_heatmap_expr(\n  dataset_id = dataset_id,\n  top_up = 15,\n  top_down = 15,\n  scale = \"none\", # Raw log2(CPM+1)\n  title = \"No Scaling: Raw Expression\"\n)\n\n# Row scaling emphasizes relative changes; no scaling shows absolute levels\n\n# ===========================================================================\n# Example 5: Quality Control Check\n# ===========================================================================\n# Identify potential issues with samples or perturbation\n\n# Create heatmap\np5 <- gpdb_plot_heatmap_expr(\n  dataset_id = dataset_id,\n  top_up = 20,\n  top_down = 20,\n  cluster_cols = TRUE # Enable sample clustering\n)\n\n# Interpretation guide:\ncat(\"\\n=== Quality Control Checklist ===\\n\")\ncat(\"✓ Control samples cluster together?\\n\")\ncat(\"✓ Treatment samples cluster together?\\n\")\ncat(\"✓ Clear separation between groups?\\n\")\ncat(\"✓ Upregulated genes show high expression in treatment?\\n\")\ncat(\"✓ Downregulated genes show low expression in treatment?\\n\")\ncat(\"✓ Consistent patterns across replicates?\\n\")\n\n# ===========================================================================\n# Example 6: Combine with Volcano Plot for Validation\n# ===========================================================================\n# Cross-validate DEG results between volcano and expression heatmap\n\n# Load DEG results to identify top genes\ndeg_data <- gpdb_load_deg(dataset_id)\ntop_genes <- head(deg_data$gene[order(deg_data$adj.P.Val)], 10)\ncat(\"Top 10 significant genes:\", paste(top_genes, collapse = \", \"), \"\\n\")\n\n# Create volcano plot\np6_volcano <- gpdb_plot_volcano(\n  dataset_id = dataset_id,\n  highlight_genes = top_genes\n)\n\n# Create expression heatmap\np6_heatmap <- gpdb_plot_heatmap_expr(\n  dataset_id = dataset_id,\n  top_up = 15,\n  top_down = 15\n)\n\n# Compare: Genes significant in volcano should show clear patterns in heatmap\n\n# ===========================================================================\n# Next Steps (Workflow Integration)\n# ===========================================================================\n# For complete workflows, see:\n# - Load expression data: ?gpdb_load_data\n# - Volcano plot: ?gpdb_plot_volcano\n# - Cross-dataset comparison: ?gpdb_plot_heatmap_deg\n# - Enrichment analysis: ?gpdb_enrich\n# - Network visualization: ?gpdb_plot_network\n## End(No test)\n\n\n\n",
    "return_value": "ggplot object showing sample-level expression heatmap for single dataset. **Plot Elements**: Rows Genes (top upregulated + top downregulated from DEG analysis) Columns Samples (individual replicates from control and treatment groups) Color Expression level (blue = low, white = medium, red = high) Scaling Default z-score normalization per gene for visualizing relative changes Clustering Hierarchical clustering reveals sample groupings and gene modules Annotations Row annotation shows Up/Down status; column annotation shows sample groups **What You Can Do Next**: Save plot: ggplot2::ggsave(\"heatmap_expr.pdf\", p, width = 10, height = 12) Check sample clustering: Verify control and treatment samples cluster separately Identify outliers: Spot samples with unusual expression patterns Extract gene groups: Find co-expressed gene modules from row clustering Validate targets: Confirm top DEG genes show clear treatment effects Quality control: Assess technical variation within groups Compare with DEG: Cross-reference with gpdb_plot_volcano() for same dataset **Alternative Visualizations**: gpdb_plot_volcano : Volcano plot for identifying significant DEGs in same dataset. Use when: Want to see fold change vs significance for all genes. gpdb_plot_heatmap_deg : DEG heatmap across multiple datasets. Use when: Comparing expression changes (log2FC) across experiments, not within-sample variation. gpdb_plot_network : Gene regulatory network visualization. Use when: Exploring gene-gene regulatory relationships.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "dataset_id: Character. Dataset ID from GPSAdb to visualize. Default: None (required). Use gpdb_list_datasets() to find available datasets. Example: \"D28200\" for TP53 siRNA in PANC-1 cells.\ntop_up: Integer. Number of top upregulated genes to show. Default: 20 . Range: 5-50. Genes ranked by log2 fold change (highest first). Higher values show more upregulated genes but may reduce readability.\ntop_down: Integer. Number of top downregulated genes to show. Default: 20 . Range: 5-50. Genes ranked by log2 fold change (lowest first). Total genes displayed = top_up + top_down.\nscale: Character. Data scaling method for visualization. Default: \"row\" (z-score per gene). Options: \"row\", \"column\", \"none\". \"row\" scaling highlights relative expression across samples; \"none\" shows raw normalized expression.\ncluster_rows: Logical. Perform hierarchical clustering on genes (rows). Default: TRUE . Groups genes with similar expression patterns across samples. Set FALSE to preserve up/down gene ordering.\ncluster_cols: Logical. Perform hierarchical clustering on samples (columns). Default: TRUE . Groups samples by expression similarity (may separate control vs treatment). Set FALSE to preserve sample order from metadata.\nshow_gene_names: Logical. Display gene names on y-axis. Default: TRUE . Set FALSE for cleaner appearance when showing many genes (>40).\ncolors: Character vector. Custom color palette for heatmap gradient. Default: NULL (uses 11-color spectral palette: blue-white-red). Provide vector of colors for custom gradient.\nshow_values: Logical. Display numeric values in heatmap cells. Default: FALSE . Set TRUE for small heatmaps (<20 genes) to show exact values. Not recommended for large heatmaps due to overcrowding.\ntitle: Character. Custom plot title. Default: NULL (auto-generated: \"Gene in CellLine (Method)\"). Provide custom title to override.\ntheme: ggplot2 theme object. Custom theme for plot styling. Default: NULL (uses .gpdb_theme_default() , publication-ready academic theme). Can provide custom ggplot2 theme.",
    "simple_arguments": "dataset_id: Character. Dataset ID from GPSAdb to visualize. Default: None (required). Use gpdb_list_datasets() to find available datasets. Example: \"D28200\" for TP53 siRNA in PANC-1 cells."
  },
  "gpdb_plot_network": {
    "package": "GenePerturbR",
    "function_name": "gpdb_plot_network",
    "title": "Visualize Gene Regulatory Network with Upstream and Downstream Relationships",
    "description": "Construct and visualize bidirectional regulatory network showing both upstream regulators (genes that control focal gene) and downstream targets (genes regulated by focal gene), aggregated from 7,665 RNA-seq perturbation experiments for pathway mapping and regulatory cascade analysis. **Database covers 2,810 genes across 1,063 cell lines** with multi-dataset evidence supporting each regulatory edge. Returns publication-ready network graph with color-coded nodes (focal gene, regulators, targets) and effect-based edge styling (activation/repression).",
    "user_queries": ["How to visualize which genes regulate my gene of interest?", "What genes are controlled by TP53 knockout in cancer cells?", "Can I see both upstream and downstream regulatory relationships?", "How do I identify master regulators in my network?", "Which layout is best for finding regulatory modules?", "How to adjust network size for publication figures?", "What do the edge colors mean in the network plot?", "How reliable are the regulatory relationships shown?", "Can I export the network for Cytoscape analysis?", "How to trace regulatory cascades from the network?", "What if my network is too dense to read?", "How to compare networks of different genes?", "Can I filter edges by effect size or confidence?", "How to identify feedback loops in the network?", "Which genes are the most connected hubs?", "How to validate regulatory edges with raw data?", "Can I customize node colors and edge styles?", "What cell types are represented in the network?", "How to find tissue-specific regulatory relationships?", "Can I overlay pathway annotations on the network?"],
    "usage": "gpdb_plot_network( gene, top_regulators = 10, top_targets = 10, min_confidence = \"medium\", layout = c(\"fr\", \"circle\", \"star\"), node_size = 8, edge_width = 1, show_labels = TRUE, title = NULL, theme = NULL )",
    "parameters": [
      {
        "name": "gene",
        "has_default": false,
        "description": "Character. Gene symbol for focal node (e.g., \"TP53\", \"MYC\"). Must exist in database (use gpdb_search() to verify). Case-insensitive."
      },
      {
        "name": "top_regulators",
        "has_default": true,
        "default_value": "10",
        "description": "Integer. Number of top upstream regulators to display. Default: 10 . Range: 5-50 recommended. Higher values show more comprehensive regulatory inputs but increase visual complexity."
      },
      {
        "name": "top_targets",
        "has_default": true,
        "default_value": "10",
        "description": "Integer. Number of top downstream targets to display. Default: 10 . Range: 5-50 recommended. Higher values reveal broader regulatory impact but may clutter visualization."
      },
      {
        "name": "min_confidence",
        "has_default": true,
        "default_value": "\"medium\"",
        "description": "Character. Evidence strength filter for edges (\"high\", \"medium\", \"low\"). Default: \"medium\" . Options: \"high\" (5+ datasets, publication-grade), \"medium\" (2-4 datasets), \"low\" (1 dataset, exploratory). Higher confidence reduces false positives; lower captures emerging regulatory relationships."
      },
      {
        "name": "layout",
        "has_default": true,
        "default_value": "c(\"fr\", \"circle\", \"star\")",
        "description": "Character. Network layout algorithm: \"fr\" (force-directed, default), \"circle\", \"star\". Default: \"fr\" . Options: \"fr\" (Fruchterman-Reingold, reveals clusters), \"circle\" (equal spacing), \"star\" (focal gene centered). Force-directed layout best for identifying regulatory modules; star layout emphasizes hub structure."
      },
      {
        "name": "node_size",
        "has_default": true,
        "default_value": "8",
        "description": "Numeric. Base size of nodes in mm. Default: 8 . Range: 5-15 recommended. Node size scales with degree (connectivity) automatically."
      },
      {
        "name": "edge_width",
        "has_default": true,
        "default_value": "1",
        "description": "Numeric. Base width of edges in mm. Default: 1 . Range: 0.5-3 recommended. Edge width scales with effect size (|logFC|) automatically."
      },
      {
        "name": "show_labels",
        "has_default": true,
        "default_value": "TRUE",
        "description": "Logical. Display gene symbol labels on nodes. Default: TRUE . Set to FALSE for dense networks (>100 nodes) to reduce overlap."
      },
      {
        "name": "title",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character. Custom plot title. Default: NULL (auto-generates \"Regulatory Network of [gene]\")."
      },
      {
        "name": "theme",
        "has_default": true,
        "default_value": "NULL",
        "description": "ggplot2 theme object. Custom theme for plot styling. Default: NULL (uses .gpdb_theme_default() academic publication theme)."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage (TESTED - runtime: 0.85 sec)\n# ===========================================================================\n# Scientific Question: What are the regulatory inputs and outputs of TP53?\n# Query: TP53 regulatory network with high-confidence edges\n# Expected output: Network graph with TP53 as focal hub\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\np <- gpdb_plot_network(\n  gene = \"TP53\",\n  top_regulators = 10,\n  top_targets = 10,\n  min_confidence = \"high\"\n)\n\n# Display network\nprint(p)\n\n# Check network structure\n# Message shows: \"Network: 40 edges, 40 nodes\"\n\n# Interpretation:\n# - Red node: TP53 (focal gene)\n# - Blue nodes: Upstream regulators (control TP53)\n# - Green nodes: Downstream targets (regulated by TP53)\n# - Green arrows: Activation\n# - Red arrows: Repression\n\n# ===========================================================================\n# Example 2: Layout Comparison (Show impact of layout algorithms)\n# ===========================================================================\n# Compare different layouts to reveal network structure\n\n# Force-directed layout: Reveals regulatory modules\np_fr <- gpdb_plot_network(\n  gene = \"MYC\",\n  top_regulators = 15,\n  top_targets = 15,\n  layout = \"fr\", # Default, good for clustering\n  min_confidence = \"medium\"\n)\n\n# Star layout: Emphasizes hub structure\np_star <- gpdb_plot_network(\n  gene = \"MYC\",\n  top_regulators = 15,\n  top_targets = 15,\n  layout = \"star\", # Focal gene centered\n  min_confidence = \"medium\"\n)\n\n# Circle layout: Equal spacing for counting edges\np_circle <- gpdb_plot_network(\n  gene = \"MYC\",\n  top_regulators = 15,\n  top_targets = 15,\n  layout = \"circle\", # Uniform distribution\n  min_confidence = \"medium\"\n)\n\n# Display side-by-side comparison\nlibrary(patchwork)\np_fr + p_star + p_circle + plot_layout(ncol = 3)\n\n# ===========================================================================\n# Example 3: Confidence Level Impact (Filter by evidence strength)\n# ===========================================================================\n# Compare how confidence filtering affects network\n\n# High confidence: Publication-grade evidence only\np_high <- gpdb_plot_network(\n  gene = \"EGFR\",\n  top_regulators = 20,\n  top_targets = 20,\n  min_confidence = \"high\", # 5+ datasets, most reliable\n  title = \"EGFR Network (High Confidence)\"\n)\n\n# Medium confidence: Include moderate evidence\np_medium <- gpdb_plot_network(\n  gene = \"EGFR\",\n  top_regulators = 20,\n  top_targets = 20,\n  min_confidence = \"medium\", # 2-4 datasets\n  title = \"EGFR Network (Medium Confidence)\"\n)\n\n# Compare network sizes\nprint(p_high) # Fewer edges, higher reliability\nprint(p_medium) # More edges, broader coverage\n\n# ===========================================================================\n# Example 4: Customize Visualization (Adjust aesthetics)\n# ===========================================================================\n# Fine-tune network appearance for publication\n\np_custom <- gpdb_plot_network(\n  gene = \"KRAS\",\n  top_regulators = 12,\n  top_targets = 12,\n  layout = \"fr\",\n  node_size = 10, # Larger nodes\n  edge_width = 1.5, # Thicker edges\n  show_labels = TRUE, # Show gene names\n  min_confidence = \"high\",\n  title = \"KRAS Regulatory Network in Cancer\"\n)\n\n# Further customize (ggplot layers work!)\np_custom <- p_custom +\n  ggplot2::theme(\n    plot.title = ggplot2::element_text(size = 16, face = \"bold\"),\n    legend.position = \"bottom\"\n  )\n\nprint(p_custom)\n\n# Save high-resolution figure\nggplot2::ggsave(\"kras_network.pdf\", p_custom, width = 10, height = 8)\n\n# ===========================================================================\n# Example 5: Extract Network Data (Export for external tools)\n# ===========================================================================\n# Get underlying igraph object for advanced analysis\n\np <- gpdb_plot_network(\"BRCA1\", top_regulators = 20, top_targets = 20)\n\n# Extract graph data (requires accessing internal structure)\n# Note: ggraph embeds igraph object in plot data\n\n# Alternative: Query data directly\nregulators <- gpdb_find_regulators(\"BRCA1\", top_n = 20, min_confidence = \"high\")\ntargets <- gpdb_find_targets(\"BRCA1\", top_n = 20, min_confidence = \"high\")\n\n# Build edge list for Cytoscape\nedges_up <- data.frame(\n  source = \"BRCA1\",\n  target = targets$upregulated$target_gene,\n  interaction = \"activates\",\n  weight = targets$upregulated$logfc_mean\n)\n\nedges_down <- data.frame(\n  source = \"BRCA1\",\n  target = targets$downregulated$target_gene,\n  interaction = \"represses\",\n  weight = targets$downregulated$logfc_mean\n)\n\nall_edges <- rbind(edges_up, edges_down)\n\n# Export for Cytoscape\nwrite.csv(all_edges, \"brca1_network_edges.csv\", row.names = FALSE)\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# For complete workflows, see:\n# - Regulatory cascades: ?gpdb_analyze_cascade\n# - Pathway enrichment: ?gpdb_enrich\n# - Compare networks: ?gpdb_compare_genes\n# - Validate edges: ?gpdb_load_data\n# - Sequential visualization: ?gpdb_plot_cascade\n## End(No test)\n\n\n\n",
    "return_value": "ggraph/ggplot object with interactive network visualization. **Network Structure**: Nodes Genes colored by role: Red: Focal gene (query) Blue: Regulators (upstream, control focal gene) Green: Targets (downstream, regulated by focal gene) Node size scales with connectivity degree. Edges Directed regulatory relationships colored by effect: Green arrows: Activation (positive regulation) Red arrows: Repression (negative regulation) Edge width/transparency scale with effect size (|logFC|). **What You Can Do Next**: Identify key hubs: Nodes with high connectivity are master regulators Trace regulatory paths: Use gpdb_analyze_cascade for multi-step regulation Validate relationships: Use gpdb_load_data to check raw expression data Expand network: Increase top_regulators / top_targets to reveal broader network Export for Cytoscape: Extract graph data with igraph::as_data_frame(p$data) Customize visualization: Modify returned ggplot object (add layers, change theme) **Alternative Methods**: gpdb_analyze_cascade : Use when tracing multi-step regulatory cascades (A→B→C) gpdb_plot_cascade : Use when visualizing sequential regulatory steps with pathway context gpdb_find_regulators : Use when only upstream regulators are needed (tabular output) gpdb_find_targets : Use when only downstream targets are needed (tabular output)",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "gene: Character. Gene symbol for focal node (e.g., \"TP53\", \"MYC\"). Must exist in database (use gpdb_search() to verify). Case-insensitive.\ntop_regulators: Integer. Number of top upstream regulators to display. Default: 10 . Range: 5-50 recommended. Higher values show more comprehensive regulatory inputs but increase visual complexity.\ntop_targets: Integer. Number of top downstream targets to display. Default: 10 . Range: 5-50 recommended. Higher values reveal broader regulatory impact but may clutter visualization.\nmin_confidence: Character. Evidence strength filter for edges (\"high\", \"medium\", \"low\"). Default: \"medium\" . Options: \"high\" (5+ datasets, publication-grade), \"medium\" (2-4 datasets), \"low\" (1 dataset, exploratory). Higher confidence reduces false positives; lower captures emerging regulatory relationships.\nlayout: Character. Network layout algorithm: \"fr\" (force-directed, default), \"circle\", \"star\". Default: \"fr\" . Options: \"fr\" (Fruchterman-Reingold, reveals clusters), \"circle\" (equal spacing), \"star\" (focal gene centered). Force-directed layout best for identifying regulatory modules; star layout emphasizes hub structure.\nnode_size: Numeric. Base size of nodes in mm. Default: 8 . Range: 5-15 recommended. Node size scales with degree (connectivity) automatically.\nedge_width: Numeric. Base width of edges in mm. Default: 1 . Range: 0.5-3 recommended. Edge width scales with effect size (|logFC|) automatically.\nshow_labels: Logical. Display gene symbol labels on nodes. Default: TRUE . Set to FALSE for dense networks (>100 nodes) to reduce overlap.\ntitle: Character. Custom plot title. Default: NULL (auto-generates \"Regulatory Network of [gene]\").\ntheme: ggplot2 theme object. Custom theme for plot styling. Default: NULL (uses .gpdb_theme_default() academic publication theme).",
    "simple_arguments": "gene: Character. Gene symbol for focal node (e.g., \"TP53\", \"MYC\"). Must exist in database (use gpdb_search() to verify). Case-insensitive."
  },
  "gpdb_plot_volcano": {
    "package": "GenePerturbR",
    "function_name": "gpdb_plot_volcano",
    "title": "Visualize Differential Expression with Volcano Plot",
    "description": "Create publication-ready volcano plot showing gene expression changes from a single perturbation experiment. Displays log2 fold change vs -log10(adjusted p-value) with automatic gene labeling and classification. **Visualizes DEG results from one dataset** (17,000+ genes per experiment) for identifying most significantly changed genes.",
    "user_queries": ["How do I visualize differential expression results from my perturbation experiment?", "What genes are most significantly changed after TP53 knockout?", "How do I create a publication-ready volcano plot?", "Can I highlight specific genes of interest in the volcano plot?", "How do I adjust significance thresholds for volcano plots?", "What do the colors and sizes mean in a volcano plot?", "How do I compare DEG patterns across different datasets visually?", "Which genes should I focus on for downstream validation?", "How do I customize volcano plot colors for my presentation?", "What's the difference between adjusted p-value and fold change thresholds?", "How do I export high-resolution volcano plots for publication?", "Can I plot multiple datasets side-by-side for comparison?", "How do I interpret volcano plot quadrants biologically?", "What threshold values are recommended for drug target discovery?", "How do I label more genes or disable auto-labeling?", "Can I change the theme for dark background presentations?", "How do I identify outlier genes with extreme fold changes?", "What's the best way to show subtle but significant changes?", "How do I overlay pathway-specific genes on volcano plot?", "Can I use volcano plots for comparing different perturbation methods?"],
    "usage": "gpdb_plot_volcano( dataset_id, padj_cutoff = 0.05, logfc_cutoff = 1, nlabel = 10, highlight_genes = NULL, colors = NULL, point.maxsize = 4, point.alpha = 0.8, intercept.width = 0.65, label.size = 3.5, label.bg = \"white\", label.bg.r = 0.1, legend.position = \"bottom\", title = NULL, theme.plot = NULL )",
    "parameters": [
      {
        "name": "dataset_id",
        "has_default": false,
        "description": "Character. Dataset ID from GPSAdb (e.g., \"D28200\"). Default: None (required). Use gpdb_list_datasets() to find available datasets. Each dataset represents one perturbation experiment (gene knockout/knockdown)."
      },
      {
        "name": "padj_cutoff",
        "has_default": true,
        "default_value": "0.05",
        "description": "Numeric. Adjusted p-value significance threshold. Default: 0.05 . Range: 0-1. Genes below this threshold are considered significant. Lower values (0.01) give higher confidence; higher values (0.1) include more candidates."
      },
      {
        "name": "logfc_cutoff",
        "has_default": true,
        "default_value": "1",
        "description": "Numeric. Log2 fold change threshold for biological significance. Default: 1 (2-fold change). Range: 0-5. Higher values focus on strong effects. Common: 1 (2-fold), 1.5 (2.8-fold), 2 (4-fold)."
      },
      {
        "name": "nlabel",
        "has_default": true,
        "default_value": "10",
        "description": "Integer. Number of top significant genes to auto-label. Default: 10 . Range: 0-50. Set to 0 to disable auto-labeling. Genes are ranked by adjusted p-value."
      },
      {
        "name": "highlight_genes",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character vector. Specific genes to label (overrides nlabel). Default: NULL (use auto-labeling). Provide gene symbols to highlight genes of interest. Example: c(\"TP53\", \"MYC\", \"KRAS\") ."
      },
      {
        "name": "colors",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character vector of length 3. Custom colors for Down/NoSig/Up genes. Default: NULL (uses publication-friendly blue/grey/red palette). Order: c(Down, NoSig, Up). Example: c(\"#3288BD\", \"#E3E3E3\", \"#D53E4F\") ."
      },
      {
        "name": "point.maxsize",
        "has_default": true,
        "default_value": "4",
        "description": "Numeric. Maximum point size for visualizing effect magnitude. Default: 4 . Range: 1-10. Points are sized by absolute log2 fold change."
      },
      {
        "name": "point.alpha",
        "has_default": true,
        "default_value": "0.8",
        "description": "Numeric. Transparency of data points. Default: 0.8 . Range: 0-1. Lower values reduce overplotting for dense data."
      },
      {
        "name": "intercept.width",
        "has_default": true,
        "default_value": "0.65",
        "description": "Numeric. Line width for significance thresholds. Default: 0.65 . Range: 0.3-1.5. Dashed lines mark padj and logFC cutoffs."
      },
      {
        "name": "label.size",
        "has_default": true,
        "default_value": "3.5",
        "description": "Numeric. Font size for gene labels. Default: 3.5 . Range: 2-6. Larger values for presentation slides."
      },
      {
        "name": "label.bg",
        "has_default": true,
        "default_value": "\"white\"",
        "description": "Character. Background color for gene labels. Default: \"white\" . Improves readability over dense point clouds."
      },
      {
        "name": "label.bg.r",
        "has_default": true,
        "default_value": "0.1",
        "description": "Numeric. Corner radius for label background. Default: 0.1 . Range: 0-0.3. Higher values give rounded corners."
      },
      {
        "name": "legend.position",
        "has_default": true,
        "default_value": "\"bottom\"",
        "description": "Character. Legend placement. Default: \"bottom\" . Options: \"top\", \"bottom\", \"left\", \"right\", \"none\"."
      },
      {
        "name": "title",
        "has_default": true,
        "default_value": "NULL",
        "description": "Character. Plot title. Default: NULL (auto-generated: \"Gene in CellLine (Method)\"). Provide custom title to override."
      },
      {
        "name": "theme.plot",
        "has_default": true,
        "default_value": "NULL",
        "description": "ggplot2 theme object. Custom theme for plot styling. Default: NULL (uses .gpdb_theme_default() , publication-ready academic theme). Can provide custom ggplot2 theme."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage (TESTED - runtime: 0.61 sec)\n# ===========================================================================\n# Scientific Question: What genes are significantly changed by TP53 perturbation?\n# Dataset: TP53 siRNA in PANC-1 cells\n# Expected output: Volcano plot with 264 up, 95 down (at default thresholds)\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Find available datasets\ndatasets <- gpdb_list_datasets(gene = \"TP53\")\ncat(\"Found\", nrow(datasets), \"datasets for TP53\\n\")\n\n# Create basic volcano plot\np1 <- gpdb_plot_volcano(dataset_id = datasets$dataset_id[1])\n\n# Plot is ready for viewing or saving\nprint(p1)\n\n# Save to file\n# ggplot2::ggsave(\"volcano_tp53.pdf\", p1, width = 8, height = 6)\n\n# ===========================================================================\n# Example 2: Customize Significance Thresholds\n# ===========================================================================\n# Compare different stringency levels\n\n# Stringent thresholds (high confidence)\np2_stringent <- gpdb_plot_volcano(\n  dataset_id = datasets$dataset_id[1],\n  padj_cutoff = 0.01, # More significant\n  logfc_cutoff = 2, # 4-fold change\n  nlabel = 20\n)\n\n# Standard thresholds (balanced)\np2_standard <- gpdb_plot_volcano(\n  dataset_id = datasets$dataset_id[1],\n  padj_cutoff = 0.05, # Standard\n  logfc_cutoff = 1, # 2-fold change\n  nlabel = 10\n)\n\n# Lenient thresholds (exploratory)\np2_lenient <- gpdb_plot_volcano(\n  dataset_id = datasets$dataset_id[1],\n  padj_cutoff = 0.1, # More permissive\n  logfc_cutoff = 0.5, # 1.4-fold change\n  nlabel = 5\n)\n\n# ===========================================================================\n# Example 3: Highlight Specific Genes\n# ===========================================================================\n# Focus on genes of interest (e.g., cell cycle genes)\n\n# Highlight candidate drug targets\ncell_cycle_genes <- c(\"CDK1\", \"CDK2\", \"CDK4\", \"CCND1\", \"CCNE1\", \"MYC\")\n\np3 <- gpdb_plot_volcano(\n  dataset_id = datasets$dataset_id[1],\n  highlight_genes = cell_cycle_genes,\n  point.maxsize = 5,\n  label.size = 4\n)\n\n# Verify which genes are present\ndeg_data <- gpdb_load_deg(datasets$dataset_id[1])\nfound_genes <- cell_cycle_genes[cell_cycle_genes %in% deg_data$gene]\ncat(\"Highlighted genes found:\", paste(found_genes, collapse = \", \"), \"\\n\")\n\n# ===========================================================================\n# Example 4: Customize Visual Appearance\n# ===========================================================================\n# Publication-ready customization\n\n# Custom color palette (colorblind-friendly)\ncustom_colors <- c(\n  \"#0072B2\", # Down (blue)\n  \"#999999\", # NoSig (grey)\n  \"#D55E00\" # Up (orange)\n)\n\np4 <- gpdb_plot_volcano(\n  dataset_id = datasets$dataset_id[1],\n  colors = custom_colors,\n  point.maxsize = 6,\n  point.alpha = 0.6,\n  legend.position = \"right\",\n  title = \"TP53 Perturbation in Pancreatic Cancer Cells\"\n)\n\n# Further customization with ggplot2\nlibrary(ggplot2)\np4_custom <- p4 +\n  theme(plot.title = element_text(size = 16, face = \"bold\")) +\n  labs(caption = \"Data source: GPSAdb (D28200)\")\n\n# ===========================================================================\n# Next Steps (Workflow Integration)\n# ===========================================================================\n# For complete workflows, see:\n# - Load DEG data: ?gpdb_load_deg\n# - Enrichment analysis: ?gpdb_enrich\n# - Network visualization: ?gpdb_plot_network\n# - Compare across datasets: ?gpdb_plot_heatmap_deg\n# - Find aggregated targets: ?gpdb_find_targets\n## End(No test)\n\n\n\n",
    "return_value": "ggplot object showing differential expression volcano plot. **Plot Elements**: X-axis Log2 fold change (positive = upregulated, negative = downregulated) Y-axis -Log10(adjusted p-value). Higher values = more significant Points Each point = one gene. Color shows regulation status (Up/Down/NoSig) Size Point size reflects effect magnitude (absolute log2FC) Dashed lines Significance thresholds (vertical = logFC, horizontal = padj) Labels Top significant genes or user-specified genes **What You Can Do Next**: Save plot: ggplot2::ggsave(\"volcano.pdf\", p, width = 8, height = 6) Customize colors: Modify colors parameter with custom palette Extract DEG data: Use gpdb_load_deg(dataset_id) to get underlying data Compare datasets: Plot multiple datasets for different cell lines/conditions Enrichment analysis: Feed significant genes to gpdb_enrich() Network visualization: Use gpdb_plot_network() for regulatory relationships **Alternative Visualizations**: gpdb_plot_heatmap_deg : Heatmap of DEG across multiple datasets. Use when: Comparing expression patterns across experiments. gpdb_plot_heatmap_expr : Expression heatmap with hierarchical clustering. Use when: Exploring sample-to-sample relationships. gpdb_plot_enrichment : Enrichment results visualization. Use when: Interpreting pathway/GO term enrichment from DEG.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "dataset_id: Character. Dataset ID from GPSAdb (e.g., \"D28200\"). Default: None (required). Use gpdb_list_datasets() to find available datasets. Each dataset represents one perturbation experiment (gene knockout/knockdown).\npadj_cutoff: Numeric. Adjusted p-value significance threshold. Default: 0.05 . Range: 0-1. Genes below this threshold are considered significant. Lower values (0.01) give higher confidence; higher values (0.1) include more candidates.\nlogfc_cutoff: Numeric. Log2 fold change threshold for biological significance. Default: 1 (2-fold change). Range: 0-5. Higher values focus on strong effects. Common: 1 (2-fold), 1.5 (2.8-fold), 2 (4-fold).\nnlabel: Integer. Number of top significant genes to auto-label. Default: 10 . Range: 0-50. Set to 0 to disable auto-labeling. Genes are ranked by adjusted p-value.\nhighlight_genes: Character vector. Specific genes to label (overrides nlabel). Default: NULL (use auto-labeling). Provide gene symbols to highlight genes of interest. Example: c(\"TP53\", \"MYC\", \"KRAS\") .\ncolors: Character vector of length 3. Custom colors for Down/NoSig/Up genes. Default: NULL (uses publication-friendly blue/grey/red palette). Order: c(Down, NoSig, Up). Example: c(\"#3288BD\", \"#E3E3E3\", \"#D53E4F\") .\npoint.maxsize: Numeric. Maximum point size for visualizing effect magnitude. Default: 4 . Range: 1-10. Points are sized by absolute log2 fold change.\npoint.alpha: Numeric. Transparency of data points. Default: 0.8 . Range: 0-1. Lower values reduce overplotting for dense data.\nintercept.width: Numeric. Line width for significance thresholds. Default: 0.65 . Range: 0.3-1.5. Dashed lines mark padj and logFC cutoffs.\nlabel.size: Numeric. Font size for gene labels. Default: 3.5 . Range: 2-6. Larger values for presentation slides.\nlabel.bg: Character. Background color for gene labels. Default: \"white\" . Improves readability over dense point clouds.\nlabel.bg.r: Numeric. Corner radius for label background. Default: 0.1 . Range: 0-0.3. Higher values give rounded corners.\nlegend.position: Character. Legend placement. Default: \"bottom\" . Options: \"top\", \"bottom\", \"left\", \"right\", \"none\".\ntitle: Character. Plot title. Default: NULL (auto-generated: \"Gene in CellLine (Method)\"). Provide custom title to override.\ntheme.plot: ggplot2 theme object. Custom theme for plot styling. Default: NULL (uses .gpdb_theme_default() , publication-ready academic theme). Can provide custom ggplot2 theme.",
    "simple_arguments": "dataset_id: Character. Dataset ID from GPSAdb (e.g., \"D28200\"). Default: None (required). Use gpdb_list_datasets() to find available datasets. Each dataset represents one perturbation experiment (gene knockout/knockdown)."
  },
  "gpdb_predict_interaction": {
    "package": "GenePerturbR",
    "function_name": "gpdb_predict_interaction",
    "title": "Predict Gene-Gene Interaction Type from Perturbation Effects",
    "description": "Infer synergistic, antagonistic, or independent relationships between two genes by comparing their regulatory effects on common target genes across 18.9M pre-computed relationships from 7,665 perturbation experiments. Computes Pearson correlation between gene1 and gene2 effects on shared targets to classify interaction types. **Requires 5+ common targets** for reliable predictions. Fast correlation-based scoring with sub-100ms runtime for most gene pairs.",
    "user_queries": ["How do I predict if two genes work together or oppose each other?", "What is the relationship between TP53 and MDM2?", "Do METTL3 and ALKBH5 have antagonistic effects?", "How many common targets are needed for reliable prediction?", "What does correlation coefficient tell me about gene interaction?", "Can I test synergy between pathway genes?", "How do I interpret independent vs synergistic interactions?", "What are the top targets co-regulated by two genes?", "Can I visualize the correlation between gene effects?", "How do I validate predicted gene-gene interactions?", "What if prediction shows insufficient data?", "Can I test interactions for gene family members?", "How reliable is the correlation-based prediction?", "What does high positive correlation indicate biologically?", "What does high negative correlation suggest?", "Can I get raw effect data for custom analysis?", "How do I find all genes that synergize with my gene of interest?", "What experimental designs validate synergistic interactions?", "Can I test context-specific interactions (tissue/cell line)?", "How do I build interaction networks for pathway genes?"],
    "usage": "gpdb_predict_interaction(gene1, gene2, interaction_type = \"infer\")",
    "parameters": [
      {
        "name": "gene1",
        "has_default": false,
        "description": "Character. First gene symbol (e.g., \"TP53\", \"MYC\"). Will be auto-formatted to uppercase. Must exist in database (use gpdb_search() to verify). This gene's perturbation effects will be compared with"
      },
      {
        "name": "gene2",
        "has_default": false,
        "description": "gene2 Character. Second gene symbol (e.g., \"MDM2\", \"KRAS\"). Will be auto-formatted to uppercase. Must exist in database. Order of gene1/gene2 does not affect results (correlation is symmetric)."
      },
      {
        "name": "interaction_type",
        "has_default": true,
        "default_value": "\"infer\"",
        "description": "Character. Prediction mode for interaction classification. Default: \"infer\" . Options: \"infer\" : Automatically classify based on correlation threshold (recommended). Uses: r > 0.5 = synergistic, r < -0.5 = antagonistic, else independent. \"synergy\" : Force synergistic classification (returns correlation data only). Use when: Testing specific hypothesis about cooperative effects. \"antagonism\" : Force antagonistic classification (returns correlation data only). Use when: Testing specific hypothesis about opposing effects."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage - Infer Interaction (TESTED - runtime: 0.054 sec)\n# ===========================================================================\n# Scientific Question: Do TP53 and MDM2 have synergistic or antagonistic effects?\n# Known biology: MDM2 is E3 ligase that degrades TP53 (expected: antagonistic)\n# Expected output: Interaction prediction with correlation and common targets\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Predict interaction between TP53 and MDM2\ninteraction <- gpdb_predict_interaction(\n  gene1 = \"TP53\",\n  gene2 = \"MDM2\",\n  interaction_type = \"infer\"\n)\n\n# Examine prediction\ncat(\"Interaction type:\", interaction$prediction, \"\\n\")\ncat(\"Correlation:\", round(interaction$correlation, 3), \"\\n\")\ncat(\"Common targets:\", interaction$n_common_targets, \"\\n\")\ncat(\"Evidence:\", interaction$evidence, \"\\n\")\n\n# View top co-regulated targets\ncat(\"\\nTop 5 common targets:\\n\")\nprint(head(interaction$top_common_targets, 5))\n\n# ===========================================================================\n# Example 2: m6A Enzymes - Writer vs Eraser (TESTED - runtime: 0.059 sec)\n# ===========================================================================\n# Scientific Question: Do m6A methyltransferase and demethylase oppose each other?\n# Known biology: METTL3 adds m6A, ALKBH5 removes m6A (expected: antagonistic)\n\ninteraction_m6a <- gpdb_predict_interaction(\"METTL3\", \"ALKBH5\")\n\ncat(\"\\nMETTL3-ALKBH5 interaction:\\n\")\ncat(\"  Prediction:\", interaction_m6a$prediction, \"\\n\")\ncat(\"  Correlation:\", round(interaction_m6a$correlation, 3), \"\\n\")\ncat(\"  Common targets:\", interaction_m6a$n_common_targets, \"\\n\")\n\n# Note: r = -0.108 (weak antagonism, below -0.5 threshold)\n# Suggests context-dependent or indirect antagonism\n\n# ===========================================================================\n# Example 3: Oncogenes - MYC and KRAS (TESTED - runtime: 0.052 sec)\n# ===========================================================================\n# Scientific Question: Do MYC and KRAS have synergistic oncogenic effects?\n\ninteraction_onc <- gpdb_predict_interaction(\"MYC\", \"KRAS\")\n\ncat(\"\\nMYC-KRAS interaction:\\n\")\ncat(\"  Prediction:\", interaction_onc$prediction, \"\\n\")\ncat(\"  Correlation:\", round(interaction_onc$correlation, 3), \"\\n\")\n\n# ===========================================================================\n# Example 4: Explore Common Effects Data Frame\n# ===========================================================================\n# Access detailed effects on shared targets for custom analysis\n\ncommon_effects <- interaction$common_effects\n\ncat(\"\\nCommon effects structure:\\n\")\ncat(\n  \"  Dimensions:\", nrow(common_effects), \"targets ×\",\n  ncol(common_effects), \"columns\\n\"\n)\ncat(\"  Columns:\", paste(names(common_effects), collapse = \", \"), \"\\n\")\n\n# View top co-regulated targets with strongest combined effects\ntop_10 <- head(common_effects, 10)\ncat(\"\\nTop 10 targets by combined effect magnitude:\\n\")\nprint(top_10[, c(\"target_gene\", \"logfc1\", \"logfc2\")])\n\n# ===========================================================================\n# Example 5: Visualize Correlation (Custom Plot)\n# ===========================================================================\n# Create scatter plot of gene1 vs gene2 effects\n\n# Extract effects for visualization\neffects_df <- interaction$common_effects\n\n# Correlation plot (base R)\nplot(effects_df$logfc1, effects_df$logfc2,\n  xlab = paste(interaction$gene1, \"effect (logFC)\"),\n  ylab = paste(interaction$gene2, \"effect (logFC)\"),\n  main = paste(\"Correlation: r =\", round(interaction$correlation, 3)),\n  pch = 16, col = rgb(0, 0, 0, 0.1),\n  xlim = c(-5, 5), ylim = c(-5, 5)\n)\nabline(h = 0, v = 0, lty = 2, col = \"gray\")\nabline(a = 0, b = 1, lty = 2, col = \"red\") # y = x line for reference\n\n# ===========================================================================\n# Example 6: Filter Strong Co-Regulated Targets\n# ===========================================================================\n# Find targets with strong effects from both genes\n\n# Criteria: |logfc1| > 1.5 AND |logfc2| > 1.5 (strong effects from both)\nstrong_targets <- effects_df[\n  abs(effects_df$logfc1) > 1.5 & abs(effects_df$logfc2) > 1.5,\n]\n\ncat(\"\\nTargets with strong effects from both genes:\\n\")\ncat(\"  Count:\", nrow(strong_targets), \"\\n\")\n\nif (nrow(strong_targets) > 0) {\n  # Check directionality: same direction (synergy) or opposite (antagonism)?\n  same_dir <- sign(strong_targets$logfc1) == sign(strong_targets$logfc2)\n  cat(\"  Same direction:\", sum(same_dir), \"targets\\n\")\n  cat(\"  Opposite direction:\", sum(!same_dir), \"targets\\n\")\n\n  # Show examples\n  cat(\"\\nTop 5 strongly co-regulated targets:\\n\")\n  print(head(strong_targets[, c(\"target_gene\", \"logfc1\", \"logfc2\")], 5))\n}\n\n# ===========================================================================\n# Example 7: Build Interaction Matrix for Gene Family\n# ===========================================================================\n# Test all pairwise interactions within gene set\n\n# Example: Cell cycle genes\ngenes <- c(\"CCND1\", \"CDK4\", \"CDK6\", \"E2F1\")\n\n# Create pairwise interaction matrix\nn_genes <- length(genes)\ncorrelation_matrix <- matrix(NA, n_genes, n_genes,\n  dimnames = list(genes, genes)\n)\n\nfor (i in 1:n_genes) {\n  for (j in i:n_genes) {\n    if (i == j) {\n      correlation_matrix[i, j] <- 1.0 # Self-correlation\n    } else {\n      result <- gpdb_predict_interaction(genes[i], genes[j])\n      correlation_matrix[i, j] <- result$correlation\n      correlation_matrix[j, i] <- result$correlation # Symmetric\n    }\n  }\n}\n\ncat(\"\\nCell cycle gene interaction matrix:\\n\")\nprint(round(correlation_matrix, 3))\n\n# ===========================================================================\n# Example 8: Validate Synergistic Interaction\n# ===========================================================================\n# Deep dive into a predicted synergistic pair\n\n# Find a strongly synergistic pair (for demonstration, assume CCND1-CDK4)\nsyn_test <- gpdb_predict_interaction(\"CCND1\", \"CDK4\")\n\nif (syn_test$prediction == \"synergistic\") {\n  cat(\"\\nValidating synergistic interaction:\\n\")\n\n  # 1. Check experimental evidence for each gene\n  datasets_g1 <- gpdb_list_datasets(syn_test$gene1)\n  datasets_g2 <- gpdb_list_datasets(syn_test$gene2)\n  cat(\"  \", syn_test$gene1, \"datasets:\", nrow(datasets_g1), \"\\n\")\n  cat(\"  \", syn_test$gene2, \"datasets:\", nrow(datasets_g2), \"\\n\")\n\n  # 2. Pathway enrichment on common targets\n  common_targets <- syn_test$top_common_targets\n  # enrichment <- gpdb_enrich(common_targets, enrich.type = \"KEGG\")\n\n  # 3. Network visualization\n  # gpdb_plot_network(syn_test$gene1, top_targets = 50)\n}\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# For complete workflows, see:\n# - Detailed targets: ?gpdb_find_targets\n# - Compare effects: ?gpdb_compare_genes\n# - Network visualization: ?gpdb_plot_network\n# - Pathway enrichment: ?gpdb_enrich\n# - Load validation data: ?gpdb_load_data\n# - Multi-step regulation: ?gpdb_analyze_cascade\n## End(No test)\n\n\n",
    "return_value": "List with interaction prediction and supporting evidence. Elements: gene1 First gene symbol (formatted) gene2 Second gene symbol (formatted) prediction Interaction type classification: \"synergistic\": Genes produce similar effects on targets (r > 0.5) \"antagonistic\": Genes produce opposite effects on targets (r < -0.5) \"independent\": Genes have uncorrelated effects (-0.5 ≤ r ≤ 0.5) \"insufficient_data\": One/both genes lack perturbation data \"insufficient_overlap\": <5 common targets found correlation Pearson correlation coefficient between gene1 and gene2 effects on common targets. Range: -1 to +1. Values closer to ±1 indicate stronger interaction (synergistic or antagonistic). Values near 0 suggest independence. n_common_targets Number of genes regulated by BOTH gene1 and gene2. Larger values (>100) provide more robust correlation estimates. Typical range: 5,000-20,000 for well-studied genes. evidence Natural language summary explaining the prediction with correlation value and common target count. LLM-friendly format for automated interpretation. top_common_targets Character vector of top 10 shared target genes, ranked by combined effect magnitude (|logfc1 + logfc2|). These genes show strongest co-regulation by both gene1 and gene2. common_effects Data.frame with all common target effects. Columns: target_gene: Shared target gene symbol logfc1: Gene1 perturbation effect (log2 fold change) n1: Number of datasets supporting gene1 → target relationship logfc2: Gene2 perturbation effect (log2 fold change) n2: Number of datasets supporting gene2 → target relationship Use for custom correlation analysis or visualization. **Interpreting Results**: **Synergistic (r > 0.5)**: Genes work together, co-activate or co-repress targets. Example: Co-factors in same pathway. Consider: Dual targeting for enhanced effects. **Antagonistic (r < -0.5)**: Genes oppose each other, one activates while other represses. Example: Feedback regulators. Consider: Synthetic lethality or rescue experiments. **Independent (-0.5 ≤ r ≤ 0.5)**: Genes regulate different target sets or contexts. Example: Parallel pathways. Consider: Orthogonal perturbations for combinatorial studies. **High n_common_targets (>1000)**: Strong statistical power, reliable prediction **Low n_common_targets (<100)**: Interpret with caution, may reflect context-specific effects **What You Can Do Next**: Examine shared targets: Explore result$common_effects data frame Visualize correlation: Plot logfc1 vs logfc2 from common_effects Check individual effects: gpdb_find_targets (gene1) and gpdb_find_targets (gene2) Network visualization: gpdb_plot_network (gene1, top_targets = 50) Pathway enrichment: gpdb_enrich (top_common_targets, enrich.type = \"KEGG\") Load validation data: gpdb_list_datasets (gene1) → gpdb_load_data (dataset_id) **Alternative Methods**: gpdb_compare_genes : Compare multiple genes' effects side-by-side. Use when: Analyzing gene family or pathway members simultaneously. gpdb_analyze_cascade : Trace multi-step regulatory paths between genes. Use when: Investigating indirect regulatory relationships. gpdb_predict_targets : Find genes that reverse/mimic expression signature. Use when: Looking for therapeutic targets for gene pair's combined effects.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "gene1: Character. First gene symbol (e.g., \"TP53\", \"MYC\"). Will be auto-formatted to uppercase. Must exist in database (use gpdb_search() to verify). This gene's perturbation effects will be compared with\ngene2: gene2 Character. Second gene symbol (e.g., \"MDM2\", \"KRAS\"). Will be auto-formatted to uppercase. Must exist in database. Order of gene1/gene2 does not affect results (correlation is symmetric).\ninteraction_type: Character. Prediction mode for interaction classification. Default: \"infer\" . Options: \"infer\" : Automatically classify based on correlation threshold (recommended). Uses: r > 0.5 = synergistic, r < -0.5 = antagonistic, else independent. \"synergy\" : Force synergistic classification (returns correlation data only). Use when: Testing specific hypothesis about cooperative effects. \"antagonism\" : Force antagonistic classification (returns correlation data only). Use when: Testing specific hypothesis about opposing effects.",
    "simple_arguments": "gene1: Character. First gene symbol (e.g., \"TP53\", \"MYC\"). Will be auto-formatted to uppercase. Must exist in database (use gpdb_search() to verify). This gene's perturbation effects will be compared with\ngene2: gene2 Character. Second gene symbol (e.g., \"MDM2\", \"KRAS\"). Will be auto-formatted to uppercase. Must exist in database. Order of gene1/gene2 does not affect results (correlation is symmetric)."
  },
  "gpdb_predict_targets": {
    "package": "GenePerturbR",
    "function_name": "gpdb_predict_targets",
    "title": "Predict Therapeutic Targets from Disease Gene Expression Signature",
    "description": "Identify candidate drug targets by Gene Perturbation Similarity Analysis (GPSA), matching disease signatures against 18.9M pre-computed gene-gene regulatory relationships from 7,665 perturbation experiments. Finds genes whose knockdown/overexpression would reverse (therapeutic mode) or mimic (mechanistic mode) the disease transcriptional profile. **Database covers 2,810 perturbed genes** with evidence-weighted scoring based on multi-dataset consensus. Optimized with vectorized SQL queries for fast signature matching.",
    "user_queries": ["How do I find drug targets from disease gene expression data?", "What genes should I knock down to reverse disease signature?", "Can I predict therapeutic targets from RNA-seq data?", "How many signature genes do I need for reliable predictions?", "What is the difference between reverse and mimic mode?", "How do I interpret the total_score and match_rate?", "Which candidates are best for experimental validation?", "Can I use directional signatures without fold changes?", "How reliable are predictions with low signature coverage?", "What evidence supports the predicted therapeutic targets?", "How do I validate predicted targets in my system?", "Can I find targets that affect specific pathway genes?", "What if my disease signature has mixed up/down genes?", "How do I filter candidates by effect size or consistency?", "Can I compare predictions across different signatures?", "What downstream experiments should I prioritize?", "How do I check off-target effects of predicted targets?", "Can I use this for drug repurposing analysis?", "What cell lines were used for candidate target data?", "How do I export results for further computational analysis?"],
    "usage": "gpdb_predict_targets( disease_signature, mode = c(\"reverse\", \"mimic\"), top_n = 10, min_confidence = \"medium\" )",
    "parameters": [
      {
        "name": "disease_signature",
        "has_default": false,
        "description": "Data.frame with disease gene expression profile. Required columns: gene : Character vector of gene symbols (e.g., \"MYC\", \"TP53\", \"KRAS\"). Will be auto-formatted to uppercase. Use 5-50 signature genes for optimal results. logFC OR direction : Either numeric log2 fold changes (recommended) or categorical directions (\"up\"/\"down\", \"UP\"/\"DOWN\", \"upregulated\"/\"downregulated\"). logFC values are used for magnitude weighting; directions get equal weight. Example: data.frame(gene = c(\"MYC\", \"TP53\"), logFC = c(2.5, -1.8))"
      },
      {
        "name": "mode",
        "has_default": true,
        "default_value": "c(\"reverse\", \"mimic\")",
        "description": "Character. Prediction strategy for target identification. Default: \"reverse\" . Options: \"reverse\" : Find genes producing OPPOSITE effects (therapeutic targets). Use when: Disease has upregulated oncogenes → find genes that downregulate them. Example: High MYC in cancer → identify genes whose knockdown reduces MYC. \"mimic\" : Find genes producing SIMILAR effects (mechanistic insights). Use when: Studying disease mechanisms or identifying phenocopy genes. Example: Find other genes that produce cancer-like expression changes."
      },
      {
        "name": "top_n",
        "has_default": true,
        "default_value": "10",
        "description": "Integer. Number of top-ranked candidates to return. Default: 10 . Range: 5-100. Higher values include lower-scoring candidates that may have partial signature matches or lower confidence evidence."
      },
      {
        "name": "min_confidence",
        "has_default": true,
        "default_value": "\"medium\"",
        "description": "Character. Evidence strength filter for regulatory relationships. Default: \"medium\" . Options: \"high\": 5+ datasets, >80% consistency (publication-grade, fewer candidates) \"medium\": 2-4 datasets, >70% consistency (balanced, recommended) \"low\": 1 dataset (exploratory, includes preliminary findings)"
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage - Reverse Mode (TESTED - runtime: 1.02 sec)\n# ===========================================================================\n# Scientific Question: Find therapeutic targets for oncogene-driven disease\n# Strategy: Identify genes whose knockdown reverses oncogene upregulation\n# Expected output: Ranked candidates with scoring metrics\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Create disease signature (oncogene upregulation in cancer)\ndisease_sig <- data.frame(\n  gene = c(\"MYC\", \"CCND1\", \"CDK4\", \"E2F1\", \"BIRC5\"),\n  logFC = c(2.5, 1.8, 2.1, 1.5, 2.0)\n)\n\n# Find genes that reverse this signature (therapeutic targets)\ntargets <- gpdb_predict_targets(\n  disease_signature = disease_sig,\n  mode = \"reverse\",\n  top_n = 10,\n  min_confidence = \"medium\"\n)\n\n# Examine top candidates\ncat(\"Found\", nrow(targets), \"candidate therapeutic targets\\n\")\ncat(\"\\nTop candidate:\", targets$perturbed_gene[1], \"\\n\")\ncat(\"  Total score:\", round(targets$total_score[1], 2), \"\\n\")\ncat(\n  \"  Signature coverage:\", targets$n_signature_matches[1], \"/\",\n  nrow(disease_sig), \"genes\\n\"\n)\ncat(\"  Match rate:\", round(targets$match_rate[1] * 100, 1), \"%\\n\")\n\n# View all candidates\nprint(targets[, c(\n  \"perturbed_gene\", \"total_score\", \"n_signature_matches\",\n  \"match_rate\", \"avg_effect_size\"\n)])\n\n# ===========================================================================\n# Example 2: Mimic Mode - Mechanistic Study (TESTED - runtime: 0.07 sec)\n# ===========================================================================\n# Scientific Question: Find genes that produce similar disease-like effects\n# Use case: Identify phenocopy genes for mechanism studies\n\n# Same disease signature\nmimics <- gpdb_predict_targets(\n  disease_signature = disease_sig,\n  mode = \"mimic\", # Find genes producing SIMILAR effects\n  top_n = 5,\n  min_confidence = \"high\" # High-confidence only\n)\n\ncat(\"\\nGenes that mimic disease signature:\\n\")\nprint(mimics[, c(\"perturbed_gene\", \"total_score\", \"match_rate\")])\n\n# ===========================================================================\n# Example 3: Direction-Based Signature (TESTED - runtime: 0.28 sec)\n# ===========================================================================\n# Use case: Have categorical up/down information without exact fold changes\n\n# Tumor suppressor downregulation signature\nsig_direction <- data.frame(\n  gene = c(\"TP53\", \"CDKN1A\", \"BAX\"),\n  direction = c(\"down\", \"down\", \"down\")\n)\n\n# Find targets that restore tumor suppressor expression\nrestorers <- gpdb_predict_targets(\n  disease_signature = sig_direction,\n  mode = \"reverse\",\n  top_n = 5\n)\n\ncat(\"\\nCandidates that restore tumor suppressor expression:\\n\")\nprint(restorers)\n\n# ===========================================================================\n# Example 4: Filter and Prioritize Candidates\n# ===========================================================================\n# Select high-quality candidates for experimental validation\n\n# Criteria: High match rate + broad signature coverage + strong effects\nhigh_quality <- targets[\n  targets$match_rate > 0.8 & # >80% correct direction\n    targets$n_signature_matches >= 4 & # Affects 4+ signature genes\n    targets$avg_effect_size > 1.5, # Strong effect size\n]\n\ncat(\"\\nHigh-quality candidates for validation:\\n\")\nprint(high_quality[, c(\n  \"perturbed_gene\", \"total_score\",\n  \"n_signature_matches\", \"match_rate\"\n)])\n\n# ===========================================================================\n# Example 5: Compare Reverse vs Mimic for Same Signature\n# ===========================================================================\n# Understand both therapeutic targets and disease mechanism\n\n# Small signature for quick comparison\nsmall_sig <- data.frame(\n  gene = c(\"MYC\", \"CCND1\", \"CDK4\"),\n  logFC = c(2.5, 1.8, 2.1)\n)\n\n# Therapeutic targets (reverse)\ntargets_rev <- gpdb_predict_targets(small_sig, mode = \"reverse\", top_n = 3)\n\n# Phenocopy genes (mimic)\ntargets_mim <- gpdb_predict_targets(small_sig, mode = \"mimic\", top_n = 3)\n\ncat(\"\\nTherapeutic targets (reverse signature):\\n\")\nprint(targets_rev$perturbed_gene)\n\ncat(\"\\nPhenocopy genes (mimic signature):\\n\")\nprint(targets_mim$perturbed_gene)\n\n# ===========================================================================\n# Example 6: Validate Top Candidate\n# ===========================================================================\n# Get detailed evidence for top-ranked therapeutic target\n\ntop_candidate <- targets$perturbed_gene[1]\ncat(\"\\nValidating top candidate:\", top_candidate, \"\\n\")\n\n# Check which signature genes it regulates\ncandidate_targets <- gpdb_find_targets(\n  gene = top_candidate,\n  top_n = 100,\n  min_confidence = \"medium\"\n)\n\n# Find overlap with disease signature\noverlap_up <- intersect(\n  candidate_targets$downregulated$target_gene, # Candidate downregulates\n  disease_sig$gene[disease_sig$logFC > 0] # Disease upregulates\n)\n\ncat(\"Signature genes reversed by candidate:\", length(overlap_up), \"\\n\")\ncat(\"Genes:\", paste(overlap_up, collapse = \", \"), \"\\n\")\n\n# Check experimental evidence\ndatasets <- gpdb_list_datasets(gene = top_candidate)\ncat(\"Supporting datasets:\", nrow(datasets), \"\\n\")\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# For complete workflows, see:\n# - Detailed regulation: ?gpdb_find_targets\n# - Experimental evidence: ?gpdb_list_datasets\n# - Load validation data: ?gpdb_load_data\n# - Network visualization: ?gpdb_plot_network\n# - Pathway enrichment: ?gpdb_enrich\n# - Compare candidates: ?gpdb_compare_genes\n## End(No test)\n\n\n",
    "return_value": "Data.frame with ranked candidate targets and scoring metrics. Columns: perturbed_gene Candidate target gene symbol (gene to perturb) total_score Weighted composite score (higher = better match). Computed as: sum(match_score × effect_size × consistency × signature_magnitude) across all signature genes. Top candidates typically have scores >10. n_signature_matches Number of signature genes affected by this candidate. Higher values indicate broader coverage of disease signature. n_positive_matches Number of genes affected in desired direction. Should be close to n_signature_matches for high-quality candidates. match_rate Proportion of matches in correct direction (0-1). Values >0.8 indicate consistent directional effects across signature genes. avg_effect_size Mean |logFC| across regulated signature genes. Higher values (>2) indicate strong perturbation effects. avg_consistency Mean consistency score across datasets (0-1). Values >0.8 indicate reproducible effects across experimental contexts. avg_n_datasets Mean number of supporting datasets per relationship. Higher values provide stronger evidence base for predictions. **Interpreting Results**: **Top candidates** (rank 1-3): Highest priority for experimental validation **Match rate >0.8**: Consistently regulates signature in desired direction **High total_score + high match_rate**: Best therapeutic target candidates **High n_signature_matches**: Broad impact on disease signature **What You Can Do Next**: Examine regulatory details: gpdb_find_targets (candidate_gene, top_n = 100) Check experimental evidence: gpdb_list_datasets (candidate_gene) Pathway enrichment: gpdb_enrich (signature_genes, enrich.type = \"KEGG\") Network visualization: gpdb_plot_network (candidate_gene, top_targets = 50) Validate interactions: gpdb_predict_interaction (candidate, signature_gene) Load validation data: gpdb_load_data (dataset_id) **Alternative Methods**: gpdb_find_regulators : Find upstream regulators of single gene. Use when: Have one key disease gene, not full signature. gpdb_compare_genes : Compare effects of multiple candidate targets. Use when: Evaluating alternative therapeutic targets side-by-side. gpdb_analyze_cascade : Trace multi-step regulatory cascades. Use when: Understanding indirect regulation mechanisms.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "disease_signature: Data.frame with disease gene expression profile. Required columns: gene : Character vector of gene symbols (e.g., \"MYC\", \"TP53\", \"KRAS\"). Will be auto-formatted to uppercase. Use 5-50 signature genes for optimal results. logFC OR direction : Either numeric log2 fold changes (recommended) or categorical directions (\"up\"/\"down\", \"UP\"/\"DOWN\", \"upregulated\"/\"downregulated\"). logFC values are used for magnitude weighting; directions get equal weight. Example: data.frame(gene = c(\"MYC\", \"TP53\"), logFC = c(2.5, -1.8))\nmode: Character. Prediction strategy for target identification. Default: \"reverse\" . Options: \"reverse\" : Find genes producing OPPOSITE effects (therapeutic targets). Use when: Disease has upregulated oncogenes → find genes that downregulate them. Example: High MYC in cancer → identify genes whose knockdown reduces MYC. \"mimic\" : Find genes producing SIMILAR effects (mechanistic insights). Use when: Studying disease mechanisms or identifying phenocopy genes. Example: Find other genes that produce cancer-like expression changes.\ntop_n: Integer. Number of top-ranked candidates to return. Default: 10 . Range: 5-100. Higher values include lower-scoring candidates that may have partial signature matches or lower confidence evidence.\nmin_confidence: Character. Evidence strength filter for regulatory relationships. Default: \"medium\" . Options: \"high\": 5+ datasets, >80% consistency (publication-grade, fewer candidates) \"medium\": 2-4 datasets, >70% consistency (balanced, recommended) \"low\": 1 dataset (exploratory, includes preliminary findings)",
    "simple_arguments": "disease_signature: Data.frame with disease gene expression profile. Required columns: gene : Character vector of gene symbols (e.g., \"MYC\", \"TP53\", \"KRAS\"). Will be auto-formatted to uppercase. Use 5-50 signature genes for optimal results. logFC OR direction : Either numeric log2 fold changes (recommended) or categorical directions (\"up\"/\"down\", \"UP\"/\"DOWN\", \"upregulated\"/\"downregulated\"). logFC values are used for magnitude weighting; directions get equal weight. Example: data.frame(gene = c(\"MYC\", \"TP53\"), logFC = c(2.5, -1.8))"
  },
  "gpdb_search": {
    "package": "GenePerturbR",
    "function_name": "gpdb_search",
    "title": "Search Gene Perturbation Database Across Multiple Categories",
    "description": "Flexible keyword search across genes, cell lines, and tissue types in the GenePerturbR database (7,665 perturbation experiments). Supports fuzzy matching (default) for partial string matches or exact matching for precise lookups. **Database contains 2,810 genes, 1,063 cell lines, 71 tissue types** with results ranked by experimental coverage (dataset count). Fast sub-20ms queries for single-category searches, ideal for data exploration and validation.",
    "user_queries": ["How do I check if my gene is in the database?", "What genes start with \"TP\" or contain \"kinase\"?", "How do I find available cell lines for my tissue type?", "What is the exact gene symbol used in database?", "How many datasets exist for my gene of interest?", "Can I search for gene aliases or alternative names?", "How do I find all HeLa cell line variants?", "What tissue types are available in the database?", "How reliable is a gene with only 1-2 datasets?", "Why does my search return no results?", "Can I search for multiple genes at once?", "How do I find genes in specific cell line?", "What's the difference between fuzzy and exact search?", "Which genes have the most experimental coverage?", "How do I validate if gene name is correct?", "Can I search for tissue-specific perturbations?", "How do I explore available experimental systems?", "What cell lines have most datasets for my gene?", "How do I find similar gene names?", "Can I search by gene family or pathway?"],
    "usage": "gpdb_search( query, search_in = c(\"genes\", \"cell_lines\", \"tissues\"), fuzzy = TRUE )",
    "parameters": [
      {
        "name": "query",
        "has_default": false,
        "description": "Character. Search keyword or pattern. Case-insensitive partial matching by default ("
      },
      {
        "name": "search_in",
        "has_default": true,
        "default_value": "c(\"genes\", \"cell_lines\", \"tissues\")",
        "description": "Character vector. Categories to search in. Default: c(\"genes\", \"cell_lines\", \"tissues\") (search all categories). Options: \"genes\" : Perturbed genes in database (2,810 unique genes). Searches pbgene column in datasets table. Returns up to 20 top matches by dataset count. \"cell_lines\" : Cell line names (1,063 unique cell lines). Searches CellLineName column. Useful for finding available cell systems. \"tissues\" : Tissue types (71 unique tissues). Searches TissueSite column. Useful for context-specific analysis planning. Can specify single category (e.g., \"genes\" ) or combination (e.g., c(\"genes\", \"cell_lines\") ). fuzzy Logical. Enable fuzzy (partial) matching. Default: TRUE (recommended for exploration). TRUE : SQL LIKE '%query%' pattern matching. Finds all entries containing query string. Case-insensitive. Returns up to 20 results per category, ranked by dataset count. Use when: Exploring similar gene names, finding cell line variants, or discovering related entries. FALSE : Exact match (SQL = 'query'). Returns only perfect matches. Use when: Validating specific gene exists, confirming exact cell line name, or retrieving precise dataset counts."
      },
      {
        "name": "fuzzy",
        "has_default": true,
        "default_value": "TRUE",
        "description": "mode). Examples: \"TP\" finds TP53, TP63, PTPN2; \"HeLa\" finds HeLa, H1HeLa, HeLa S3; \"Liver\" finds Liver tissue. Use exact gene symbols with fuzzy = FALSE for precise lookups. Whitespace is trimmed automatically."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Fuzzy Search - All Categories (TESTED - runtime: 0.018 sec)\n# ===========================================================================\n# Scientific Question: What entries contain \"TP\" in database?\n# Use case: Exploratory search to find TP53 and related genes\n# Expected output: Genes, cell lines, and tissues matching \"TP\"\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\n# Search across all categories\nresults <- gpdb_search(\"TP\")\n\n# Examine genes found\ncat(\"Genes found:\", nrow(results$genes), \"\\n\")\nprint(head(results$genes, 5))\n# Output: TP53 (71 datasets), TP63 (17), PTPN2 (6), PTPN23 (6), ITPR3 (3)\n\n# Check cell lines\nif (!is.null(results$cell_lines) && nrow(results$cell_lines) > 0) {\n  cat(\"\\nCell lines found:\", nrow(results$cell_lines), \"\\n\")\n  print(results$cell_lines)\n}\n\n# Check tissues\nif (!is.null(results$tissues) && nrow(results$tissues) > 0) {\n  cat(\"\\nTissues found:\", nrow(results$tissues), \"\\n\")\n  print(results$tissues)\n}\n\n# ===========================================================================\n# Example 2: Gene-Only Search (TESTED - runtime: 0.001 sec)\n# ===========================================================================\n# Use case: Find all MYC family genes\n\nmyc_genes <- gpdb_search(\"MYC\", search_in = \"genes\")\n\ncat(\"\\nMYC family genes:\\n\")\nprint(myc_genes$genes)\n# Output: MYC (22 datasets), MYCN (6), MYCL (1)\n\n# Sort by dataset count to identify best-studied member\ncat(\n  \"\\nBest-studied MYC gene:\", myc_genes$genes$gene[1],\n  \"with\", myc_genes$genes$n_datasets[1], \"datasets\\n\"\n)\n\n# ===========================================================================\n# Example 3: Cell Line Search (TESTED - runtime: 0.001 sec)\n# ===========================================================================\n# Use case: Find all HeLa cell line variants\n\nhela_variants <- gpdb_search(\"HeLa\", search_in = \"cell_lines\")\n\ncat(\"\\nHeLa cell line variants:\\n\")\nprint(hela_variants$cell_lines)\n# Output: HeLa (239 datasets), H1HeLa (2), HeLa S3 (2), HeLaK (1)\n\n# Most commonly used variant\ncat(\"\\nMost common HeLa variant:\", hela_variants$cell_lines$cell_line[1], \"\\n\")\n\n# ===========================================================================\n# Example 4: Tissue Search (TESTED - runtime: 0.001 sec)\n# ===========================================================================\n# Use case: Check liver tissue data availability\n\nliver_data <- gpdb_search(\"Liver\", search_in = \"tissues\")\n\nif (!is.null(liver_data$tissues) && nrow(liver_data$tissues) > 0) {\n  cat(\"\\nLiver tissue data:\\n\")\n  print(liver_data$tissues)\n  cat(\"\\nLiver datasets available:\", liver_data$tissues$n_datasets[1], \"\\n\")\n} else {\n  cat(\"\\nNo liver tissue data found\\n\")\n}\n\n# ===========================================================================\n# Example 5: Exact Match Validation (TESTED - runtime: 0.0006 sec)\n# ===========================================================================\n# Use case: Validate exact gene symbol and get dataset count\n\n# Check if TP53 exists (exact match)\ntp53_exact <- gpdb_search(\"TP53\", search_in = \"genes\", fuzzy = FALSE)\n\nif (!is.null(tp53_exact$genes) && nrow(tp53_exact$genes) > 0) {\n  cat(\"\\nTP53 validation:\\n\")\n  cat(\"  Gene:\", tp53_exact$genes$gene[1], \"\\n\")\n  cat(\"  Datasets:\", tp53_exact$genes$n_datasets[1], \"\\n\")\n  cat(\"  Status: EXISTS in database ✓\\n\")\n} else {\n  cat(\"\\nTP53 not found in database\\n\")\n}\n\n# ===========================================================================\n# Example 6: Compare Fuzzy vs Exact Search\n# ===========================================================================\n# Understand difference between search modes\n\n# Fuzzy: Find all genes containing \"CDK\"\ncdk_fuzzy <- gpdb_search(\"CDK\", search_in = \"genes\", fuzzy = TRUE)\ncat(\"\\nFuzzy search for 'CDK':\\n\")\ncat(\"  Genes found:\", nrow(cdk_fuzzy$genes), \"\\n\")\nprint(cdk_fuzzy$genes)\n# Expected: CDK4, CDK6, CDKN1A, CDKN2A, etc. (all containing \"CDK\")\n\n# Exact: Find only \"CDK4\"\ncdk4_exact <- gpdb_search(\"CDK4\", search_in = \"genes\", fuzzy = FALSE)\ncat(\"\\nExact search for 'CDK4':\\n\")\nprint(cdk4_exact$genes)\n# Expected: Only CDK4\n\n# ===========================================================================\n# Example 7: Workflow - Search → Validate → Analyze\n# ===========================================================================\n# Complete workflow from discovery to analysis\n\n# Step 1: Search for gene family\nhdac_genes <- gpdb_search(\"HDAC\", search_in = \"genes\")\ncat(\"\\nStep 1 - Found HDAC genes:\\n\")\nprint(hdac_genes$genes)\n\n# Step 2: Select gene with most data\ntop_hdac <- hdac_genes$genes$gene[1]\ncat(\n  \"\\nStep 2 - Selected:\", top_hdac,\n  \"with\", hdac_genes$genes$n_datasets[1], \"datasets\\n\"\n)\n\n# Step 3: List available datasets\ndatasets <- gpdb_list_datasets(top_hdac)\ncat(\"\\nStep 3 - Available datasets:\\n\")\nprint(head(datasets, 3))\n\n# Step 4: Query gene effects\ntargets <- gpdb_find_targets(top_hdac, top_n = 20)\ncat(\"\\nStep 4 - Top regulated targets:\\n\")\nprint(head(targets$upregulated, 3))\n\n# ===========================================================================\n# Example 8: Multi-Category Search for Context Planning\n# ===========================================================================\n# Plan context-specific analysis\n\n# Search for brain-related entries\nbrain_search <- gpdb_search(\"brain\")\n\ncat(\"\\nBrain-related database content:\\n\")\nif (!is.null(brain_search$genes) && nrow(brain_search$genes) > 0) {\n  cat(\"  Brain-related genes:\", nrow(brain_search$genes), \"\\n\")\n}\nif (!is.null(brain_search$cell_lines) && nrow(brain_search$cell_lines) > 0) {\n  cat(\"  Brain cell lines:\", nrow(brain_search$cell_lines), \"\\n\")\n  print(brain_search$cell_lines)\n}\nif (!is.null(brain_search$tissues) && nrow(brain_search$tissues) > 0) {\n  cat(\"  Brain tissues:\", nrow(brain_search$tissues), \"\\n\")\n  print(brain_search$tissues)\n}\n\n# Use results to plan tissue-specific analysis\nif (!is.null(brain_search$tissues) && nrow(brain_search$tissues) > 0) {\n  brain_tissue <- brain_search$tissues$tissue[1]\n  cat(\"\\nUse in context parameter: context = list(tissue = '\",\n    brain_tissue, \"')\\n\",\n    sep = \"\"\n  )\n}\n\n# ===========================================================================\n# Example 9: Handle No Results\n# ===========================================================================\n# Graceful handling when search finds nothing\n\nrare_gene <- gpdb_search(\"NONEXISTENT\", search_in = \"genes\")\n\nif (is.null(rare_gene$genes) || nrow(rare_gene$genes) == 0) {\n  cat(\"\\nNo results found for 'NONEXISTENT'\\n\")\n  cat(\"Suggestions:\\n\")\n  cat(\"  - Check spelling\\n\")\n  cat(\"  - Try alternative gene names or aliases\\n\")\n  cat(\"  - Use broader fuzzy search\\n\")\n  cat(\"  - Gene may not be in database (2,810 genes available)\\n\")\n}\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# For complete workflows, see:\n# - List experiments: ?gpdb_list_datasets\n# - Query effects: ?gpdb_find_targets\n# - What happens: ?gpdb_what_happens\n# - Compare genes: ?gpdb_compare_genes\n# - Get metadata: ?gpdb_get_info\n# - Load data: ?gpdb_load_data\n## End(No test)\n\n\n",
    "return_value": "List with search results from requested categories. Elements: genes Data.frame of matching genes (if \"genes\" in search_in). Columns: gene : Gene symbol (perturbed gene in experiments) n_datasets : Number of perturbation datasets for this gene. Higher values indicate well-studied genes with more robust evidence. Range: 1-71 (e.g., TP53 = 71 datasets, rare genes = 1-2 datasets). Sorted by n_datasets (descending). Up to 20 results for fuzzy searches. NULL or empty data.frame if no matches found. cell_lines Data.frame of matching cell lines (if \"cell_lines\" in search_in). Columns: cell_line , n_datasets . Sorted by dataset count. Example: HeLa (239 datasets), A549 (180 datasets). NULL if no matches. tissues Data.frame of matching tissues (if \"tissues\" in search_in). Columns: tissue , n_datasets . Sorted by dataset count. Example: Liver (706 datasets), Lung (450 datasets). NULL if no matches. **Interpreting Results**: **High n_datasets (>20)**: Well-characterized genes/systems, robust for analysis **Medium n_datasets (5-20)**: Moderate evidence, suitable for most studies **Low n_datasets (1-4)**: Limited data, use with caution or for exploratory work **Multiple fuzzy matches**: Review all candidates to select correct gene/cell line **No matches**: Check spelling, try broader query, or gene may not be in database **What You Can Do Next**: List datasets for found gene: gpdb_list_datasets (gene) Query gene effects: gpdb_find_targets (gene, top_n = 100) Check what happens: gpdb_what_happens (gene) Filter by context: Use found cell_line/tissue in context parameter Compare similar genes: gpdb_compare_genes (c(\"TP53\", \"TP63\")) Get gene info: gpdb_get_info (dataset_id) for specific datasets **Alternative Methods**: gpdb_list_datasets : List all datasets for known gene. Use when: Already know exact gene symbol, want to see experimental details. gpdb_find_pathway_regulators : Find genes regulating specific pathway. Use when: Pathway-centric analysis rather than keyword search.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "query: Character. Search keyword or pattern. Case-insensitive partial matching by default (\nsearch_in: Character vector. Categories to search in. Default: c(\"genes\", \"cell_lines\", \"tissues\") (search all categories). Options: \"genes\" : Perturbed genes in database (2,810 unique genes). Searches pbgene column in datasets table. Returns up to 20 top matches by dataset count. \"cell_lines\" : Cell line names (1,063 unique cell lines). Searches CellLineName column. Useful for finding available cell systems. \"tissues\" : Tissue types (71 unique tissues). Searches TissueSite column. Useful for context-specific analysis planning. Can specify single category (e.g., \"genes\" ) or combination (e.g., c(\"genes\", \"cell_lines\") ). fuzzy Logical. Enable fuzzy (partial) matching. Default: TRUE (recommended for exploration). TRUE : SQL LIKE '%query%' pattern matching. Finds all entries containing query string. Case-insensitive. Returns up to 20 results per category, ranked by dataset count. Use when: Exploring similar gene names, finding cell line variants, or discovering related entries. FALSE : Exact match (SQL = 'query'). Returns only perfect matches. Use when: Validating specific gene exists, confirming exact cell line name, or retrieving precise dataset counts.\nfuzzy: mode). Examples: \"TP\" finds TP53, TP63, PTPN2; \"HeLa\" finds HeLa, H1HeLa, HeLa S3; \"Liver\" finds Liver tissue. Use exact gene symbols with fuzzy = FALSE for precise lookups. Whitespace is trimmed automatically.",
    "simple_arguments": "query: Character. Search keyword or pattern. Case-insensitive partial matching by default ("
  },
  "gpdb_summarize": {
    "package": "GenePerturbR",
    "function_name": "gpdb_summarize",
    "title": "Generate Natural Language Summary of Gene Function from Perturbation Data",
    "description": "Create automated gene function summaries by aggregating perturbation evidence from 7,665 RNA-seq datasets. Returns human-readable text describing experimental coverage (cell lines, tissues) and top regulatory targets with effect sizes. **Database covers 2,810 genes across 1,063 cell lines** with summaries generated from multi-dataset consensus. Ideal for quick gene profile generation, literature review assistance, and LLM-based analysis workflows.",
    "user_queries": ["How do I get a quick overview of what a gene does?", "What tissues and cell lines have been studied for my gene?", "Which genes are most strongly affected by gene perturbation?", "How many experiments are available for my gene of interest?", "Can I generate a natural language summary for literature review?", "What effect sizes do I see for top regulated targets?", "How do I create brief gene profiles for multiple genes?", "Which genes are upregulated vs downregulated by perturbation?", "Can I use this summary in LLM-based analysis pipelines?", "How reliable is the summary if there are few experiments?", "What information is included in the automated summary?", "Can I control the length of the generated text?", "How do I interpret fold change values in the summary?", "What happens if my gene has no perturbation data?", "Can I compare summaries across related genes?", "How do I export summaries for batch analysis?", "Which aspects of gene function are covered?", "Can I get summaries for non-human genes?", "How often is the summary data updated?", "What downstream analyses work with summary results?"],
    "usage": "gpdb_summarize( gene, max_length = 500, include = c(\"function\", \"targets\", \"pathways\") )",
    "parameters": [
      {
        "name": "gene",
        "has_default": false,
        "description": "Character. Gene symbol (e.g., \"TP53\", \"METTL3\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended."
      },
      {
        "name": "max_length",
        "has_default": true,
        "default_value": "500",
        "description": "Integer. Maximum summary length in characters. Default: 500 . Range: 100-2000. Summaries exceeding limit are truncated with \"...\" suffix. Use 200-300 for brief overviews, 500+ for detailed profiles."
      },
      {
        "name": "include",
        "has_default": true,
        "default_value": "c(\"function\", \"targets\", \"pathways\")",
        "description": "Character vector. Content aspects to include in summary. Default: c(\"function\", \"targets\", \"pathways\") . Options: \"function\" (experimental coverage), \"targets\" (top regulated genes), \"pathways\" (enrichment results - not yet implemented), \"diseases\" (clinical associations - not yet implemented). Currently only \"function\" and \"targets\" are active."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage (TESTED - runtime: 0.020 sec)\n# ===========================================================================\n# Scientific Question: Quick overview of TP53 function from perturbation data\n# Expected output: Natural language text with experimental coverage and top targets\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\nsummary <- gpdb_summarize(\"TP53\")\ncat(summary)\n# Output: \"TP53 has been studied in 71 experiments across 39 cell lines\n# and 23 tissue types. Perturbation leads to upregulation of SLC10A6\n# (7.82-fold) and downregulation of MUC17, LINC01482, SPRR3...\"\n\n# Check summary properties\ncat(\"Summary length:\", nchar(summary), \"characters\\n\")\n\n# ===========================================================================\n# Example 2: Control Summary Length (TESTED - runtime: 0.005 sec)\n# ===========================================================================\n# Compare different length limits\n\n# Brief summary for quick reference\nsummary_brief <- gpdb_summarize(\"TP53\", max_length = 200)\ncat(\"Brief (200 chars):\\n\", summary_brief, \"\\n\\n\")\n\n# Detailed summary for comprehensive overview\nsummary_detailed <- gpdb_summarize(\"TP53\", max_length = 800)\ncat(\"Detailed (800 chars):\\n\", summary_detailed, \"\\n\\n\")\n\n# Very concise for table display\nsummary_concise <- gpdb_summarize(\"TP53\", max_length = 150)\ncat(\"Concise (150 chars):\\n\", summary_concise, \"\\n\")\n\n# ===========================================================================\n# Example 3: Batch Summarization for Multiple Genes\n# ===========================================================================\n# Generate summaries for gene panel\n\ngenes <- c(\"TP53\", \"METTL3\", \"MYC\", \"BRCA1\")\n\n# Create brief summaries for all genes\nsummaries <- lapply(genes, function(g) {\n  gpdb_summarize(g, max_length = 250)\n})\nnames(summaries) <- genes\n\n# Display all summaries\nfor (gene in genes) {\n  cat(\"\\n\", gene, \":\\n\", summaries[[gene]], \"\\n\", sep = \"\")\n}\n\n# ===========================================================================\n# Example 4: Include Parameter Control (future enhancement)\n# ===========================================================================\n# Currently only \"function\" and \"targets\" are implemented\n\nsummary_all <- gpdb_summarize(\n  gene = \"TP53\",\n  max_length = 600,\n  include = c(\"function\", \"targets\") # Current default\n)\n\n# Note: \"pathways\" and \"diseases\" will be added in future versions\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# For complete workflows, see:\n# - Get detailed targets: ?gpdb_find_targets\n# - Load raw data: ?gpdb_load_data\n# - Enrichment analysis: ?gpdb_enrich\n# - Network visualization: ?gpdb_plot_network\n# - Compare genes: ?gpdb_compare_genes\n## End(No test)\n\n\n",
    "return_value": "Character string with natural language gene summary. Format: \"[Gene] has been studied in N experiments across M cell lines and K tissue types. Perturbation leads to upregulation of [genes] (X-fold) and downregulation of [genes] (Y-fold).\" **What You Can Do Next**: Get detailed targets: gpdb_find_targets (gene, top_n = 100) Load raw datasets: gpdb_list_datasets (gene) then gpdb_load_data (dataset_id) Enrichment analysis: gpdb_enrich (targets, enrich.type = \"GO\") Network visualization: gpdb_plot_network (gene, top_targets = 50) Compare with other genes: gpdb_compare_genes (c(gene, \"GENE2\")) **Alternative Methods**: gpdb_what_happens : More structured output with detailed statistics. Use when you need programmatic access to data instead of text summary. gpdb_find_targets : Get full target list with confidence scores. Use when you need quantitative analysis rather than qualitative summary.",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "gene: Character. Gene symbol (e.g., \"TP53\", \"METTL3\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended.\nmax_length: Integer. Maximum summary length in characters. Default: 500 . Range: 100-2000. Summaries exceeding limit are truncated with \"...\" suffix. Use 200-300 for brief overviews, 500+ for detailed profiles.\ninclude: Character vector. Content aspects to include in summary. Default: c(\"function\", \"targets\", \"pathways\") . Options: \"function\" (experimental coverage), \"targets\" (top regulated genes), \"pathways\" (enrichment results - not yet implemented), \"diseases\" (clinical associations - not yet implemented). Currently only \"function\" and \"targets\" are active.",
    "simple_arguments": "gene: Character. Gene symbol (e.g., \"TP53\", \"METTL3\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended."
  },
  "gpdb_what_happens": {
    "package": "GenePerturbR",
    "function_name": "gpdb_what_happens",
    "title": "Comprehensive Gene Perturbation Effect Analysis",
    "description": "Query all effects of gene perturbation aggregated from 7,665 RNA-seq datasets, returning upregulated and downregulated targets with multi-dataset confidence scores. **Database covers 2,810 genes across 1,063 cell lines and 71 tissue types** with 826,650 high-confidence relationships. Returns natural language summary and structured data for immediate interpretation or downstream analysis.",
    "user_queries": ["What happens when TP53 is knocked out in my cells?", "Which genes are affected by METTL3 knockdown?", "What are the downstream effects of MYC perturbation?", "How do I get a comprehensive view of gene perturbation effects?", "What genes increase or decrease after knocking out my gene?", "Which perturbation effects are most reproducible across studies?", "Can I filter results by cell line or tissue type?", "How reliable are the predicted gene-gene relationships?", "What's the difference between upregulated and downregulated targets?", "How do I interpret the confidence scores in the results?", "Can I get the complete list of affected genes not just top 50?", "What does high consistency score mean biologically?", "How many datasets support each gene-gene relationship?", "What experimental systems were used for my gene of interest?", "Can I compare perturbation effects across different genes?", "What should I do next after getting the perturbation results?", "How do I use these results for pathway enrichment analysis?", "Can I visualize the regulatory network for my gene?", "What genes have the strongest perturbation effects?", "How do I export the results for further custom analysis?"],
    "usage": "gpdb_what_happens(gene, context = NULL, aggregate = TRUE, top_n = 50)",
    "parameters": [
      {
        "name": "gene",
        "has_default": false,
        "description": "Character. Gene symbol to query (e.g., \"TP53\", \"MYC\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended."
      },
      {
        "name": "context",
        "has_default": true,
        "default_value": "NULL",
        "description": "List. Optional filters to restrict analysis to specific experimental conditions: cell_line: Specific cell line (e.g., \"K-562\", \"HeLa\") tissue: Specific tissue type (e.g., \"Liver\", \"Lung\") If NULL (default), queries all available datasets for comprehensive results."
      },
      {
        "name": "aggregate",
        "has_default": true,
        "default_value": "TRUE",
        "description": "Logical. Whether to return aggregated multi-dataset results (default TRUE). Should always be TRUE for typical use; internal parameter."
      },
      {
        "name": "top_n",
        "has_default": true,
        "default_value": "50",
        "description": "Integer. Number of top targets per direction to return (default 50). Larger values provide more comprehensive results. Recommended: 50 (focused), 100 (exploratory), or use result$all_effects for complete data."
      }
    ],
    "examples": "## No test: \n# ===========================================================================\n# Example 1: Basic Usage (TESTED - runtime: 0.116 sec)\n# ===========================================================================\n# Scientific Question: What happens when TP53 is knocked out?\n# Query: TP53 perturbation effects across all datasets\n# Expected output: Comprehensive target list with confidence scores\n\n# Zero configuration - database auto-loaded!\nlibrary(GenePerturbR)\n\nresult <- gpdb_what_happens(\"TP53\")\n\n# Natural language summary\ncat(result$summary)\n\n# Verify output structure\nstr(result, max.level = 1)\ncat(\"Datasets:\", result$stats$n_datasets, \"\\n\")\ncat(\"Targets found:\", result$stats$n_targets_total, \"\\n\")\ncat(\"High confidence:\", result$stats$n_high_confidence, \"\\n\")\n\n# Quick preview of top results\nhead(result$top_upregulated, 10)\nhead(result$top_downregulated, 10)\n\n# ===========================================================================\n# Example 2: Context-Specific Analysis (Cell line filtering)\n# ===========================================================================\n# Focus on specific experimental context\n\n# All contexts\nresult_all <- gpdb_what_happens(\"MYC\", top_n = 30)\n\n# K-562 cell line only (leukemia)\nresult_k562 <- gpdb_what_happens(\n  \"MYC\",\n  context = list(cell_line = \"K-562\"),\n  top_n = 30\n)\n\n# Compare context specificity\ncat(\"All contexts:\", result_all$stats$n_datasets, \"datasets\\n\")\ncat(\"K-562 only:\", result_k562$stats$n_datasets, \"datasets\\n\")\n\n# Check if targets differ by context\ncommon <- intersect(\n  result_all$top_upregulated$target_gene,\n  result_k562$top_upregulated$target_gene\n)\ncat(\"Common targets:\", length(common), \"/\", nrow(result_all$top_upregulated), \"\\n\")\n\n# ===========================================================================\n# Example 3: Filtering and Custom Analysis\n# ===========================================================================\n# Use all_effects for comprehensive filtering\n\nresult <- gpdb_what_happens(\"TP53\", top_n = 50)\n\n# Filter high-confidence targets with strong effects\nstrong_effects <- result$all_effects[\n  result$all_effects$confidence == \"high\" &\n    abs(result$all_effects$logfc_mean) > 1.5,\n]\n\n# Highly consistent findings only\nreproducible <- result$all_effects[\n  result$all_effects$consistency_score > 0.8 &\n    result$all_effects$n_datasets >= 5,\n]\n\n# Compare filtering results\ncat(\"All targets:\", nrow(result$all_effects), \"\\n\")\ncat(\"Strong effects:\", nrow(strong_effects), \"\\n\")\ncat(\"Highly reproducible:\", nrow(reproducible), \"\\n\")\n\n# Get average effect size for high-confidence targets\nhigh_conf <- result$all_effects[result$all_effects$confidence == \"high\", ]\ncat(\n  \"Avg effect size (high confidence):\",\n  mean(abs(high_conf$logfc_mean)), \"\\n\"\n)\n\n# ===========================================================================\n# Next Steps (Brief pointers to downstream analysis)\n# ===========================================================================\n# For complete workflows, see:\n# - Enrichment analysis: ?gpdb_enrich\n# - Network visualization: ?gpdb_plot_network\n# - Cascade analysis: ?gpdb_analyze_cascade\n# - Compare genes: ?gpdb_compare_genes\n# - Load raw data: ?gpdb_load_data\n## End(No test)\n\n\n\n",
    "return_value": "List containing five elements with comprehensive perturbation analysis: **Return Structure**: result$summary Natural language text summary describing gene perturbation effects, top targets, and dataset count (LLM-friendly format) result$top_upregulated Data.frame of top upregulated targets (genes increased by perturbation), sorted by effect size Key columns: target_gene , logfc_mean (avg log2FC), n_datasets , consistency_score , confidence result$top_downregulated Data.frame of top downregulated targets (genes decreased by perturbation). Same structure as top_upregulated. result$all_effects Data.frame of ALL target genes (complete results). Use for custom filtering or comprehensive analysis. Same columns as top results. result$stats List of summary statistics: n_datasets (experiment count), n_targets_total , n_upregulated , n_downregulated , n_high_confidence , avg_effect_size **Programmatic Access Examples**: Get top 10 upregulated: head(result$top_upregulated, 10) Filter high confidence: result$all_effects[result$all_effects$confidence == \"high\", ] Filter by effect size: result$all_effects[abs(result$all_effects$logfc_mean) > 1.5, ] Get upregulated names: result$top_upregulated$target_gene **What You Can Do Next**: Enrichment analysis: gpdb_enrich (result$top_upregulated$target_gene, enrich.type = \"GO\") Network visualization: gpdb_plot_network (gene, top_targets = 50) Compare with other genes: gpdb_compare_genes (c(gene, \"GENE2\")) Cascade analysis: gpdb_analyze_cascade (gene, steps = 2) Load raw data: gpdb_list_datasets (gene = gene) then gpdb_load_data (dataset_id) **Alternative Methods**: gpdb_find_targets : Use when you want filtered targets with specific confidence levels or effect sizes (more focused than what_happens) gpdb_find_regulators : Use when you want to find what CONTROLS a gene (reverse direction: who regulates X?) gpdb_load_deg : Use when you need complete DEG tables for specific datasets rather than aggregated results",
    "references": "Guo S, Xu Z, Dong X, Hu D, Jiang Y, Wang Q, Zhang J, Zhou Q, Liu S, Song W (2022). GPSAdb: a comprehensive web resource for interactive exploration of genetic perturbation RNA-seq datasets. Nucleic Acids Research, gkac1066. doi:10.1093/nar/gkac1066",
    "formatted_arguments": "gene: Character. Gene symbol to query (e.g., \"TP53\", \"MYC\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended.\ncontext: List. Optional filters to restrict analysis to specific experimental conditions: cell_line: Specific cell line (e.g., \"K-562\", \"HeLa\") tissue: Specific tissue type (e.g., \"Liver\", \"Lung\") If NULL (default), queries all available datasets for comprehensive results.\naggregate: Logical. Whether to return aggregated multi-dataset results (default TRUE). Should always be TRUE for typical use; internal parameter.\ntop_n: Integer. Number of top targets per direction to return (default 50). Larger values provide more comprehensive results. Recommended: 50 (focused), 100 (exploratory), or use result$all_effects for complete data.",
    "simple_arguments": "gene: Character. Gene symbol to query (e.g., \"TP53\", \"MYC\"). Must exist in database (use gpdb_search() to verify). Case-insensitive but uppercase recommended."
  }
}