Skip to content

README.md

Latest commit

 

History

History
165 lines (120 loc) · 5.28 KB

README.md

File metadata and controls

165 lines (120 loc) · 5.28 KB
Raw

Website Scripts

extract_metadata.py

Imports task classes from the installed pyhealth package and writes data/tasks.json. Run this whenever a task class is added or renamed.

Prerequisites: pyhealth installed in your active Python environment.

# From the pyhealth.github.io repo root:
python scripts/extract_metadata.py

# Custom output path:
python scripts/extract_metadata.py --output data/tasks.json

Output goes to data/tasks.json by default.

Workflow for adding a new task

  1. Add the task class to PyHealth/pyhealth/tasks/.
  2. Run the script to regenerate data/tasks.json.
  3. Add one entry to data/tasks_extra.json (see format below).
  4. Commit both JSON files — the site renders from them automatically.

data/tasks.json (auto-generated, do not hand-edit)

Each entry is one Python class found in pyhealth/tasks/:

{
  "class_name":    "MortalityPredictionMIMIC3",
  "task_name":     "MortalityPredictionMIMIC3",
  "description":   "Task for predicting mortality using MIMIC-III...",
  "input_schema":  {"conditions": "sequence", "procedures": "sequence"},
  "output_schema": {"mortality": "binary"},
  "output_type":   "binary",
  "source_file":   "pyhealth/tasks/mortality_prediction.py"
}

output_type is inferred from output_schema values. Classes that set their schema dynamically in __init__ will have null here — override via tasks_extra.json.

dataset_classes is read from the task's docstring: every :class:`~pyhealth.datasets.X` it cites (PyHealth task docstrings say "Works with :class:~pyhealth.datasets.X."). tasks.html turns these into dataset pills that link to datasets.html#X, and datasets.html lists each dataset's tasks from them, so a new task shows up in both places after you rerun the script. Hand-written datasets labels are only a fallback for entries without dataset_classes.

data/datasets.json (hand-authored)

One entry per pyhealth.datasets class, keyed by class name. datasets.html uses it for each card's access badge and "Get the data" link, and tasks.html for the pill labels. The facts match the "Getting the data" section of each dataset's docstring in PyHealth; update both together.

Field Required Description
label Yes Short pill label, e.g. "MIMIC-III"
access Yes open, restricted, credentialed, or format
access_note Yes One line on what access takes
source_url Yes Where to download it
demo_label, demo_url No An open demo or subset
anchor No Card to link to when the class has no card of its own

A new dataset card needs id="<ClassName>" on its .dataset-card div so datasets.html#<ClassName> links land on it.

data/tasks_extra.json (hand-authored)

Controls which tasks appear on the site and in what order. Fields:

Field Required Description
class_name Yes Python class name — used to join with tasks.json
display_name Yes Human-readable title shown on the card
display_class No Short name shown in the code snippet (defaults to class_name)
datasets Yes Array of dataset pill labels, e.g. ["MIMIC-III"]
description Yes One-sentence description for the card
colab_url No Colab notebook URL
docs_url No ReadTheDocs URL (defaults to the tasks index page)
output_type No Override auto-detected type (needed when schema is set in __init__)

Minimal entry:

{
  "class_name":   "MyNewTask",
  "display_name": "My New Task",
  "datasets":     ["MIMIC-IV"],
  "description":  "One sentence for the website card.",
  "colab_url":    "https://colab.research.google.com/drive/..."
}

Testing locally

The site fetches JSON via fetch(), so it must be served over HTTP:

cd /path/to/pyhealth.github.io
python -m http.server 8080
# open http://localhost:8080/tasks.html

build_blog_index.py (blog index + metadata)

This script scans the blogs/ folder and writes the blog index used by the site.

  • Input: blogs/YYYY-MM-DD/*.md (uses the first .md file in each dated folder)
  • Output: data/blogs.json
  • What it computes: title/author (from frontmatter or # ...), preview text, word_count, and read_time_min (based on words-per-minute).

Run it whenever you:

  • add a new blog post folder,
  • rename the .md file inside a post folder,
  • or change post content and want preview / word_count / read_time_min updated.
# From the pyhealth.github.io repo root:
python scripts/build_blog_index.py

How blog pages render

  • blog_list.html loads data/blogs.json to render the list.
  • blog.html?post=YYYY-MM-DD loads data/blogs.json to find the markdown filename, then fetches blogs/YYYY-MM-DD/<file>.md and converts the Markdown to HTML in the browser.

Previewing the blog locally

Because the site uses fetch(), preview via an HTTP server:

cd /path/to/pyhealth.github.io
python -m http.server 8080
# open http://localhost:8080/blog_list.html

To open a specific post:

  • http://localhost:8080/blog.html?post=YYYY-MM-DD