Skip to content

Commit

Permalink
Documentation and publishing updates (#52)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
jenniferjiangkells authored Sep 5, 2024
1 parent 3d661a3 commit 7a2e2ce
Show file tree
Hide file tree
Showing 31 changed files with 1,453 additions and 680 deletions.
15 changes: 5 additions & 10 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -50,6 +48,3 @@ jobs:
path: dist/
- name: Publish distribution 📦 to PyPI
uses: pypa/gh-action-pypi-publish@release/v1



2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -160,3 +160,5 @@ cython_debug/
#.idea/

output/
.DS_Store
.vscode/
1 change: 1 addition & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
27 changes: 23 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down
69 changes: 63 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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):
Expand All @@ -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

Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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
Expand Down
3 changes: 3 additions & 0 deletions docs/api/cda_parser.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# CDA Parser

::: healthchain.cda_parser.cdaannotator
10 changes: 10 additions & 0 deletions docs/api/cds_hooks.md
Original file line number Diff line number Diff line change
@@ -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
3 changes: 3 additions & 0 deletions docs/api/clients.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Clients

::: healthchain.clients.ehrclient
4 changes: 4 additions & 0 deletions docs/api/data_generators.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Data Generators

::: healthchain.data_generators.cdsdatagenerator
::: healthchain.data_generators.encountergenerators
5 changes: 5 additions & 0 deletions docs/api/data_models.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Data Models

::: healthchain.models.data.ccddata
::: healthchain.models.data.cdsfhirdata
::: healthchain.models.data.concept
3 changes: 3 additions & 0 deletions docs/api/service.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Service

::: healthchain.service.service
9 changes: 9 additions & 0 deletions docs/api/use_cases.md
Original file line number Diff line number Diff line change
@@ -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
Binary file removed docs/assets/healthchain_logo.png
Binary file not shown.
Binary file added docs/assets/images/healthchain_logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
File renamed without changes
2 changes: 1 addition & 1 deletion docs/license-page.md → docs/distribution.md
Original file line number Diff line number Diff line change
@@ -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:

Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down
4 changes: 2 additions & 2 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions docs/stylesheets/extra.css
Original file line number Diff line number Diff line change
Expand Up @@ -69,9 +69,9 @@
margin-bottom: 2rem;
}

.language-python {
/* .language-python {
background: #FFFFFF ! important
}
} */

.language-bash {
background: #FFFFFF ! important
Expand Down
Loading

0 comments on commit 7a2e2ce

Please sign in to comment.