Skip to content

Commit 068c87d

Browse files
jhnwu3John Wu
jhnwu3
and
John Wu
authored
more tutorial and doc updates (#529)
* more tutorial and doc updates * fix grammar --------- bypassing protections because it's a .rst docs update. Co-authored-by: John Wu <johnwu3@sunlab-work-01.cs.illinois.edu>
1 parent ce02081 commit 068c87d

3 files changed

Lines changed: 218 additions & 4 deletions

File tree

‎docs/how_to_contribute.rst‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
.. _how_to_contribute:
2+
3+
=====================
4+
How to Contribute
5+
=====================
6+
7+
We welcome contributions to PyHealth! This guide will help you get started with contributing datasets, tasks, models, bug fixes, or other improvements to the project.
8+
9+
Getting Started
10+
===============
11+
12+
Prerequisites
13+
-------------
14+
15+
PyHealth uses GitHub for development, so you'll need a GitHub account to contribute.
16+
17+
Setting Up Your Development Environment
18+
---------------------------------------
19+
20+
To start contributing to PyHealth:
21+
22+
1. **Fork the PyHealth repository** on GitHub
23+
2. **Clone your forked repository** to your local machine:
24+
25+
.. code-block:: bash
26+
27+
git clone https://github.com/your_username/PyHealth.git
28+
cd PyHealth
29+
30+
3. **Install dependencies**:
31+
32+
.. code-block:: bash
33+
34+
pip install mne pandarallel rdkit transformers accelerate polars
35+
36+
4. **Implement your code** with proper test cases
37+
5. **Push changes** to your forked repository
38+
6. **Create a pull request** to the main PyHealth repository
39+
40+
- Target the ``main`` branch
41+
- Enable edits by maintainers
42+
- Rebase with the remote ``sunlabuiuc`` main branch before creating the PR
43+
44+
Implementation Requirements
45+
===========================
46+
47+
Code File Headers
48+
-----------------
49+
50+
For new contributors, include the following information at the top of your code files:
51+
52+
- Your name(s)
53+
- Your NetID(s) (if applicable for UIUC students)
54+
- Paper title (if applicable to a reproducibility contribution)
55+
- Paper link (if applicable)
56+
- Description of the task/dataset/model you're implementing
57+
58+
Code Style and Documentation
59+
-----------------------------
60+
61+
**General Guidelines:**
62+
63+
- Use object-oriented programming with well-defined and typed functions
64+
- Follow snake_case naming for variables and functions (e.g., ``this_variable``)
65+
- Use PascalCase for class names (e.g., ``ThisClass``)
66+
- Follow PEP8 style with 88 character line length
67+
- Use Google style for docstrings
68+
69+
**Function Documentation Requirements:**
70+
71+
Each function must document:
72+
73+
- **Input arguments**: Define variable types and descriptions
74+
- **Output arguments**: Define variable types and descriptions
75+
- **High-level description** of what the function does
76+
- **Example use case** or where it will be called
77+
78+
**Example Well-Documented Function:**
79+
80+
.. code-block:: python
81+
82+
def parse_basic_info(self, patients: Dict[str, Patient]) -> Dict[str, Patient]:
83+
"""Helper functions which parses patients and admissions tables.
84+
85+
Will be called in `self.parse_tables()`
86+
87+
Docs:
88+
- patients: https://mimic.mit.edu/docs/iv/modules/hosp/patients/
89+
- admissions: https://mimic.mit.edu/docs/iv/modules/hosp/admissions/
90+
91+
Args:
92+
patients: a dict of `Patient` objects indexed by patient_id.
93+
94+
Returns:
95+
The updated patients dict.
96+
"""
97+
98+
Types of Contributions
99+
======================
100+
101+
Contributing a Dataset
102+
----------------------
103+
104+
All datasets must follow these guidelines:
105+
106+
- **Inherit from BaseDataset**: All datasets must inherit from the appropriate BaseDataset class
107+
- **Follow established patterns**:
108+
109+
- For EHR datasets: See the `MIMIC4 dataset example <https://github.com/sunlabuiuc/PyHealth/blob/main/pyhealth/datasets/mimic4.py>`_
110+
- For image datasets: See the `CovidCXR dataset example <https://github.com/sunlabuiuc/PyHealth/blob/main/pyhealth/datasets/covidcxr.py>`_ where each folder represents a sample
111+
112+
- **Include a test task**: Datasets should ideally have an associated task for testing purposes
113+
114+
**Key Requirements:**
115+
116+
- Define all required variables outlined in the BaseDataset documentation
117+
- Provide clear data loading and processing methods
118+
- Include proper error handling and validation
119+
120+
Contributing a Task
121+
-------------------
122+
123+
Tasks must follow the established task class structure:
124+
125+
- **Inherit from base task class**: Follow the pattern defined in existing tasks
126+
- **Examples to reference**:
127+
128+
- `Mortality prediction task <https://github.com/sunlabuiuc/PyHealth/blob/main/pyhealth/tasks/mortality_prediction.py>`_
129+
- `X-ray classification task <https://github.com/sunlabuiuc/PyHealth/blob/main/pyhealth/tasks/chest_xray_classification.py>`_
130+
131+
- **Flexibility**: Tasks can include various implementation details but must have clear inputs/outputs
132+
- **Test cases**: Include example test cases with defined inputs and expected outputs
133+
134+
Contributing a Model
135+
--------------------
136+
137+
Models must follow the model base class structure:
138+
139+
- **Inherit from BaseModel**: All models must inherit from the appropriate base model class
140+
- **Reference implementation**: See the `RNN model example <https://github.com/sunlabuiuc/PyHealth/blob/main/pyhealth/models/rnn.py>`_
141+
- **Test cases**: Include example test cases with dummy inputs and expected outputs
142+
143+
**Key Requirements:**
144+
145+
- Implement required abstract methods from the base class
146+
- Provide clear forward pass implementation
147+
- Include proper initialization and configuration methods
148+
149+
Test Case Requirements
150+
======================
151+
152+
Every contribution must include two types of test cases:
153+
154+
1. **Automated tests**: These will be run by our continuous integration system
155+
2. **Manual test cases**: You must define these yourself with:
156+
157+
- Clear input specifications
158+
- Expected output formats
159+
- Example usage demonstrating functionality
160+
161+
**Note**: You can use frontier LLMs to help generate basic test cases, which we consider valid as long as they are reasonable and comprehensive.
162+
163+
Pull Request Guidelines
164+
=======================
165+
166+
Formatting Your Pull Request
167+
----------------------------
168+
169+
Every pull request must include the following information in the comment:
170+
171+
1. **Who you are** (include NetID if you're an Illinois student)
172+
2. **Type of contribution** (dataset, task, model, bug fix, etc.)
173+
3. **High-level description** of what you've implemented
174+
4. **File guide**: Quick rundown of which files to examine to test your implementation
175+
176+
**Example PR Description:**
177+
178+
.. code-block:: text
179+
180+
**Contributor:** Jane Doe (jdoe2@illinois.edu)
181+
182+
**Contribution Type:** New Dataset
183+
184+
**Description:** Added support for the XYZ Hospital dataset with patient
185+
admission records and diagnostic codes. Includes data preprocessing and
186+
sample task for mortality prediction.
187+
188+
**Files to Review:**
189+
- `pyhealth/datasets/xyz_hospital.py` - Main dataset implementation
190+
- `pyhealth/tasks/xyz_mortality.py` - Example task
191+
- `tests/core/test_xyz_dataset.py` - Test cases
192+
193+
Review Process
194+
--------------
195+
196+
After submitting your pull request:
197+
198+
1. Maintainers will review your code for style, functionality, and completeness
199+
2. Automated tests will be run to ensure compatibility
200+
3. You may be asked to make revisions based on feedback
201+
4. Once approved, your contribution will be merged into the main branch
202+
203+
Getting Help
204+
============
205+
206+
If you need assistance:
207+
208+
- Check existing issues and discussions on GitHub
209+
- Review similar implementations in the codebase
210+
- Reach out to maintainers through GitHub issues
211+
- Consider using LLMs to help with code formatting and documentation
212+
213+
We appreciate your contributions to making PyHealth better for the healthcare AI community!

‎docs/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -302,7 +302,7 @@ GRASP deep learning ``pyhealth.models.GRASP`
302302

303303
install
304304
tutorials
305-
advance_tutorials
305+
.. advance_tutorials
306306

307307

308308
.. toctree::
@@ -326,6 +326,7 @@ GRASP deep learning ``pyhealth.models.GRASP`
326326
:hidden:
327327
:caption: Additional Information
328328

329+
how_to_contribute
329330
live
330331
log
331332
about

‎docs/tutorials.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
Tutorials
22
========================
33

4-
We provide the following tutorials to help users get started with our pyhealth. Please bare with us as we update the docuemntation on how to use pyhealth.
4+
We provide the following tutorials to help users get started with our pyhealth. Please bear with us as we update the documentation on how to use pyhealth 2.0.
55

66

77
`Tutorial 0: Introduction to pyhealth.data <https://colab.research.google.com/drive/1y9PawgSbyMbSSMw1dpfwtooH7qzOEYdN?usp=sharing>`_ `[Video] <https://www.youtube.com/watch?v=Nk1itBoLOX8&list=PLR3CNIF8DDHJUl8RLhyOVpX_kT4bxulEV&index=2>`_
88

9-
`Tutorial 1: Introduction to pyhealth.datasets <https://colab.research.google.com/drive/18kbzEQAj1FMs_J9rTGX8eCoxnWdx4Ltn?usp=sharing>`_ `[Video] <https://www.youtube.com/watch?v=c1InKqFJbsI&list=PLR3CNIF8DDHJUl8RLhyOVpX_kT4bxulEV&index=3>`_
9+
`Tutorial 1: Introduction to pyhealth.datasets <https://colab.research.google.com/drive/1voSx7wEfzXfEf2sIfW6b-8p1KqMyuWxK?usp=sharing>`_ `[Video (PyHealth 1.6)] <https://www.youtube.com/watch?v=c1InKqFJbsI&list=PLR3CNIF8DDHJUl8RLhyOVpX_kT4bxulEV&index=3>`_
1010

11-
`Tutorial 2: Introduction to pyhealth.tasks <https://colab.research.google.com/drive/1r7MYQR_5yCJGpK_9I9-A10HmpupZuIN-?usp=sharing>`_ `[Video] <https://www.youtube.com/watch?v=CxESe1gYWU4&list=PLR3CNIF8DDHJUl8RLhyOVpX_kT4bxulEV&index=4>`_
11+
`Tutorial 2: Introduction to pyhealth.tasks <https://colab.research.google.com/drive/1kKkkBVS_GclHoYTbnOtjyYnSee79hsyT?usp=sharing>`_ `[Video (PyHealth 1.6)] <https://www.youtube.com/watch?v=CxESe1gYWU4&list=PLR3CNIF8DDHJUl8RLhyOVpX_kT4bxulEV&index=4>`_
1212

1313
`Tutorial 3: Introduction to pyhealth.models <https://colab.research.google.com/drive/1LcXZlu7ZUuqepf269X3FhXuhHeRvaJX5?usp=sharing>`_ `[Video] <https://www.youtube.com/watch?v=fRc0ncbTgZA&list=PLR3CNIF8DDHJUl8RLhyOVpX_kT4bxulEV&index=6>`_
1414

0 commit comments

Comments
 (0)