Skip to content
Snippets Groups Projects
Commit f29f45bc authored by mjbonifa's avatar mjbonifa
Browse files

Merge branch '54-docs-publish-to-readthedocs' into 'dev' 

Resolve "[docs] Publish to readthedocs"

Closes #54

See merge request meldb/concepts-processing!36
parents 9254ae24 88675c27
No related branches found
No related tags found
No related merge requests found
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 4172 additions and 4696 deletions
contributing.md
+ 32
− 2
View file @ f29f45bc
......@@ -101,14 +101,14 @@ hatch run black --check .
To format the coode and modify the files, use
```sh
hatch run black .
hatch run format
```
### Type Checking
The project uses `mypy` for type checking:
```sh
hatch run mypy .
hatch run type
```
## Building the Package
......@@ -141,6 +141,36 @@ Upload to pypi using:
twine upload dist/acmc-<version>-py3-none-any.whl --username __token__ --password <your pypi token>
```
## Updating docs
Docs are created using mkdocs and published at readthedocs.org. mkdocs is configured with `mkdocs.yaml` in the root repo directory. Mkdocs includes the navigation structure of the document linking to general docs and API docs.
Docs are published at readthedocs https://acmc.readthedocs.io/en/latest/. readthedocs is configured with `readthedocs.yml` in the root repo directory.
### General docs
General docs are written in markdown and stored within the `docs` directory, e.g. the user guide is `./docs/index.md`
### API docs
API documentation are automatically generated from docstrings using pdoc, through the following command
```bash
hatch run docs
```
### Publishing to readthedocs
1. Get an account a [readthedocs](https://app.readthedocs.org/dashboard)
2. Ask to become a maintainer of the acmc project
3. Select the acmc project from the dash board
4. Select builds and press the rebuild button
5. Check the documentation at https://acmc.readthedocs.io/en/latest/
## GitLab Workflows
### Basic
......
docs/api.md deleted 100644 → 0
+ 0
− 540
View file @ 9254ae24
<a id="__init__"></a>
# \_\_init\_\_
<a id="__main__"></a>
# \_\_main\_\_
<a id="util"></a>
# util
<a id="logging_config"></a>
# logging\_config
<a id="logging_config.setup_logger"></a>
#### setup\_logger
```python
def setup_logger(log_level: int = logging.INFO)
```
Sets up logger as a singleton outputing to file and sysout syserr
<a id="logging_config.set_log_level"></a>
#### set\_log\_level
```python
def set_log_level(log_level: int)
```
Sets the log level for the acmc logger
<a id="main"></a>
# main
<a id="main.trud_install"></a>
#### trud\_install
```python
def trud_install(args: argparse.Namespace)
```
Handle the `trud install` command.
<a id="main.omop_install"></a>
#### omop\_install
```python
def omop_install(args: argparse.Namespace)
```
Handle the `omop install` command.
<a id="main.omop_clear"></a>
#### omop\_clear
```python
def omop_clear(args: argparse.Namespace)
```
Handle the `omop clear` command.
<a id="main.omop_delete"></a>
#### omop\_delete
```python
def omop_delete(args: argparse.Namespace)
```
Handle the `omop delete` command.
<a id="main.phen_init"></a>
#### phen\_init
```python
def phen_init(args: argparse.Namespace)
```
Handle the `phen init` command.
<a id="main.phen_fork"></a>
#### phen\_fork
```python
def phen_fork(args: argparse.Namespace)
```
Handle the `phen fork` command.
<a id="main.phen_validate"></a>
#### phen\_validate
```python
def phen_validate(args: argparse.Namespace)
```
Handle the `phen validate` command.
<a id="main.phen_map"></a>
#### phen\_map
```python
def phen_map(args: argparse.Namespace)
```
Handle the `phen map` command.
<a id="main.phen_export"></a>
#### phen\_export
```python
def phen_export(args: argparse.Namespace)
```
Handle the `phen copy` command.
<a id="main.phen_publish"></a>
#### phen\_publish
```python
def phen_publish(args: argparse.Namespace)
```
Handle the `phen publish` command.
<a id="main.phen_copy"></a>
#### phen\_copy
```python
def phen_copy(args: argparse.Namespace)
```
Handle the `phen copy` command.
<a id="main.phen_diff"></a>
#### phen\_diff
```python
def phen_diff(args: argparse.Namespace)
```
Handle the `phen diff` command.
<a id="omop"></a>
# omop
OMOP Module
================
This module provides functionality to manage OMOP vocabularies.
<a id="omop.install"></a>
#### install
```python
def install(omop_zip_file: str, version: str)
```
Installs the OMOP release csv files in a file-based sql database
<a id="omop.write_version_file"></a>
#### write\_version\_file
```python
def write_version_file(version: str)
```
Writes the OMOP vocaburaries and version to a file
<a id="omop.clear"></a>
#### clear
```python
def clear(db_path: Path)
```
Clears the OMOP sql database
<a id="omop.delete"></a>
#### delete
```python
def delete(db_path: Path)
```
Deletes the OMOP sql database
<a id="parse"></a>
# parse
<a id="parse.CodesError"></a>
## CodesError Objects
```python
class CodesError()
```
A class used in InvalidCodesException to report an error if a code parser check fails
<a id="parse.InvalidCodesException"></a>
## InvalidCodesException Objects
```python
class InvalidCodesException(Exception)
```
Custom exception class raised when invalid codes are found that cannot be resolved by processing
<a id="parse.Proto"></a>
## Proto Objects
```python
class Proto()
```
Define checks as list of 3 tuple: (Message, Condition, Process)
- Message = The name of the condition (what is printed and logged)
- Condition = True if Passed, and False if Failed
- Process = Aims to resolve all issues that stop condition from passing (Do not change index!)
<a id="parse.Proto.raise_exception"></a>
#### raise\_exception
```python
def raise_exception(ex: Exception)
```
Raises an exception inside a lambda function. Python does not allow using raise statement inside lambda because lambda can only contain expressions, not statements. Using raise_exception not raise_ as it's more explict
<a id="parse.Proto.process"></a>
#### process
```python
def process(codes: pd.DataFrame,
codes_file: Path) -> Tuple[pd.DataFrame, list]
```
identify issues that do not pass and fix them with define/d process
<a id="parse.Proto.verify"></a>
#### verify
```python
def verify(codes: pd.DataFrame, codes_file: Path)
```
verify codes in codes file
<a id="parse.Read2"></a>
## Read2 Objects
```python
class Read2(Proto)
```
This Read2 class extends Proto, adding custom validation checks for a dataset of "Read2" codes. It ensures that the dataset is loaded, validates the codes based on several rules, and applies corrections or logs errors when necessary.
<a id="parse.CodeTypeParser"></a>
## CodeTypeParser Objects
```python
class CodeTypeParser()
```
A class used in InvalidCodesException to report an error if a code parser check fails
<a id="phen"></a>
# phen
Phenotype Module
================
This module provides functionality for managing phenotypes.
<a id="phen.PhenValidationException"></a>
## PhenValidationException Objects
```python
class PhenValidationException(Exception)
```
Custom exception class raised when validation errors in phenotype configuration file
<a id="phen.construct_git_url"></a>
#### construct\_git\_url
```python
def construct_git_url(remote_url: str)
```
Constructs a git url for github or gitlab including a PAT token environment variable
<a id="phen.create_empty_git_dir"></a>
#### create\_empty\_git\_dir
```python
def create_empty_git_dir(path: Path)
```
Creates a directory with a .gitkeep file so that it's tracked in git
<a id="phen.check_delete_dir"></a>
#### check\_delete\_dir
```python
def check_delete_dir(path: Path, msg: str) -> bool
```
Checks on the command line if a user wants to delete a directory
**Arguments**:
- `path` _Path_ - path of the directory to be deleted
- `msg` _str_ - message to be displayed to the user
**Returns**:
- `Boolean` - True if deleted
<a id="phen.fork"></a>
#### fork
```python
def fork(phen_dir: str, upstream_url: str, upstream_version: str,
new_origin_url: str)
```
Forks an upstream phenotype in a remote repo at a specific version to a local director, and optionally sets to a new remote origin"
**Arguments**:
- `phen_dir` _str_ - local directory path where the upstream repo is to be cloned
- `upstream_url` _str_ - url to the upstream repo
- `upstream_version` _str_ - version in the upstream repo to clone
- `new_origin_url` _str, optional_ - url of the remote repo to set as the new origin. Defaults to None.
**Raises**:
- `ValueError` - if the specified version is not in the upstream repo
- `ValueError` - if the upstream repo is not a valid phenotype repo
- `ValueError` - if there's any other problems with Git
<a id="phen.init"></a>
#### init
```python
def init(phen_dir: str, remote_url: str)
```
Initial phenotype directory as git repo with standard structure
<a id="phen.validate"></a>
#### validate
```python
def validate(phen_dir: str)
```
Validates the phenotype directory is a git repo with standard structure
<a id="phen.read_table_file"></a>
#### read\_table\_file
```python
def read_table_file(path: Path, excel_sheet: str = "")
```
Load Code List File
<a id="phen.preprocess_source_concepts"></a>
#### preprocess\_source\_concepts
```python
def preprocess_source_concepts(
df: pd.DataFrame, concept_set: dict,
code_file_path: Path) -> Tuple[pd.DataFrame, list]
```
Parses each column individually - Order and length will not be preserved!
<a id="phen.translate_codes"></a>
#### translate\_codes
```python
def translate_codes(source_df: pd.DataFrame, target_code_type: str,
concept_name: str) -> pd.DataFrame
```
Translates each source code type the source coding list into a target type and returns all conversions as a concept set
<a id="phen.publish"></a>
#### publish
```python
def publish(phen_dir: str,
msg: str,
remote_url: str,
increment: str = DEFAULT_VERSION_INC)
```
Publishes updates to the phenotype by commiting all changes to the repo directory
<a id="phen.export"></a>
#### export
```python
def export(phen_dir: str, version: str)
```
Exports a phen repo at a specific tagged version into a target directory
<a id="phen.copy"></a>
#### copy
```python
def copy(phen_dir: str, target_dir: str, version: str)
```
Copys a phen repo at a specific tagged version into a target directory
<a id="phen.extract_concepts"></a>
#### extract\_concepts
```python
def extract_concepts(config_data: dict) -> Tuple[dict, Set[str]]
```
Extracts concepts as {name: file_path} dictionary and a name set.
<a id="phen.extract_clean_deepdiff_keys"></a>
#### extract\_clean\_deepdiff\_keys
```python
def extract_clean_deepdiff_keys(diff: dict, key_type: str) -> Set[Any]
```
Extracts clean keys from a DeepDiff dictionary.
**Arguments**:
- `diff`: DeepDiff result dictionary
- `key_type`: The type of change to extract (e.g., "dictionary_item_added", "dictionary_item_removed")
**Returns**:
A set of clean key names
<a id="phen.diff_phen"></a>
#### diff\_phen
```python
def diff_phen(new_phen_path: Path, new_version: str, old_phen_path: Path,
old_version: str, report_path: Path)
```
Compare the differences between two versions of a phenotype
<a id="trud"></a>
# trud
<a id="trud.get_releases"></a>
#### get\_releases
```python
def get_releases(item_id: str, API_KEY: str, latest=False) -> list
```
Retrieve release information for an item from the TRUD API.
<a id="trud.download_release_file"></a>
#### download\_release\_file
```python
def download_release_file(item_id: str, release_ordinal: str, release: dict,
file_json_prefix: str) -> Path
```
Download specified file type for a given release of an item.
<a id="trud.create_map_directories"></a>
#### create\_map\_directories
```python
def create_map_directories()
```
Create map directories.
docs/api/acmc/omop.html
+ 322
− 324
View file @ f29f45bc
This diff is collapsed.
docs/api/acmc/parse.html
+ 441
− 475
View file @ f29f45bc
This diff is collapsed.
docs/api/acmc/phen.html
+ 2383
− 2389
View file @ f29f45bc
This diff is collapsed.
docs/api/acmc/trud.html
+ 753
− 751
View file @ f29f45bc
This diff is collapsed.
docs/api/search.js
+ 1
− 1
View file @ f29f45bc
This diff is collapsed.
docs/index.md
+ 190
− 12
View file @ f29f45bc
# ACMC Documentation
# User Guide
## Contents
- [Phenotype Workflow](#phenotype-workflow)
- [Phenotype Definition](#phenotype-definition)
- [Version Control](#version-control)
- [Installation](./installation.md)
- [User Guide](./user-guide.md)
- [Usage](./usage.md)
- Tutorials
- [Example 1 - Basic local phenotype](./tutorials/example1.md)
- [Example 2 - More complex local phenotype](./tutorials/example2.md)
- [Example 3 - Using a remote git repository](./tutorials/example3.md)
- [API Reference](./api.md)
- [Change Log](./changelog.md)
- [Troubleshooting](./troubleshooting.md)
## Phenotype Workflow
ACMC has a five step workflow to create a phenotype including steps initialise, validate, map, publish and export
### Step 1: Initialise
The `initialise` step creates a phenotype directory within the acmc workspace. The outcome will be a directory with all
required subdirectories and files, see [directory structure](#phenotype-directory-structure)
```bash
acmc phen init
```
### Step 2: Validate
The `validate` step checks that the phenotype configuration is valid including verification of the
configuration file according to schema and consistency between concept sets and source concept coding lists. The outcome will be notifications of the validity of the phenotype configuration.
```bash
acmc phen validate
```
### Step 3: Map
The `map` step performs code translations between source and target coding types. The outcome will be a concept sets defined for the target coding types stored in CSV files.
```bash
acmc phen map
```
### Step 4: Publish
The `publish` step commits the phenotype to a git repo and increments the version number. The outcome will be a published phenotype at the next version number
```bash
acmc phen publish
```
### Step 5: Export
The `export` step creates an OMOP database for the phenotype. The outcome will be an OMOP database including concept sets for all target coding types exported as CSV files
```bash
acmc phen export
```
## Phenotype Definition
### **Phenotype directory structure**
```
workspace/ # Default workspace directory
├── phen/ # Default phenotype directory
│ ├── concepts/ # Phenotype source concept code lists directory
│ ├── concept-sets/ # Processed phenotype concept sets
│ │ ├── csv/ # Processed phenotype concept sets in ACMC CSV format
│ │ ├── omop/ # Processed phenotype concept sets in OMOP CDM database exported as CSV files
│ ├── map/ # Process mapping from source to target code types
│ │ ├── errors/ # Errors recorded during mapping process
│ ├── config.yaml # Phenotype configuration file
│ ├── vocab_versions.yaml # Versions file for vocabularies used to generate concept sets
```
### **Configuration File**
Phenotype configuration is stored in the root of the phenotype directory in `config.yaml`. The file is yaml format.
#### **Root Phenotype Element**
- `phenotype`: **(object)** The root element containing all phenotype-related concept sets and metadata.
#### **Phenotype Attributes**
- `version`: **(string)** Specifies the version of the phenotype definition.
- `omop`: **(object)** Metadata related to OMOP vocabulary.
- `vocabulary_id`: **(string)** Identifier for the vocabulary.
- `vocabulary_name`: **(string)** Human-readable name of the vocabulary.
- `vocabulary_reference`: **(string, URL)** A reference URL for the vocabulary source.
#### **Concept Sets**
- `concept_sets`: **(array)** A list of concept set definitions, where each item has the following attributes:
- `name`: **(string)** Unique name of the concept set.
- `file`: **(object)** Contains file-related metadata.
- `path`: **(string, file path)** Relative path to the source concepts coding list file, relative to `<phen_directory>/concepts`
- `columns`: **(object)** Key-value pairs mapping column names in the file to coding list types
- `category` **(optional, string)** A categorical identifier for processing files containing multiple concept sets.
- `actions` **(optional, object)** Additional transformations on data.
- `divide_col`: **(string)** Specifies a column name in the source concept file to group on.
- `metadata`: **(object)** Reserved for additional metadata.
## **Version Control**
ACMC uses [Git](https://git-scm.com/) to support versioning of phenotypes. Git is a version control system that track changes in documents such as source coding lists, coding maps or configuration files. Using git allows ACMC to track versions and changes.
When a phenotype is initialised the directory is configured as a Git repository. ACMC then provides a simplified interaction with Git through a specific workflow using ACMC commands including integrate with remote Git services such as [GitLab](https://about.gitlab.com/) or [GitHub](https://github.com/).
ACMC does not currently support merging contributions from multiple collaborators on a phenotype through ACMC commands. This has to be done using existing Git tools.
### **Version Numbers**
ACMC uses [semantic versioning](https://semver.org/) to version phenotypes. Semantic versioning uses three numbers MAJOR.MINOR.PATCH where each number is incremented depending on the significance of the change. Although semantic versioning is designed for sofware the idea of major, minor and patch changes is retained for the phenotype as per the following
- MAJOR version when you make changes to concept sets
- MINOR version when you make changes to coding list concepts
- PATCH version when you make other minor changes such as documentation
### **Workflows**
ACMC supports local and remote repositories
#### **Local Workflow**
A local phenotype is only stored within a directory on a filesystem. The following command will create a git repository with the initial phenotype directory structure and make a commit to the git repository.
```bash
acmc phen init
```
You can then configure your phenotype and generate maps to other coding types as required. When you are finished and happy to publish a version of your phenotype, you run the following command
```bash
acmc phen publish
```
This will commit the changes to the git repository and generate a new version number. If this is the first publish the initial version will be `0.0.1`. You can tell ACMC how to increment the version using the `-i` argument with either major, minor or patch. The defaul is a patch change, i.e. incrementing the patch number. Using the following command will create a major release `1.0.0`
```bash
acmc phen publish -i major
```
#### **Remote Workflow**
A remote phenotype is stored on a central server that can be accessed remotely by others. Common central services include GitHub or GitLab (public or private). You can connect your local phenotype to a remote repository during initialisation or publication. When connecting to a remote repository it is important and recommended that you connect to an empty repo without any previous commits. Do not initialise it with a readme.md file, which is often the default. If there are commits you will need to resolve the conflicts manually before ACMC will work.
To initiatise a phenotype with a remote Git repository using the following command replacing the git URL with the URL to your remote repo.
```bash
acmc phen init -r https://git.soton.ac.uk/meldb/remote-phenotype.git
```
If you have a local phenotype and later want to connect it to a remote phenotype you can do this when it's published
```bash
acmc phen publish -r https://git.soton.ac.uk/meldb/remote-phenotype.git
```
#### **Fork Remote Workflow**
If there is an existing published remote phenotype that you want to use as a starting point you can fork the upstream repo and create a new phenotype. To do this you can run the following command to create a fork of the remote repo in a local directory
```bash
acmc fork -u https://git.soton.ac.uk/meldb/forked-phenotype.git -v 1.0.0
```
If you want to fork the repo and connect this to a remote repo you can run the following command.
```bash
acmc fork -u https://git.soton.ac.uk/meldb/forked-phenotype.git -v 1.0.0 -r https://git.soton.ac.uk/meldb/remote-phenotype.git
```
Alternatively you can connect the remote repo later when you publish
```bash
acmc phen publish -r https://git.soton.ac.uk/meldb/remote-phenotype.git
```
### Supported Medical Coding Standards
The tool supports verification and mapping across diagnostic coding formats below:
| Medical Code | Verification | Translation to |
|---------------|--------------|-----------------------------------|
| Readv2 | NHS TRUD | Readv3, SNOMED, ICD10, OPCS4, ATC |
| Readv3 (CTV3) | NHS TRUD | Readv3, SNOMED, ICD10, OPCS4 |
| ICD10 | NHS TRUD | None |
| SNOMED | NHS TRUD | None |
| OPCS4 | NHS TRUD | None |
| ATC | None | None |
- [**Read V2:**](https://digital.nhs.uk/services/terminology-and-classifications/read-codes) NHS clinical terminology standard used in primary care and replaced by SNOMED-CT in 2018; Still supported by some data providers as widely used in primary care, e.g. [SAIL Databank](https://saildatabank.com/)
- [**SNOMED-CT:**](https://icd.who.int/browse10/2019/en) international standard for clinical terminology for Electronic Healthcare Records adopted by the NHS in 2018; Mappings to Read codes are partially provided by [Clinical Research Practice Database (CPRD)](https://www.cprd.com/) and [NHS Technology Reference Update Distribution (TRUD)](https://isd.digital.nhs.uk/trud).
- [**ICD-10:**](https://icd.who.int/browse10/2019/en) International Classification of Diseases (ICD) is a medical classification list from the World Health Organization (WHO) and widely used in hospital settings, e.g. Hospital Episode Statistics (HES).
- [**ATC Codes:**](https://www.who.int/tools/atc-ddd-toolkit/atc-classification) Anatomical Therapeutic Chemical (ATC) Classification is a drug classification list from the World Health Organization (WHO)
## Notes
Processed resources will be saved in the `build/maps/processed/` directory.
*Note: NHS TRUD provides one-way mappings. To reverse mappings, duplicate the `.parquet` file and reverse the filename (e.g., `read2_code_to_snomed_code.parquet` to `snomed_code_to_read2_code.parquet`).*
docs/user-guide.md deleted 100644 → 0
+ 0
− 193
View file @ 9254ae24
# User Guide
- [Phenotype Workflow](#phenotype-workflow)
- [Phenotype Definition](#phenotype-definition)
- [Version Control](#version-control)
## Phenotype Workflow
ACMC has a five step workflow to create a phenotype including steps initialise, validate, map, publish and export
### Step 1: Initialise
The `initialise` step creates a phenotype directory within the acmc workspace. The outcome will be a directory with all
required subdirectories and files, see [directory structure](#phenotype-directory-structure)
```bash
acmc phen init
```
### Step 2: Validate
The `validate` step checks that the phenotype configuration is valid including verification of the
configuration file according to schema and consistency between concept sets and source concept coding lists. The outcome will be notifications of the validity of the phenotype configuration.
```bash
acmc phen validate
```
### Step 3: Map
The `map` step performs code translations between source and target coding types. The outcome will be a concept sets defined for the target coding types stored in CSV files.
```bash
acmc phen map
```
### Step 4: Publish
The `publish` step commits the phenotype to a git repo and increments the version number. The outcome will be a published phenotype at the next version number
```bash
acmc phen publish
```
### Step 5: Export
The `export` step creates an OMOP database for the phenotype. The outcome will be an OMOP database including concept sets for all target coding types exported as CSV files
```bash
acmc phen export
```
## Phenotype Definition
### **Phenotype directory structure**
```
workspace/ # Default workspace directory
├── phen/ # Default phenotype directory
│ ├── concepts/ # Phenotype source concept code lists directory
│ ├── concept-sets/ # Processed phenotype concept sets
│ │ ├── csv/ # Processed phenotype concept sets in ACMC CSV format
│ │ ├── omop/ # Processed phenotype concept sets in OMOP CDM database exported as CSV files
│ ├── map/ # Process mapping from source to target code types
│ │ ├── errors/ # Errors recorded during mapping process
│ ├── config.yaml # Phenotype configuration file
│ ├── vocab_versions.yaml # Versions file for vocabularies used to generate concept sets
```
### **Configuration File**
Phenotype configuration is stored in the root of the phenotype directory in `config.yaml`. The file is yaml format.
#### **Root Phenotype Element**
- `phenotype`: **(object)** The root element containing all phenotype-related concept sets and metadata.
#### **Phenotype Attributes**
- `version`: **(string)** Specifies the version of the phenotype definition.
- `omop`: **(object)** Metadata related to OMOP vocabulary.
- `vocabulary_id`: **(string)** Identifier for the vocabulary.
- `vocabulary_name`: **(string)** Human-readable name of the vocabulary.
- `vocabulary_reference`: **(string, URL)** A reference URL for the vocabulary source.
#### **Concept Sets**
- `concept_sets`: **(array)** A list of concept set definitions, where each item has the following attributes:
- `name`: **(string)** Unique name of the concept set.
- `file`: **(object)** Contains file-related metadata.
- `path`: **(string, file path)** Relative path to the source concepts coding list file, relative to `<phen_directory>/concepts`
- `columns`: **(object)** Key-value pairs mapping column names in the file to coding list types
- `category` **(optional, string)** A categorical identifier for processing files containing multiple concept sets.
- `actions` **(optional, object)** Additional transformations on data.
- `divide_col`: **(string)** Specifies a column name in the source concept file to group on.
- `metadata`: **(object)** Reserved for additional metadata.
## **Version Control**
ACMC uses [Git](https://git-scm.com/) to support versioning of phenotypes. Git is a version control system that track changes in documents such as source coding lists, coding maps or configuration files. Using git allows ACMC to track versions and changes.
When a phenotype is initialised the directory is configured as a Git repository. ACMC then provides a simplified interaction with Git through a specific workflow using ACMC commands including integrate with remote Git services such as [GitLab](https://about.gitlab.com/) or [GitHub](https://github.com/).
ACMC does not currently support merging contributions from multiple collaborators on a phenotype through ACMC commands. This has to be done using existing Git tools.
### **Version Numbers**
ACMC uses [semantic versioning](https://semver.org/) to version phenotypes. Semantic versioning uses three numbers MAJOR.MINOR.PATCH where each number is incremented depending on the significance of the change. Although semantic versioning is designed for sofware the idea of major, minor and patch changes is retained for the phenotype as per the following
- MAJOR version when you make changes to concept sets
- MINOR version when you make changes to coding list concepts
- PATCH version when you make other minor changes such as documentation
### **Workflows**
ACMC supports local and remote repositories
#### **Local Workflow**
A local phenotype is only stored within a directory on a filesystem. The following command will create a git repository with the initial phenotype directory structure and make a commit to the git repository.
```bash
acmc phen init
```
You can then configure your phenotype and generate maps to other coding types as required. When you are finished and happy to publish a version of your phenotype, you run the following command
```bash
acmc phen publish
```
This will commit the changes to the git repository and generate a new version number. If this is the first publish the initial version will be `0.0.1`. You can tell ACMC how to increment the version using the `-i` argument with either major, minor or patch. The defaul is a patch change, i.e. incrementing the patch number. Using the following command will create a major release `1.0.0`
```bash
acmc phen publish -i major
```
#### **Remote Workflow**
A remote phenotype is stored on a central server that can be accessed remotely by others. Common central services include GitHub or GitLab (public or private). You can connect your local phenotype to a remote repository during initialisation or publication. When connecting to a remote repository it is important and recommended that you connect to an empty repo without any previous commits. Do not initialise it with a readme.md file, which is often the default. If there are commits you will need to resolve the conflicts manually before ACMC will work.
To initiatise a phenotype with a remote Git repository using the following command replacing the git URL with the URL to your remote repo.
```bash
acmc phen init -r https://git.soton.ac.uk/meldb/remote-phenotype.git
```
If you have a local phenotype and later want to connect it to a remote phenotype you can do this when it's published
```bash
acmc phen publish -r https://git.soton.ac.uk/meldb/remote-phenotype.git
```
#### **Fork Remote Workflow**
If there is an existing published remote phenotype that you want to use as a starting point you can fork the upstream repo and create a new phenotype. To do this you can run the following command to create a fork of the remote repo in a local directory
```bash
acmc fork -u https://git.soton.ac.uk/meldb/forked-phenotype.git -v 1.0.0
```
If you want to fork the repo and connect this to a remote repo you can run the following command.
```bash
acmc fork -u https://git.soton.ac.uk/meldb/forked-phenotype.git -v 1.0.0 -r https://git.soton.ac.uk/meldb/remote-phenotype.git
```
Alternatively you can connect the remote repo later when you publish
```bash
acmc phen publish -r https://git.soton.ac.uk/meldb/remote-phenotype.git
```
### Supported Medical Coding Standards
The tool supports verification and mapping across diagnostic coding formats below:
| Medical Code | Verification | Translation to |
|---------------|--------------|-----------------------------------|
| Readv2 | NHS TRUD | Readv3, SNOMED, ICD10, OPCS4, ATC |
| Readv3 (CTV3) | NHS TRUD | Readv3, SNOMED, ICD10, OPCS4 |
| ICD10 | NHS TRUD | None |
| SNOMED | NHS TRUD | None |
| OPCS4 | NHS TRUD | None |
| ATC | None | None |
- [**Read V2:**](https://digital.nhs.uk/services/terminology-and-classifications/read-codes) NHS clinical terminology standard used in primary care and replaced by SNOMED-CT in 2018; Still supported by some data providers as widely used in primary care, e.g. [SAIL Databank](https://saildatabank.com/)
- [**SNOMED-CT:**](https://icd.who.int/browse10/2019/en) international standard for clinical terminology for Electronic Healthcare Records adopted by the NHS in 2018; Mappings to Read codes are partially provided by [Clinical Research Practice Database (CPRD)](https://www.cprd.com/) and [NHS Technology Reference Update Distribution (TRUD)](https://isd.digital.nhs.uk/trud).
- [**ICD-10:**](https://icd.who.int/browse10/2019/en) International Classification of Diseases (ICD) is a medical classification list from the World Health Organization (WHO) and widely used in hospital settings, e.g. Hospital Episode Statistics (HES).
- [**ATC Codes:**](https://www.who.int/tools/atc-ddd-toolkit/atc-classification) Anatomical Therapeutic Chemical (ATC) Classification is a drug classification list from the World Health Organization (WHO)
## Notes
Processed resources will be saved in the `build/maps/processed/` directory.
*Note: NHS TRUD provides one-way mappings. To reverse mappings, duplicate the `.parquet` file and reverse the filename (e.g., `read2_code_to_snomed_code.parquet` to `snomed_code_to_read2_code.parquet`).*
mkdocs.yml 0 → 100644
+ 24
− 0
View file @ f29f45bc
site_name: ACMC Documentation
site_url: https://acmc.readthedocs.io
theme:
name: 'readthedocs'
nav:
- Home: index.md
- Installation: installation.md
- Tutorial 1 Basic local phenotype: tutorials/example1.md
- Tutorial 2 More complex local phenotype: tutorials/example2.md
- Tutorial 3 Using a remote git repository: tutorials/example3.md
- Comand Line Reference: usage.md
- API Reference: api/acmc.html
- Change Log: changelog.md
- Troubleshooting: troubleshooting.md
markdown_extensions:
- toc:
permalink: true
plugins:
- search
pydoc-markdown.yml deleted 100644 → 0
+ 0
− 6
View file @ 9254ae24
loaders:
- type: python
search_path: ["./acmc"]
renderer:
type: markdown
pyproject.toml
+ 9
− 3
View file @ f29f45bc
......@@ -51,7 +51,7 @@ acmc = "acmc.main:main" # Entry point for CLI command
[project.urls]
Repository = "https://git.soton.ac.uk/meldb/concepts-processing"
Documentation = "https://git.soton.ac.uk/meldb/concepts-processing/docs"
Documentation = "https://acmc.readthedocs.io/en/latest/"
Issues = "https://git.soton.ac.uk/meldb/concepts-processing/-/issues"
......@@ -63,6 +63,12 @@ dependencies = [
"hatch",
"pytest",
]
[tool.hatch.envs.docs]
dependencies = [
"mkdocs",
"mkdocs-material"
]
[tool.hatch.envs.dev]
dependencies = [
......@@ -71,13 +77,13 @@ dependencies = [
"mypy",
"pdoc",
"pydoc-markdown",
"mkdocs"
]
[tool.hatch.envs.dev.scripts]
format = "black ."
type = "mypy ."
docs = "pydoc-markdown > docs/api.md"
htmldocs = "pdoc -o docs/api -d markdown --docformat markdown --include-undocumented acmc"
docs = "pdoc -o docs/api -d markdown --docformat markdown --include-undocumented acmc"
precommit = "hatch run format && hatch run type && hatch run docs"
[tool.hatch.build]
......
readthedocs.yml 0 → 100644
+ 17
− 0
View file @ f29f45bc
# Read the Docs configuration file for MkDocs projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python and other tools you might need
build:
os: ubuntu-24.04
tools:
python: "3.12"
mkdocs:
configuration: mkdocs.yml
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment