Add a MIMIC-III code-set mode to GAN, with tests and an example notebook

docs/api/models/pyhealth.models.GAN.rst

@@ -1,7 +1,27 @@
 pyhealth.models.GAN
 ===================================
 
-The GAN model (pyhealth trainer does not apply to GAN, refer to the example/ChestXray-image-generation-GAN.ipynb for examples of using GAN model).
+A Generative Adversarial Network built from a dataset with a single input
+feature, whose processor picks the mode. With a ``multi_hot`` feature (for
+example from :class:`~pyhealth.tasks.EHRCodeSetGenerationMIMIC3`), the GAN
+learns to generate synthetic patients as sets of codes with MLP networks. With
+a ``tensor`` feature of continuous values (for example from
+:class:`~pyhealth.tasks.CARTVitalsGenerationEICU`), it generates new vectors in
+the data's original units. With an ``image`` feature whose ``image_size`` is 32, 64 or 128 (for example from
+:class:`~pyhealth.tasks.COVID19CXRClassification`), it generates small images
+with CNN networks. ``examples/gan_tutorial.ipynb`` walks through both.
+
+The PyHealth ``Trainer`` does not apply to GAN: train it with
+:meth:`~pyhealth.models.GAN.train_model`, then call
+:meth:`~pyhealth.models.GAN.generate`, which returns synthetic patients in
+code-set mode and a tensor in continuous and image mode.
+
+Reference:
+    Goodfellow, I., Pouget-Abadie, J., Mirza, M., Xu, B., Warde-Farley, D.,
+    Ozair, S., Courville, A., & Bengio, Y. (2014).
+    *Generative Adversarial Nets.*
+    In Advances in Neural Information Processing Systems (NeurIPS) 2014.
+    https://arxiv.org/abs/1406.2661
 
 .. autoclass:: pyhealth.models.GAN
     :members:

docs/api/tasks.rst

@@ -217,6 +217,7 @@ Available Tasks
     DKA Prediction (MIMIC-IV) <tasks/pyhealth.tasks.dka>
     Drug Recommendation <tasks/pyhealth.tasks.drug_recommendation>
     EHR Generation <tasks/pyhealth.tasks.generate_ehr>
+    Vital-Sign Generation (eICU) <tasks/pyhealth.tasks.vitals_generation_eicu>
     Length of Stay Prediction <tasks/pyhealth.tasks.length_of_stay_prediction>
     Length of Stay Prediction (StageNet MIMIC-IV) <tasks/pyhealth.tasks.length_of_stay_stagenet_mimic4>
     Medical Transcriptions Classification <tasks/pyhealth.tasks.MedicalTranscriptionsClassification>

docs/api/tasks/pyhealth.tasks.vitals_generation_eicu.rst

@@ -0,0 +1,27 @@
+pyhealth.tasks.vitals_generation_eicu
+===========================================
+
+A task that turns eICU into static vital-sign vectors for generating new
+patients: each patient's first ICU stay becomes ``[age, heart rate,
+respiration rate, diastolic BP, mean BP]``, with each vital averaged over the
+stay's first 24 hours. The values are continuous, so the task pairs with
+:class:`~pyhealth.models.GAN`'s continuous mode; see
+``examples/gan_tutorial.ipynb``.
+
+The task reads the ``vitalperiodic`` and ``vitalaperiodic`` tables:
+
+.. code-block:: python
+
+    from pyhealth.datasets import eICUDataset
+    from pyhealth.tasks import CARTVitalsGenerationEICU
+
+    dataset = eICUDataset(
+        root="https://physionet.org/files/eicu-crd-demo/2.0.1",
+        tables=["vitalperiodic", "vitalaperiodic"],
+    )
+    samples = dataset.set_task(CARTVitalsGenerationEICU())
+
+.. autoclass:: pyhealth.tasks.vitals_generation_eicu.CARTVitalsGenerationEICU
+    :members:
+    :undoc-members:
+    :show-inheritance: