{"repo": "bioinfoxp/geollm", "files": {"README.md": {"67c0769dc43538fa4bfb46c09117c56f69bc4a06": {"t": 1785674114.0085902, "n": 5050, "h": "10ea8c268e1629cd", "c": "---\n\n# geoLLM 🧬🤖\n\n[](https://www.google.com/search?q=https://github.com/BioinfoXP/geoLLM/actions)\n[](https://www.google.com/search?q=https://lifecycle.r-lib.org/articles/stages.html%23experimental)\n**geoLLM** is an R package designed to revolutionize how researchers filter Gene Expression Omnibus (GEO) metadata.\n\nUnlike traditional methods that rely on rigid Regular Expressions (Regex) or manual keyword searching, **geoLLM uses Large Language Models (LLMs)** to semantically understand and classify datasets. It can distinguish between \"Pancreatic Cancer\" and \"Liver Cancer\" even if the text is complex, and accurately identify sequencing types (scRNA-seq, Spatial, Bulk) from messy descriptions.\n\n## 🌟 Key Features\n\n* **🧠 Pure AI Screening**: No keyword hard-coding. It understands context: \"10x Chromium\"  \"Single Cell\"  \"scRNA-seq\".\n* **📚 Rich Built-in Database**: Comes pre-loaded with **1,975 verified datasets** covering **scRNA-seq, Spatial Transcriptomics, Bulk RNA-seq, and Microarray**. Ready to query out-of-the-box!\n* **⚡ Batch Processing**: Automatically handles large datasets (e.g., 2000+ rows) in smart batches to handle token limits efficiently.\n* **🏷️ Auto-Classification**: Turns messy raw metadata into standardized categories (`AI_SeqType`).\n* **🌐 Multi-Language Support**: Search using Chinese or English queries; the AI understands both perfectly.\n\n## 📦 Installation\n\nYou can install the development version of geoLLM from GitHub:\n\n```r\n# Install devtools if you haven't already\nif (!requireNamespace(\"devtools\", quietly = TRUE))\n    install.packages(\"devtools\")\n\n# Install geoLLM\ndevtools::install_github(\"BioinfoXP/geoLLM\")\n\n```\n\n## 🔑 Configuration\n\nBefore using the package, you need to set up your LLM API key. This package is compatible with OpenAI-style APIs (e.g., OpenAI, SiliconFlow, DeepSeek).\n\n```r\nlibrary(geoLLM)\n\n# Option 1: Set environment variable (Recommended for security)\nSys.setenv(OPENAI_API_KEY = \"sk-xxxxxxxxxxxxxxxxxxxxxxxx\")\n\n# Option 2: Pass directly in functions\n# api_key = \"sk-...\"\n\n```\n\n> **Note:** The package defaults to `gpt-5-nano` via `https://api.gpt.ge/v1`. You can customize the `base_url` and `model` in all functions.\n\n## 🚀 Quick Start\n\n### Scenario 1: Mining the Built-in Database (Zero Setup)\n\n**geoLLM** includes a massive built-in database of **1,975 datasets**. You don't need to load any files to start mining data immediately.\n\n```r\nlibrary(geoLLM)\n\n# 1. Check what's inside the built-in database\ndata(\"geo_database\")\ntable(geo_database$AI_SeqType)\n# Output example:\n# Bulk RNA-seq   Microarray    scRNA-seq    stRNA-seq        Other\n#          850          600          500           25            0\n\n# 2. Screen with AI (e.g., finding Spatial Transcriptomics for Pancreatic Cancer)\nresults <- GEO_Screen_AI(\n  disease = \"胰腺癌\",           # AI understands Chinese input\n  data_type = \"空间转录组\",      # AI maps this to \"stRNA-seq/Visium\"\n  model = \"gpt-5-nano\"\n)\n\n# 3. View your filtered results\nprint(head(results))\n\n```\n\n### Scenario 2: Processing Your Own Raw Data\n\nIf you have a raw Excel file exported from GEO (e.g., `geo_results.xlsx`), follow this workflow:\n\n#### Step 1: Load and Classify\n\nFirst, use `GEO_Classify_AI` to clean the data and add an `AI_SeqType` tag.\n\n```r\nlibrary(readxl)\n\n# 1. Read your raw data\nraw_df <- read_excel(\"path/to/your/file.xlsx\")\n\n# 2. Classify (Standardize metadata)\n# This adds a column 'AI_SeqType' (scRNA-seq, Bulk, etc.)\nclean_df <- GEO_Classify_AI(\n  input_data = raw_df,\n  api_key = \"your_api_key\",\n  model = \"gpt-5-nano\"\n)\n\n# (Optional) Save the cleaned data for future use\nsave(clean_df, file = \"my_clean_geo_data.Rdata\")\n\n```\n\n#### Step 2: Screen with AI\n\nNow use `GEO_Screen_AI` to find exactly what you need from your cleaned data.\n\n```r\n# Screen for specific criteria\nfinal_list <- GEO_Screen_AI(\n  input_data = clean_df,\n  disease = \"Hepatocellular Carcinoma\",\n  data_type = \"scRNA-seq\",\n  other_req = \"Exclude cell lines and xenografts\",\n  target_species = \"Homo sapiens\",\n  api_key = \"your_api_key\"\n)\n\n# Result is sorted by Sample Size automatically\nprint(final_list)\n\n```\n\n## 📋 Input Data Requirements\n\nIf you provide your own `input_data`, it should be a `data.frame` containing at least the following columns (names are auto-detected, but standard names help):\n\n| Column Content | Recommended Names |\n| --- | --- |\n| **ID** | `GSE`, `Accession`, `dataset_id` |\n| **Description** | `Title`, `Summary`, `Description`, `experimental_design` |\n| **Species** | `Species`, `Organism` |\n| **Platform** | `Platform`, `GPL`, `sequencing_platform` |\n| **Sample Size** | `Sample_Count`, `N`, `sample_size` |\n\n## 🛠 Advanced Usage\n\n### Changing API Provider\n\nYou can easily switch to other LLM providers like **DeepSeek** or **SiliconFlow**:\n\n- https://cloud.siliconflow.cn/i/zIsztzpU\n\n```r\nres <- GEO_Screen_AI(\n  disease = \"Liver Cancer\",\n  base_url = \"https://api.siliconflow.cn/v1\", # Change the API URL\n  model = \"deepseek-ai/DeepSeek-V3\",          # Change the model\n  api_key = \"sk-...\"\n)\n\n```\n\n## 📄 License\n\nMIT © [BioinfoXP]\n"}}}}