update docs

dotimplement · May 23, 2024 · 21f0acb · 21f0acb
1 parent 57b2f62
commit 21f0acb
Show file tree

Hide file tree

Showing 10 changed files with 264 additions and 21 deletions.
diff --git a/docs/community/index.md b/docs/community/index.md
@@ -0,0 +1,4 @@
+# Community
+
+## Contribute
+
diff --git a/docs/index.md b/docs/index.md
@@ -1,3 +1,42 @@
-# HealthChain
+# HealthChain 💫 🏥
 
-Simplify prototyping and testing AI/NLP applications in a healthcare context 💫 🏥.
+Simplify prototyping and testing AI/NLP applications in a healthcare context.
+
+[ :fontawesome-brands-discord: Join our Discord](https://discord.gg/jG4UWCUh){ .md-button .md-button--primary }
+
+<div class="grid cards" markdown>
+
+-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
+
+    ---
+
+    Install `healthchain` with `pip` and get up
+    and running in minutes
+
+    [:octicons-arrow-right-24: Installation](installation.md)
+
+-   :fontawesome-regular-hospital:{ .lg .middle } __Define a sandbox__
+
+    ---
+
+    Test LLMs in a full health-context aware pipeline from day 1
+
+    [:octicons-arrow-right-24: Quickstart](quickstart.md)
+
+-   :material-lightbulb-on-outline:{ .lg .middle } __Contribute__
+
+    ---
+
+    If you have an idea or suggestions, we'd love to hear from you!
+
+    [:octicons-arrow-right-24: Community](community/index.md)
+
+-   :material-scale-balance:{ .lg .middle } __Open Source, Apache 2.0__
+
+    ---
+
+    HealtchChain is licensed under Apache 2.0 and available on [GitHub](https://github.com/dotimplement/HealthChain)
+
+    [:octicons-arrow-right-24: Licence](license-page.md)
+
+</div>
diff --git a/docs/installation.md b/docs/installation.md
@@ -12,4 +12,5 @@ Note you need to download any libraries that you require separetly:
 pip install langchain
 pip install transformers
 pip install torch
+...
 ```
diff --git a/docs/license-page.md b/docs/license-page.md
@@ -0,0 +1,19 @@
+# Licence
+
+HealthChain is licensed under Apache 2.0. To comply with the licence you need to add the following notice at the top every file that uses part of HealthChain code:
+
+```
+Copyright 2024 - dotimplement
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```
diff --git a/docs/license.md b/docs/license.md
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -5,7 +5,7 @@
 ### Sandbox
 a sandbox is a standard-compliant client-to-service full pipeline environment. For a given sandbox run:
 
-1.  Data is generated or loaded into a client (EHR)
+1. Data is generated or loaded into a client (EHR)
 
 2. Data is wrapped and sent as standard-compliant API requests the designated service
 
@@ -121,7 +121,7 @@ This matters when you develop applications that need to integrate into these sys
 
 The aim of the data generator in HealthChain is not to generate realistic data suitable for use cases such as patient population studies, but rather to generate data that is structurally compliant with what is expected of EHR configurations, and to be able to test and handle variations in this.
 
-For this reason the data generator is opiniated by use case and workflow. See [Use Cases](#use-cases).
+For this reason the data generator is opiniated by use case and workflow. See [Use Cases](usecases.md).
 
 !!! note
     We're aware we may not cover everyone's use cases, so if you have strong opinions about this, please [reach out]()!
@@ -185,6 +185,44 @@ data_generator.load_free_text("./dir/to/txt/files")
 If you are looking for more realistic patient population data, you are also free to define your own data in a sandbox run! Check out [MIMIC](https://mimic.mit.edu/) for comprehensive records and free-text data, or [Synthea](https://synthetichealth.github.io/synthea/) for synthetically generated FHIR resources. Both are open-source, although you will need to complete [PhysioNet Credentialing](https://mimic.mit.edu/docs/gettingstarted/) to access MIMIC.
 
 
+## Full Example
+
+```python
+import healthchain as hc
+
+from healthchain.use_cases import ClinicalDecisionSupport
+from healthchain.data_generator import DataGenerator
+
+@sandbox
+class MyCoolSandbox(ClinicalDecisionSupport):
+    def __init__(self):
+        self.data_generator = DataGenerator()
+
+    @hc.ehr(workflow="encounter-discharge", num=10)
+    def load_data_in_client(self):
+        self.data_generator.generate()
+        return self.data_generator.data
+
+    @hc.api
+    def llm_server(self, text: str):
+        return {
+            "cards": [
+                {
+                    "summary": "This will be generated by your model",
+                    "indicator": "info",
+                    "source": {"label": "resource"},
+                }
+            ]
+        }
+
+
+if __name__ == "__main__":
+    cds = MyCoolSandbox()
+    cds.start_sandbox()
+
+```
+
+
 ## Deploy sandbox locally with FastAPI 🚀
 
 To run your sandbox:
@@ -196,6 +234,10 @@ healthchain my_sandbox.py
 
 ## Inspect generated data in Streamlit 🎈
 
+By default, data generated from your sandbox runs is saved at `./output/`. The streamlit dashboard is run separately and will assume this is where your data is saved. 
+
+To run the streamlit app:
+
 ```bash
 streamlit streamlit_app/app.py
 ```
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -14,6 +14,69 @@
     --md-default-fg-color--lightest: #ECEFF4;
   }
 
+  .index-pre-code {
+    max-width: 700px;
+    left: 50%;
+  }
+
+  .index-pre-code pre>code {
+    text-align: left;
+  }
+
+  .md-typeset pre>code {
+    border-radius: .2rem;
+    box-shadow: 10px 5px 5px #D8DEE9;
+  }
+
+  .md-typeset p > code {
+    background: #ECEFF4;
+    color: #000000;
+    font-weight: 500;
+  }
+
+  .md-typeset strong > code {
+    background: #ECEFF4;
+    color: #000000;
+    font-weight: 500;
+  }
+
+  .md-content p > code {
+    background: #ECEFF4;
+    color: #000000;
+    font-weight: 500;
+  }
+
+  .md-typeset td > code {
+    background: #ECEFF4;
+    color: #000000;
+    font-weight: 500;
+  }
+
+  .md-typeset li > code {
+    background: #ECEFF4;
+    color: #000000;
+    font-weight: 500;
+  }
+
+  .md-typeset code {
+    font-weight: 500;
+  }
+
+  .md-typeset pre {
+    margin-left: .5rem;
+    margin-right: .5rem;
+    margin-top: 2rem;
+    margin-bottom: 2rem;
+  }
+
+  .language-python {
+    background: #FFFFFF ! important
+  }
+
+  .language-bash {
+    background: #FFFFFF ! important
+  }
+
   h1.title {
     color: #FFFFFF;
     margin: 0px 0px 5px;
@@ -42,3 +105,11 @@
     font-weight: bold;
     color: #000000;
   }
+
+  .md-nav__link--active {
+    background-color: #ECEFF4;
+  }
+
+  code {
+    white-space : pre-wrap !important;
+  }
diff --git a/docs/usage.md b/docs/usage.md
diff --git a/docs/usecases.md b/docs/usecases.md
@@ -0,0 +1,75 @@
+# Use Cases
+
+## Clinical Decision Support (CDS)
+
+[CDS Hooks](https://cds-hooks.org/) is an [HL7](https://cds-hooks.hl7.org) published specification for clinical decision support. For more information please consult the [official documentation](https://cds-hooks.org/).
+
+| When      | Where | What you receive            | What you send back         |
+| :-------- | :-----| :-------------------------- |----------------------------|
+| Triggered at certain events during a clinician's workflow, e.g. when a patient record is opened. | EHR  | The context of the event and FHIR resources that are requested by your service. e.g. patient ID, `Encounter` and `Patient`.  | “Cards” displaying text, actionable suggestions, or links to launch a [SMART](https://smarthealthit.org/) app from within the workflow.      |
+
+
+Each workflow has associated `context` and `prefetch` FHIR resource returned from it. 
+
+If you use the `DataGenerator`, a pre-configured list of FHIR resources is randomly generated and placed in the `prefetch` field of a `CDSRequest`.
+
+Current implemented workflows:
+
+| Workflow      | Implementation Completeness        | Generated Synthetic Resources |
+| ----------- | ------------------------------------ | -----------------------------
+| [patient-view](https://cds-hooks.org/hooks/patient-view/) | :material-check-all:  | `Patient`, `Encounter` (Future: `MedicationStatement`, `AllergyIntolerance`)|
+| [encounter-discharge](https://cds-hooks.org/hooks/encounter-discharge/)| :material-check-all: | `Patient`, `Encounter`, `Procedure`, `MedicationRequest`, Optional `DocumentReference` |
+| [order-sign](https://cds-hooks.org/hooks/order-sign/)| :material-check: Partial | Future: `MedicationRequest`, `ProcedureRequest`, `ServiceRequest` |
+| [order-select](https://cds-hooks.org/hooks/order-select/) | :material-check: Partial | Future: `MedicationRequest`, `ProcedureRequest`, `ServiceRequest` |
+
+
+### Example `CDSRequest`
+
+```json
+{
+   "hookInstance" : "23f1a303-991f-4118-86c5-11d99a39222e",
+   "fhirServer" : "https://fhir.example.org",
+   "hook" : "patient-view",
+   "context" : {
+     "patientId" : "1288992",
+     "userId" : "Practitioner/example"
+    },
+   "prefetch" : {
+      "patientToGreet" : {
+        "resourceType" : "Patient",
+        "gender" : "male",
+        "birthDate" : "1925-12-23",
+        "id" : "1288992",
+        "active" : true
+      }
+   }
+}
+```
+### Example `CDSResponse`
+
+```json
+{
+  "summary": "Bilirubin: Based on the age of this patient consider overlaying bilirubin [Mass/volume] results over a time-based risk chart",
+  "indicator": "info",
+  "detail": "The focus of this app is to reduce the incidence of severe hyperbilirubinemia and bilirubin encephalopathy while minimizing the risks of unintended harm such as maternal anxiety, decreased breastfeeding, and unnecessary costs or treatment.",
+  "source": {
+    "label": "Intermountain",
+    "url": null
+  },
+  "links": [
+    {
+      "label": "Bilirubin SMART app",
+      "url": "https://example.com/launch",
+      "type": "smart"
+   }
+  ]
+}
+
+```
+
+### FHIR Resources
+
+- `Patient`
+- `Encounter`
+- `Procedure`
+- `MedicationRequest`
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -11,17 +11,17 @@ nav:
   - Getting Started:
       - Installation: installation.md
       - Quickstart: quickstart.md
-      - Usage: usage.md
-      - License: license.md
+      - Use Cases: usecases.md
+      - Licence: license-page.md
   - Cookbook:
       - cookbook/index.md
   - Docs:
       - reference/index.md
   - API Reference:
       - api/index.md
-# plugins:
-#   - mkdocstrings
-#   - search
+  - Community:
+      - community/index.md
+
 copyright: dotimplement
 theme:
   name: material
@@ -45,6 +45,7 @@ theme:
 # Extensions
 markdown_extensions:
   - admonition
+  - tables
   - def_list
   - attr_list
   - md_in_html
@@ -59,9 +60,9 @@ markdown_extensions:
   - pymdownx.superfences
   - pymdownx.tabbed:
       alternate_style: true
-  # - pymdownx.emoji:
-  #     emoji_index: !!python/name:material.extensions.emoji.twemoji
-  #     emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
 
 extra_css:
   - stylesheets/extra.css