Exercise 1: Cataloging and data discovery

Work in progress. These tutorial materials are still under active development and will continue to change until the tutorial takes place on October 20, 2026. Content, links, and exercises may be incomplete or shift without notice.

Goal

Identify a candidate dataset based on a dataset fitness decision tied to a specific research question and then author a machine-actionable metadata record for use in the GAIA catalog.

Background

Discovery fails in predictable ways: the same label attached to a different variable, mismatched geography, incomplete temporal coverage, an unclear unit, an unstable URL, or a restrictive license. Treat the GAIA catalog as an executable contract between discovery and ingestion, not a simple bibliography but more like an annotated machine readable and machine actionable bibliography — the record you produce here has to be precise enough that Session 2’s pipeline can act on it directly.

Learning Outcomes

  1. Describe difference between raster and vector GIS data
  2. Describe spherical vs. Cartesian coordinate systems in the context of GIS
  3. Identify GIS dataset requirements for OHDSI GIS analytic pipeline
  4. Match requirements to publicly available datasets
  5. Make a dataset ingestion request with sufficient information to create a machine actionable catalog entry
  6. Understand the workflow to create a schema.org compliant JSON-LD catalog entry
  7. Match requirements to entries in the Gaia Catalog

Steps

Activity 1.

Seek a partner to form a pair and then:

  1. Start from a research question (exposure to PM 2.5 and COPD health outcomes) and decompose it into its computable requirements: population, index time, exposure window, lag, geography, variable, unit, resolution, provenance, and permissible missingness. [it seems we will do this togehter as a guided excercise]
  2. Search publicly available datasets for PM2.5 to identify one best candidate that meets your requirements
  3. Inspect the candidate’s spatial coverage, temporal coverage, variable definition, unit, and access URL.
  4. Score the candidate against the fitness rubric: scientific relevance, spatial fit, temporal fit, semantic clarity, access, and reproducibility (green/amber/red per criterion).

Share these results with the tutorial group.

Activity 2.

With the same partner for the first activity:

  1. Complete the metadata template for your chosen dataset in kobotoolbox, keeping dataset-level properties (identity, version, provider, license, URL, spatial/temporal coverage, geometry, retrieval method, update cadence) separate from variable-level properties (definition, unit).
  2. Observe the workflow to crosswalk the kobotoolbox entry to a RO Crate inspired object that includes schema.org JSON-LD metadata and bash ingestion scripts.
  3. Search the GAIA catalog for your candidate dataset (e.g., an air-quality dataset) that could answer your decomposed question.
  4. Record your overall fitness decision and, if any criterion scored amber or red, document the limitation rather than silently proceeding.

Share these results with the tutorial group.

If you get stuck on a step, faculty will circulate and a fallback dataset/metadata record is available.

Deliverable

  • Two draft metadata records ready to be transformed to JSON-LD aligned to schema.org for interoperability and machine actionability
  • One fitness decision (green/amber/red per rubric criterion, plus an overall call)

Check Your Work

Faculty will validate your submission against the following criteria, and so should you before calling it done:


Bridge to Session 2: your frozen metadata record and its downloadable source become the input to the ingestion pipeline.


Next: Exercise 2