OHDSI GIS WG

Developer Resources

Welcome to the OHDSI GIS Working Group developer hub. This section provides comprehensive information for developers contributing to the Gaia toolchain and related GIS infrastructure.

Overview

The OHDSI GIS Working Group develops and maintains a suite of tools collectively known as the Gaia toolchain. These tools enable the integration of geospatial data with OMOP Common Data Model (CDM) for population health research.

Repository Ecosystem

Central Hub

• OHDSI/GIS - This repository serves as the central coordination point
  • Documentation website (https://ohdsi.github.io/GIS/)
  • Use case tracking
  • Project management via GitHub Projects
  • Contributing guidelines

Core Packages

gaiaDb - Technology: PostgreSQL/PostGIS - Purpose: Core data repository with geospatial processing capabilities - Maintainers: See repository - Key Features: - Geospatial data ingestion, management, and analysis - SQL routines and PostGIS functionality - OMOP CDM integration - LinkML/JSON-LD metadata support - Spatial indexing and optimization

gaiaCore - Development: TuftsCTSI/gaiaCore - Technology: Multi-language connector framework - Purpose: Provides access to gaiaDB functionality across multiple languages and paradigms - Maintainers: See repository - Key Features: - RESTful API access via PostgREST - Direct database connection support - Language-specific client libraries (R, Python, etc.) - Orchestrates functions defined in gaiaDB - OpenAPI specification for API endpoints

gaiaCatalog - Technology: Schema.org compliant metadata - Purpose: Data source discovery and cataloging - Maintainers: See repository - Key Features: - Metadata management - Federated data source discovery - Schema.org compliance - Integration with external catalogs

gaiaDocker - Technology: Docker Compose orchestration - Purpose: Coordinated deployment and versioned releases of the Gaia toolchain - Maintainers: See repository - Key Features: - Complete GIS stack containerization - Coordinated image builds across all components - Version management and releases - Profile-based deployment (gaia, degauss) - Integration with OHDSI Broadsea ecosystem

Vocabulary Resources

TuftsCTSI/CVB - Purpose: OMOP vocabulary extensions for GIS - Key Vocabularies: - OMOP GIS Vocabulary - OMOP Exposome Vocabulary - OMOP SDoH Vocabulary - Toxins Vocabulary - Location: Delta files in CVB/GIS/Ontology

Architecture Overview

Data Flow

External Geospatial Data → gaiaCatalog (Discovery)
                                ↓
                           gaiaDb (Backend Repository)
                           ├── Data Ingestion
                           ├── SQL Routines & PostGIS Functions
                           ├── OMOP Integration
                           └── Exposure Calculation
                                ↓
                           gaiaCore (Access Layer)
                           ├── RESTful API (PostgREST)
                           └── Language Connectors (R, Python, etc.)
                                ↓
                      OMOP CDM + GIS Extensions
                                ↓
                           HADES Analytics

Tool Chain Components

1. Data Discovery (gaiaCatalog)
   • Input: External data source metadata
   • Output: Cataloged, discoverable datasets
2. Backend Engine (gaiaDb)
   • Input: Raw geospatial datasets, patient locations
   • Processing: SQL routines, PostGIS functions, spatial operations
   • Output: OMOP-compliant external exposure data, standardized spatial tables
3. Access Layer (gaiaCore)
   • Input: Requests via API or database connections
   • Processing: Orchestrates gaiaDB functions, provides multi-language access
   • Output: Data and function access through RESTful API or direct database connections
4. Deployment (gaiaDocker)
   • Input: Component configurations
   • Processing: Orchestrated container deployment
   • Output: Running Gaia toolchain with versioned releases
5. Analytics (HADES integration)
   • Input: OMOP CDM + GIS extensions
   • Output: Evidence generation

Getting Started as a Developer

Prerequisites

• PostgreSQL/PostGIS (>= 12/3.0) for gaiaDb
• Docker and Docker Compose (recommended for coordinated deployment)
• Git and GitHub account
• OHDSI Teams access (sign up)
• Programming environment of choice (R, Python, etc.) for using gaiaCore connectors

Development Environment Setup

Option 1: gaiaDocker (Recommended)

# Clone gaiaDocker repository
git clone https://github.com/OHDSI/gaiaDocker.git
cd gaiaDocker

# Start the full Gaia stack
docker compose --profile gaia up -d

# Verify services
docker compose ps

Option 2: Local Development

1. Clone the gaiaDb repository and set up PostgreSQL/PostGIS
2. Configure PostgREST for API access
3. Install language-specific connectors (R, Python, etc.)
4. Configure connection parameters

See Deployment Strategies for detailed setup instructions.

First Contribution

1. Join the GIS Working Group on Teams
2. Attend the weekly Friday meeting (10 AM US Eastern)
3. Review the Project Board
4. Pick a task or propose a new one
5. Read Contributing Guidelines

Development Workflow

The GIS Working Group follows an agile, use-case-driven development approach:

1. Use Case Identification - Real-world research needs drive development
2. Task Breakdown - Use cases decomposed into GitHub issues
3. Sprint Planning - Tasks assigned and tracked via GitHub Projects
4. Weekly Standups - Friday meetings (2 min max per person):
   • What did you complete last week?
   • What are you working on now?
   • What’s blocking you?
   • Discussion points for later
5. Development - Feature branches, pull requests, code review
6. Integration - Merge to main, deploy, document

Key Resources

• Package Status & Maintainers
• Contributing Guidelines
• Architecture & Data Flows
• Deployment Strategies
• Project Board

Working Group Leadership

Co-Leaders: - Robert Miller - Jared Houghtaling

Contributing to Leadership: The working group welcomes members who want to take on additional responsibilities. Express interest during weekly meetings or via Teams.

Communication Channels

• Weekly Meetings: Fridays 10 AM US Eastern (Teams Link)
• MS Teams: GIS Working Group channel
• GitHub Issues: Bug reports, feature requests, use cases
• OHDSI Forums: Developers section
• Email: zollovenecek[at]ohdsi[dot]org

Support

• General Questions: OHDSI Forums
• Bug Reports: GitHub Issues (repository-specific)
• Development Help: GIS Teams channel or weekly meetings
• Use Case Discussion: Schedule with working group leaders