Documentation and publishing updates (#52)

* Use poetry for build distribution and version bumping

* Update dependencies and meta data

* Added API reference and example usage

* Fixed Discord link and added logo

* Use github action to install poetry

* Update assets location and update use case documentation

* Update README and logo

* Export data classes in init

* rename docs license page

* Rename doc license further

* Use permalink for logo

Author: jenniferjiangkells

.github/workflows/publish.yml

@@ -16,14 +16,12 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: "3.x"
-    - name: Install pypa/build
-      run: >-
-        python3 -m
-        pip install
-        build
-        --user
+    - name: Install Poetry
+      uses: snok/install-poetry@v1
+    - name: Bump version
+      run: poetry version $(git describe --tags --abbrev=0)
     - name: Build a binary wheel and a source tarball
-      run: python3 -m build
+      run: poetry build
     - name: Store the distribution packages
       uses: actions/upload-artifact@v3
       with:
@@ -50,6 +48,3 @@ jobs:
         path: dist/
     - name: Publish distribution 📦 to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
-      
-
-

.gitignore

@@ -160,3 +160,5 @@ cython_debug/
 #.idea/
 
 output/
+.DS_Store
+.vscode/

.pre-commit-config.yaml

@@ -7,6 +7,7 @@ repos:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
     -   id: check-yaml
+        exclude: ^mkdocs.yml$
     -   id: check-added-large-files
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.

CONTRIBUTING.md

@@ -1,6 +1,4 @@
 # Contributing
-> If you're reading this, you're early! We're still finalising our guidelines as this is an early release so please [drop us a message](https://discord.gg/jG4UWCUh) instead!
->
 
 First of all, thank you for being interested in contributing to HealthChain, we welcome contributions of all kinds! Listed below are some of the ways you can get involved.
 
@@ -28,17 +26,19 @@ If you're a developer, there are many ways you can contribute code:
 
 ## Join Our Discord
 
-Are you a domain expert with valuable insights? We encourage you to join our [Discord community](https://discord.gg/jG4UWCUh) and share your wisdom. Your expertise can help shape the future of the project and guide us in making informed decisions.
+Are you a domain expert with valuable insights? We encourage you to join our [Discord community](https://discord.gg/4v6XgGBZ) and share your wisdom. Your expertise can help shape the future of the project and guide us in making informed decisions.
 
 We believe that every contribution, big or small, makes a difference. Thank you for being a part of our community!
 
 ## How to Contribute Code
 
+This project uses `poetry` for dependency management. For more information see the [poetry documentation](https://python-poetry.org/docs/).
+
 1. Fork the repository to your own GitHub account. For more details check out [github documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).
 
 2. Clone the forked repository to your local machine.
 
-3. Run `poetry install` to install all the necessary dependencies.
+3. Run `poetry install --with dev` to install all the necessary development dependencies.
 
 4. Try running `poetry run pytest` to check that all is working as expected.
 
@@ -68,6 +68,25 @@ We believe that every contribution, big or small, makes a difference. Thank you
 
 9. Open a pull request on the original repository.
 
+### Contributing to Documentation
+
+We use `Mkdocs` for our documentation site. To download the dependencies for documentation, run:
+```shell
+poetry install --with docs
+```
+
+To preview the docs page in development:
+```shell
+poetry run mkdocs serve
+```
+#### Writing Clear Documentation
+
+- **Be Concise**: Use clear and concise language to explain concepts and instructions.
+- **Use Headings**: Organize content with headings and subheadings to improve readability.
+- **Code Examples**: Include code examples to illustrate usage and functionality.
+- **Consistent Style**: Follow a consistent style and format throughout the documentation.
+- **Active Voice**: Write in the active voice to make instructions direct and easy to follow.
+- **Bullet Points**: Use bullet points or numbered lists for steps and key points.
 
 ## Testing
 

README.md

@@ -1,14 +1,23 @@
+<div align="center" style="margin-bottom: 1em;">
+
+# HealthChain 💫 🏥
+
+<img src="https://raw.githubusercontent.com/dotimplement/HealthChain/main/docs/assets/images/healthchain_logo.png" alt="HealthChain Logo" width=300></img>
+
 ![GitHub License](https://img.shields.io/github/license/dotimplement/HealthChain)
+![PyPI Version](https://img.shields.io/pypi/v/healthchain) ![Python Versions](https://img.shields.io/pypi/pyversions/healthchain)
+![Downloads](https://img.shields.io/pypi/dm/healthchain)
 
-# HealthChain
+</div>
 
-Simplify prototyping and testing AI/NLP applications in a healthcare context 💫 🏥.
+Simplify testing and evaluating AI and NLP applications in a healthcare context 💫 🏥.
 
 Building applications that integrate in healthcare systems is complex, and so is designing reliable, reactive algorithms involving unstructured data. Let's try to change that.
 
 ```bash
 pip install healthchain
 ```
+First time here? Check out our [Docs](dotimplement.github.io/HealthChain/) page!
 
 ## Features
 - [x] 🍱 Create sandbox servers and clients that comply with real EHRs API and data standards.
@@ -39,8 +48,11 @@ pip install healthchain
 import healthchain as hc
 
 from healthchain.use_cases import ClinicalDecisionSupport
+from healthchain.models import Card, CdsFhirData, CDSRequest
 from healthchain.data_generator import DataGenerator
 
+from typing import List
+
 # Decorate class with sandbox and pass in use case
 @hc.sandbox
 class myCDS(ClinicalDecisionSupport):
@@ -49,13 +61,13 @@ class myCDS(ClinicalDecisionSupport):
 
     # Sets up an instance of a mock EHR client of the specified workflow
     @hc.ehr(workflow="patient-view")
-    def ehr_database_client(self):
+    def ehr_database_client(self) -> CdsFhirData:
         self.data_generator.generate()
         return self.data_generator.data
 
     # Define your application logic here
     @hc.api
-    def llm_server(self, request: str):
+    def my_service(self, request: CdsRequest) -> List[Card]:
         result = "Hello " + request["patient_name"]
         return result
 
@@ -70,6 +82,51 @@ healthchain run mycds.py
 ```
 This will populate your EHR client with the data generation method you have defined, send requests to your server for processing, and save the data in `./output` by default.
 
+## Clinical Documentation
+
+The ClinicalDocumentation use case implements a real-time Clinical Documentation Improvement (CDI) service. It helps convert free-text medical documentation into coded information that can be used for billing, quality reporting, and clinical decision support.
+
+**When is this used?** Triggered when a clinician opts in to a CDI functionality (e.g. Epic NoteReader) and signs or pends a note after writing it.
+
+**What information is sent**: A [CDA (Clinical Document Architecture)](https://www.hl7.org/implement/standards/product_brief.cfm?product_id=7) document which contains continuity of care data and free-text data, e.g. a patient's problem list and the progress note that the clinician has entered in the EHR.
+
+**What information is returned**: A CDA document which contains additional structured data extracted and returned by your CDI service.
+
+```python
+import healthchain as hc
+
+from healthchain.use_cases import ClinicalDocumentation
+from healthchain.models import CcdData, ProblemConcept, Quantity,
+
+@hc.sandbox
+class NotereaderSandbox(ClinicalDocumentation):
+    def __init__(self):
+        self.cda_path = "./resources/uclh_cda.xml"
+
+    # Load an existing CDA file
+    @hc.ehr(workflow="sign-note-inpatient")
+    def load_data_in_client(self) -> CcdData:
+        with open(self.cda_path, "r") as file:
+            xml_string = file.read()
+
+        return CcdData(cda_xml=xml_string)
+
+    # Define application logic
+    @hc.api
+    def my_service(self, ccd_data: CcdData) -> CcdData:
+        # Apply method from ccd_data.note and access existing entries from ccd.problems
+
+        new_problem = ProblemConcept(
+            code="38341003",
+            code_system="2.16.840.1.113883.6.96",
+            code_system_name="SNOMED CT",
+            display_name="Hypertension",
+            )
+        ccd_data.problems.append(new_problem)
+        return ccd_data
+```
+
+
 ### Streamlit dashboard
 Note this is currently not meant to be a frontend to the EHR client, so you will have to run it separately from the sandbox application.
 
@@ -79,7 +136,7 @@ streamlit streamlit-demo/app.py
 ```
 
 ## Road Map
-- [ ] 📝 Adding Clinical Documentation use case
+- [x] 📝 Adding Clinical Documentation use case
 - [ ] 🎛️ Version and test different EHR backend configurations
 - [ ] 🤖 Integrations with popular LLM and NLP libraries
 - [ ] ❓ Evaluation framework for pipelines and use cases
@@ -89,7 +146,7 @@ streamlit streamlit-demo/app.py
 
 ## Contribute
 We are always eager to hear feedback and suggestions, especially if you are a developer or researcher working with healthcare systems!
-- 💡 Let's chat! [Discord](https://discord.gg/jG4UWCUh)
+- 💡 Let's chat! [Discord](https://discord.gg/4v6XgGBZ)
 - 🛠️ [Contribution Guidelines](CONTRIBUTING.md)
 
 ## Acknowledgement

docs/api/cda_parser.md

@@ -0,0 +1,3 @@
+# CDA Parser
+
+::: healthchain.cda_parser.cdaannotator

docs/api/cds_hooks.md

@@ -0,0 +1,10 @@
+# CDS Hooks
+
+::: healthchain.models.hooks.encounterdischarge
+::: healthchain.models.hooks.orderselect
+::: healthchain.models.hooks.ordersign
+::: healthchain.models.hooks.patientview
+::: healthchain.models.hooks.sign-note-inpatient
+::: healthchain.models.hooks.sign-note-outpatient
+::: healthchain.models.responses.cdsdiscovery
+::: healthchain.models.responses.cdsfeedback

docs/api/clients.md

@@ -0,0 +1,3 @@
+# Clients
+
+::: healthchain.clients.ehrclient

docs/api/data_generators.md

@@ -0,0 +1,4 @@
+# Data Generators
+
+::: healthchain.data_generators.cdsdatagenerator
+::: healthchain.data_generators.encountergenerators

docs/api/data_models.md

@@ -0,0 +1,5 @@
+# Data Models
+
+::: healthchain.models.data.ccddata
+::: healthchain.models.data.cdsfhirdata
+::: healthchain.models.data.concept

docs/api/service.md

@@ -0,0 +1,3 @@
+# Service
+
+::: healthchain.service.service

docs/api/use_cases.md

@@ -0,0 +1,9 @@
+# Use Cases
+
+::: healthchain.use_cases.cds
+::: healthchain.models.requests.cdsrequest
+::: healthchain.models.responses.cdsresponse
+
+::: healthchain.use_cases.clindoc
+::: healthchain.models.requests.cdarequest
+::: healthchain.models.responses.cdaresponse

docs/assets/healthchain_logo.png

@@ -1,4 +1,4 @@
-# Licence
+# Licence and citations
 
 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:
 

docs/assets/images/healthchain_logo.png

@@ -2,7 +2,7 @@
 
 HealthChain💫🏥 is an open-source Python package that provides a framework for testing and validating AI/NLP applications in a healthcare context.
 
-[ :fontawesome-brands-discord: Join our Discord](https://discord.gg/jG4UWCUh){ .md-button .md-button--primary }
+[ :fontawesome-brands-discord: Join our Discord](https://discord.gg/4v6XgGBZ){ .md-button .md-button--primary }
 
 <div class="grid cards" markdown>
 

docs/assets/synthetic_data_ons.png renamed to docs/assets/images/synthetic_data_ons.png

@@ -77,11 +77,11 @@ The aim of the data generator is not to generate realistic data suitable for use
 For this reason the data generator is opiniated by use case and workflow. See [Use Cases](usecases.md) for more information.
 
 !!! note
-    We're aware we may not cover everyone's use cases, so if you have strong opinions about this, please [reach out](https://discord.gg/jG4UWCUh)!
+    We're aware we may not cover everyone's use cases, so if you have strong opinions about this, please [reach out](https://discord.gg/4v6XgGBZ)!
 
 On the synthetic data spectrum defined by [this UK ONS methodology working paper](https://www.ons.gov.uk/methodology/methodologicalpublications/generalmethodology/onsworkingpaperseries/onsmethodologyworkingpaperseriesnumber16syntheticdatapilot#:~:text=Synthetic%20data%20at%20ONS&text=Synthetic%20data%20is%20created%20by,that%20provided%20the%20original%20data.%E2%80%9D), HealthChain generates level 1: synthetic structural data.
 
-![Synthetic data](assets/synthetic_data_ons.png)
+![Synthetic data](assets/images/synthetic_data_ons.png)
 
 You can use the data generator within a client function or on its own. The `.generate()` is dependent on workflow. For CDS use cases, it will return a `CdsFhirData` model with the `prefetch` field populated with a [Bundle](https://www.hl7.org/fhir/bundle.html) of generated structural synthetic FHIR data.
 

docs/license-page.md renamed to docs/distribution.md

@@ -69,9 +69,9 @@
     margin-bottom: 2rem;
   }
 
-  .language-python {
+  /* .language-python {
     background: #FFFFFF ! important
-  }
+  } */
 
   .language-bash {
     background: #FFFFFF ! important