README.md

---
title: OSI Data Browser
emoji: 🔬
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---

[![Sync to Hugging Face hub](https://github.com/OpenSyndrome/data-browser/actions/workflows/huggingface.yaml/badge.svg)](https://github.com/OpenSyndrome/data-browser/actions/workflows/huggingface.yaml)

# Open Syndrome Definition - Data Browser

An interactive data browser built with [Marimo](https://marimo.io) that lets you filter epidemiological datasets using [Open Syndrome Definition (OSD)](https://github.com/OpenSyndrome/schema) criteria, powered by the [`opensyndrome`](https://github.com/OpenSyndrome/open-syndrome-python) Python package.

## How it works

1. Load a dataset (CSV) — use the built-in example or upload your own.
2. Map your dataset columns to OSD concepts via an editable YAML form.
3. Select one or more syndromic indicators from the definitions catalogue.
4. The engine compiles each OSD criterion into a [Polars](https://pola.rs) expression and labels matching rows.
5. Explore results through time-series and diagnosis-code charts.

## Quick start

```bash
# Local development
uv sync
uv run marimo run filter_engine.py

# Docker
docker build -t osi-browser .
docker run -p 7860:7860 osi-browser
```

Then open <http://localhost:7860> in your browser.

## Column mapping format

```yaml
profiles:
  - name: my_dataset
    # value_encodings:  # optional — map OSD canonical values to dataset-specific ones
    #   sex:
    #     male: "M"
    #     female: "F"
    columns:
      my_diagnosis_column:
        concept: diagnosis
        dtype: string
      # my_age_column:
      #   concept: demographic_criteria
      #   attribute: age
      #   dtype: integer
```

## Deploy

This app is hosted on [Hugging Face Spaces](https://huggingface.co/spaces) using the Docker SDK.

Push to the Space's `main` branch to trigger a rebuild:

```bash
git remote add space https://huggingface.co/spaces/<your-username>/osi-data-browser
git push space main
```