🧬 GeoVectorSearch

GeoVectorSearch is a lightweight Python SDK and command-line tool for discovering high-quality GEO gene expression datasets relevant to a disease or biological condition — optimized for differential expression (DE) analysis.

It combines semantic search using sentence embeddings with optional GPT-based filtering to help you rapidly identify suitable datasets for your research or pipeline.

🔍 Features

• ✅ Natural language search for GEO datasets
• ⚡ Fast vector search using FAISS and prebuilt sentence embeddings
• 🧠 Optional GPT filtering to assess dataset quality for DE analysis - supports basic GPT filtering and enhanced GPT filtering which segregates the datasets into tiers: Tier 1: Highly suitable for DE studies, Tier 2: Suitable for DE studies but the samples come from cell lines/ organoids/ xenografts, and Tier 3: Not directly suitable for DE studies but can be used for exploratory studies
• 🧬 Supports microarray and RNA-seq datasets
• 🖥️ Interactive CLI for a smooth user experience
• 🧩 Easy to integrate into larger pipelines or SDKs
• 💾 Save results locally for downstream analysis

📦 Installation

Install using your preferred package manager:

uv pip install geo-pysearch

Or clone the repository and install locally:

git clone https://github.com/Tinfloz/geo-vector-search.git
cd geo-vector-search
uv pip install .

🧪 Example (Python SDK)

from geo_pysearch.sdk import search_datasets

results = search_datasets(
    query="duchenne muscular dystrophy",
    dataset_type="microarray",
    gpt_filter_type="enhanced",
    top_k=50,
    use_gpt_filter=True,
    return_all_gpt_results=True
)

print(results.head())

Convenience methods:

from geo_pysearch.sdk import search_microarray, search_rnaseq

search_microarray("breast cancer")
search_rnaseq("lung fibrosis", use_gpt_filter=True)

💻 Example (CLI)

Launch the interactive CLI:

geo-search

• Use the arrow keys to select dataset type and filtering options
• Enter your disease query
• Results will be saved to a local CSV file in a new directory
• Review and use the datasets for downstream DE analysis

🧠 GPT Filtering (Optional)

If enabled, the SDK uses GPT to evaluate whether each dataset is suitable for differential gene expression analysis. You can configure GPT behavior with:

• Adjustable confidence thresholds

📁 Project Structure

gse-pysearch/
├── geo_pysearch/
│   ├── data/                # Prebuilt FAISS index, vectors, metadata
│   ├── vector_search/
│   │   ├── vector_search.py
│   │   ├── gpt_filter.py
│   │   ├── tiered_gpt_filter.py
│   ├── sdk.py               # Main SDK interface
│   └── cli.py               # CLI implementation
├── examples/                # Example usage scripts
├── .env                     # Optional environment variables

🛠️ Requirements

• Python 3.12+
• faiss-cpu, pandas, sentence-transformers

📖 License

GNU General Public License v3.0

This project is licensed under the GNU GPLv3, which guarantees end users the freedom to run, study, share, and modify the software.

If you redistribute or modify this software, your contributions must also be licensed under the same terms.

References

This project implements semantic query generation and evidence extraction strategies inspired by:

1. Deka, P., Jurek-Loughrey, A., & others. (2022). Evidence Extraction to Validate Medical Claims in Fake News Detection. International Conference on Health Information Science, pp. 3–15.

2. Deka, P., & Jurek-Loughrey, A. (2021). Unsupervised Keyword Combination Query Generation from Online Health Related Content for Evidence-Based Fact Checking. The 23rd International Conference on Information Integration and Web Intelligence, pp. 267–277.