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 - Technology: R package (DatabaseConnector); Docker image ohdsi/gaia-core - Purpose: R interface to gaiaDB: runs the Gaia pipeline and provides quality checks and exposure analytics - Maintainers: See repository - Key Features: - Direct database connection (no REST layer) - Ingestion, location loading and the spatial-temporal join from R - Quality checks and copy into the OMOP CDM - Day-weighted exposure and cluster-robust effect estimates - Python, Java, Julia, Bash and PostgREST clients on the connectors branch

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 (R package)
                           ├── Direct database connection
                           ├── Pipeline, quality checks, copy into the CDM
                           └── Exposure analytics
                                ↓
                      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. R Interface (gaiaCore)
   • Input: Catalog dataset ids, person locations and residence histories
   • Processing: Calls gaiaDB functions over a direct connection, checks the derived rows, computes exposure analytics
   • Output: Exposure in the OMOP CDM (EXTERNAL_EXPOSURE) and analysis-ready summaries
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)
• R (or the ohdsi/gaia-core Docker image) for using gaiaCore

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. Install the gaiaCore R package (remotes::install_github("OHDSI/gaiaCore"))
3. Configure the database connection with createGaiaConnectionDetails()

See Deployment Strategies for detailed setup instructions.

First Contribution

1. Join the GIS Working Group on Teams
2. Attend the weekly Thursday 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 - Thursday 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

Docker Image Status

Image status is read from Docker Hub when the site is built, so the dates reflect the most recent build of the site.

Image	Tag	Purpose	Status	Last built
ohdsi/gaia-db	main	PostgreSQL/PostGIS database (gaiaDb)	Published	2026-10-06
ohdsi/gaia-core	main	RStudio, HADES, gaiaCore (tutorial and benchmark image)	Published	2026-10-08
ohdsi/gaia-postgrest	main	PostgREST API (optional)	Published	2026-10-07
ohdsi/gaia-catalog	main	Catalog interface	Published	2026-10-09
ohdsi/gaia-solr	main	Catalog search index	Published	2026-10-09

The ETL helper images (gaia-osgeo, gaia-postgis, gaia-gdsc, gaia-git, gaia-degauss) are built locally by gaiaDocker and are not published.

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: Thursdays 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