Merge branch 'master' of https://github.com/sunlabuiuc/PyHealth into pyhealth2bounty/adacare

Author: Razin93937

docs/api/calib.rst

@@ -23,6 +23,23 @@ confidence levels:
 - :class:`~pyhealth.calib.predictionset.FavMac`: Value-maximizing sets with cost control
 - :class:`~pyhealth.calib.predictionset.CovariateLabel`: Covariate shift adaptive conformal
 
+Getting Started
+---------------
+
+New to calibration and uncertainty quantification? Check out this complete example:
+
+**Browse all examples online**: https://github.com/sunlabuiuc/PyHealth/tree/master/examples
+
+- **Example**: ``examples/covid19cxr_conformal.py`` - Comprehensive conformal prediction workflow demonstrating:
+
+  - Training a ResNet-18 model on COVID-19 chest X-ray classification
+  - Applying conventional conformal prediction with **LABEL**
+  - Using covariate shift adaptive conformal prediction with **CovariateLabel**
+  - Comparing coverage guarantees and efficiency between methods
+  - Understanding when to use each method based on distribution shift
+
+This example shows the complete pipeline from model training to uncertainty-aware predictions with formal coverage guarantees.
+
 Quick Links
 -----------
 

docs/api/data.rst

@@ -3,6 +3,23 @@ Data
 
 **pyhealth.data** defines the atomic data structures of this package.
 
+Getting Started
+---------------
+
+New to PyHealth's data structures? Start here:
+
+- **Tutorial**: `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>`_
+
+This tutorial introduces the core data structures in PyHealth:
+
+- **Event**: Represents individual clinical events (diagnoses, procedures, medications, lab results, etc.)
+- **Patient**: Contains all events and visits for a single patient, forming the foundation of healthcare data organization
+
+Understanding these structures is essential for working with PyHealth, as they provide the standardized format for representing electronic health records.
+
+API Reference
+-------------
+
 .. toctree::
     :maxdepth: 3
 

docs/api/datasets.rst

@@ -1,6 +1,30 @@
 Datasets
 ===============
 
+Getting Started
+---------------
+
+New to PyHealth datasets? Start here:
+
+- **Tutorial**: `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>`_
+
+This tutorial covers:
+
+- How to load and work with different healthcare datasets (MIMIC-III, MIMIC-IV, eICU, etc.)
+- Understanding the ``BaseDataset`` structure and patient representation
+- Parsing raw EHR data into standardized PyHealth format
+- Accessing patient records, visits, and clinical events
+- Dataset splitting for train/validation/test sets
+
+**Data Access**: If you're new and need help accessing MIMIC datasets, check the :doc:`../how_to_contribute` guide's "Data Access for Testing" section for information on:
+
+- Getting MIMIC credentialing through PhysioNet
+- Using openly available demo datasets (MIMIC-III Demo, MIMIC-IV Demo)
+- Working with synthetic data for testing
+
+Available Datasets
+------------------
+
 .. toctree::
     :maxdepth: 3
 
@@ -23,4 +47,4 @@ Datasets
     datasets/pyhealth.datasets.TUEVDataset
     datasets/pyhealth.datasets.splitter
     datasets/pyhealth.datasets.utils
-
+    datasets/pyhealth.datasets.ChestXray14Dataset

docs/api/datasets/pyhealth.datasets.ChestXray14Dataset.rst

@@ -0,0 +1,9 @@
+pyhealth.datasets.ChestXray14Dataset
+===================================
+
+The NIH ChestX-ray14 dataset. For more information see `here <https://nihcc.app.box.com/v/ChestXray-NIHCC/folder/36938765345>`_. Note that the copy of this dataset on `Kaggle <https://www.kaggle.com/datasets/nih-chest-xrays/data>`_ is stale, as corrections have been made to the metadata (see `here <https://nihcc.app.box.com/v/ChestXray-NIHCC/file/249505703122>`_).
+
+.. autoclass:: pyhealth.datasets.ChestXray14Dataset
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/interpret.rst

@@ -1,12 +1,46 @@
 Interpretability
 ===============
 
-We implement the following interpretability techniques below:
+We implement the following interpretability techniques to help you understand model predictions and identify important features in healthcare data.
 
-Help always needed in this direction.
+
+Getting Started
+---------------
+
+New to interpretability in PyHealth? Check out these complete examples:
+
+**Browse all examples online**: https://github.com/sunlabuiuc/PyHealth/tree/master/examples
+
+**DeepLift Example:**
+
+- ``examples/deeplift_stagenet_mimic4.py`` - Demonstrates DeepLift attributions on StageNet for mortality prediction with MIMIC-IV data. Shows how to:
+
+  - Compute feature attributions for discrete (ICD codes) and continuous (lab values) features
+  - Decode attributions back to human-readable medical codes and descriptions
+  - Visualize top positive and negative attributions
+
+**Integrated Gradients Examples:**
+
+- ``examples/integrated_gradients_mortality_mimic4_stagenet.py`` - Complete workflow showing:
+
+  - How to load pre-trained models and compute attributions
+  - Comparing attributions for different target classes (mortality vs. survival)
+  - Interpreting results with medical context (lab categories, diagnosis codes)
+
+- ``examples/interpretability_metrics.py`` - Demonstrates evaluation of attribution methods using:
+
+  - **Comprehensiveness**: Measures how much prediction drops when removing important features
+  - **Sufficiency**: Measures how much prediction is retained when keeping only important features
+  - Both functional API (``evaluate_attribution``) and class-based API (``Evaluator``)
+
+These examples provide end-to-end workflows from loading data to interpreting and evaluating attributions.
+
+Available Methods
+-----------------
 
 .. toctree::
     :maxdepth: 3
 
     interpret/pyhealth.interpret.methods.chefer
+    interpret/pyhealth.interpret.methods.deeplift
     interpret/pyhealth.interpret.methods.integrated_gradients

docs/api/tasks.rst

@@ -1,7 +1,7 @@
 Tasks
 ===============
 
-We support various real-world healthcare predictive tasks defined by **function calls**. The following example tasks are collected from top AI/Medical venues, such as: 
+We support various real-world healthcare predictive tasks defined by **function calls**. The following example tasks are collected from top AI/Medical venues, such as:
 
 (i) Drug Recommendation [Yang et al. IJCAI 2021a, Yang et al. IJCAI 2021b, Shang et al. AAAI 2020]
 
@@ -11,11 +11,68 @@ We support various real-world healthcare predictive tasks defined by **function
 
 (iv) Length of Stay Prediction
 
-(v) Sleep Staging [Yang et al. ArXiv 2021]
+(v) Sleep Staging [Yang et al. ArXix 2021]
+
+Getting Started
+---------------
+
+New to PyHealth tasks? Start here:
+
+- **Tutorial**: `Introduction to pyhealth.tasks <https://colab.research.google.com/drive/1kKkkBVS_GclHoYTbnOtjyYnSee79hsyT?usp=sharing>`_ - Learn the basics of defining and using tasks
+- **Code Examples**: Browse all examples online at https://github.com/sunlabuiuc/PyHealth/tree/master/examples
+- **Pipeline Examples**: Check out our :doc:`../tutorials` page for complete end-to-end examples including:
+  
+  - Mortality Prediction Pipeline
+  - Readmission Prediction Pipeline  
+  - Medical Coding Pipeline
+  - Chest X-ray Classification Pipeline
+
+These tutorials demonstrate how to load datasets, apply tasks, train models, and evaluate results.
+
+Understanding Tasks and Processors
+-----------------------------------
+
+Tasks define **what** data to extract (via ``input_schema`` and ``output_schema``), while **processors** define **how** to transform that data into tensors for model training.
+
+After you define a task:
+
+1. **Task execution**: The task function extracts relevant features from patient records and generates samples
+2. **Processor application**: Processors automatically transform these samples into model-ready tensors based on the schemas
+
+**Example workflow:**
+
+.. code-block:: python
+
+    # 1. Define a task with input/output schemas
+    task = MortalityPredictionMIMIC4()
+    # input_schema = {"conditions": "sequence", "procedures": "sequence"}
+    # output_schema = {"mortality": "binary"}
+    
+    # 2. Apply task to dataset
+    sample_dataset = base_dataset.set_task(task)
+    
+    # 3. Processors automatically transform samples:
+    #    - "sequence" -> SequenceProcessor (converts codes to indices)
+    #    - "binary" -> BinaryLabelProcessor (converts labels to tensors)
+    
+    # 4. Get model-ready tensors
+    sample = sample_dataset[0]
+    # sample["conditions"] is now a tensor of token indices
+    # sample["mortality"] is now a binary tensor [0] or [1]
+
+**Learn more about processors:**
+
+- See the :doc:`processors` documentation for details on all available processors
+- Learn about string keys (``"sequence"``, ``"binary"``, etc.) that map to specific processors
+- Discover how to customize processor behavior with kwargs tuples
+- Understand processor types for different data modalities (text, images, signals, etc.)
+
+Available Tasks
+---------------
 
 .. toctree::
     :maxdepth: 3
-    
+
     Base Task <tasks/pyhealth.tasks.BaseTask>
     Readmission (30 Days, MIMIC-IV) <tasks/pyhealth.tasks.Readmission30DaysMIMIC4>
     In-Hospital Mortality (MIMIC-IV) <tasks/pyhealth.tasks.InHospitalMortalityMIMIC4>
@@ -36,4 +93,5 @@ We support various real-world healthcare predictive tasks defined by **function
     Temple University EEG Tasks <tasks/pyhealth.tasks.temple_university_EEG_tasks>
     Sleep Staging v2 <tasks/pyhealth.tasks.sleep_staging_v2>
     Benchmark EHRShot <tasks/pyhealth.tasks.benchmark_ehrshot>
-
+    ChestX-ray14 Binary Classification <tasks/pyhealth.tasks.ChestXray14BinaryClassification>
+    ChestX-ray14 Multilabel Classification <tasks/pyhealth.tasks.ChestXray14MultilabelClassification>

docs/api/tasks/pyhealth.tasks.ChestXray14BinaryClassification.rst

@@ -0,0 +1,7 @@
+pyhealth.tasks.ChestXray14BinaryClassification
+=======================================
+
+.. autoclass:: pyhealth.tasks.ChestXray14BinaryClassification
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/tasks/pyhealth.tasks.ChestXray14MultilabelClassification.rst

@@ -0,0 +1,7 @@
+pyhealth.tasks.ChestXray14MultilabelClassification
+=======================================
+
+.. autoclass:: pyhealth.tasks.ChestXray14MultilabelClassification
+    :members:
+    :undoc-members:
+    :show-inheritance: