From 859d27c788551a48eb66bff6531d736e1a40c30a Mon Sep 17 00:00:00 2001
From: Jakub Dylag <jjd1c23@soton.ac.uk>
Date: Wed, 26 Mar 2025 12:57:02 +0000
Subject: [PATCH] (Docs) Simple Local workflow Example

---
 docs/examples/example1.md | 134 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 133 insertions(+), 1 deletion(-)

diff --git a/docs/examples/example1.md b/docs/examples/example1.md
index c53aae5..a3933d7 100644
--- a/docs/examples/example1.md
+++ b/docs/examples/example1.md
@@ -1,3 +1,135 @@
 # Tutorial 1 Basic local phenotype
 
-TODO
+This examples sets up a phenotype workspace environment, installs dependencies, configures necessary files, and validates and maps phenotypes to read2.
+
+1. **Clone the Git Repository:**  
+    ```sh
+    git clone <repository_url>
+    ```
+    This copies the remote repository to your local machine.
+
+2. **Navigate to the Project Directory:**  
+    ```sh
+    cd concepts-processing
+    ```
+    Moves into the cloned repository's directory.
+
+3. **Create a Virtual Environment:**  
+    ```sh
+    py -m venv venv
+    ```
+    This sets up an Virtual Python environment named `venv`.
+
+4. **Upgrade `pip`:**  
+    ```sh
+    python -m pip install --upgrade pip
+    ```
+    Ensures you have the latest version of `pip`, which helps manage dependencies.
+
+5. **Install the Required Package (`acmc`):**  
+    ```sh
+    pip install acmc
+    ```
+    Installs `acmc`, which is likely a package required for processing concepts.
+
+6. **Initialize a Phenotype Project:**  
+    ```sh
+    acmc phen init
+    ```
+    Sets up the workspace file strucutre for working with phenotype concepts. An example phenotype project is created within the `phen` sub-folder.
+
+7. **Download TRUD Data:**  
+    Downloads necessary TRUD (Terminology Reference Data) files, for concept verification and translation. 
+
+    1. **Register at TRUD**
+
+        Registry your account with TRUD  at [NHS TRUD](https://isd.digital.nhs.uk/trud/user/guest/group/0/account/form).
+
+    2. **Subscribe and Accept Licenses**: Subscribe to the following data files:
+
+        - [NHS Read Browser](https://isd.digital.nhs.uk/trud/users/guest/filters/2/categories/9/items/8/releases)
+        - [NHS Data Migration](https://isd.digital.nhs.uk/trud/users/guest/filters/0/categories/8/items/9/releases)
+        - [ICD10 Edition 5 XML](https://isd.digital.nhs.uk/trud/users/guest/filters/0/categories/28/items/259/releases)
+        - [OPCS-4.10 Data Files](https://isd.digital.nhs.uk/trud/users/guest/filters/0/categories/10/items/119/releases)
+
+        After subscribing, you'll receive an API key once your request is approved (usually within a few hours).
+
+    3. **Get TRUD API KEY**
+
+        Copy your API key from [NHS TRUD Account Management](https://isd.digital.nhs.uk/trud/users/authenticated/filters/0/account/manage) and store it securely.
+
+    4. **Add TRUD API KEY to as an environment variable**
+
+        To set the environment variable temporarily (for the current session), run:
+
+        On macOS/Linux:
+
+        ```bash
+        export ACMC_TRUD_API_KEY="your_api_key_here"
+        ```
+
+        On Windows (Command Prompt or PowerShell):
+
+        ```bash
+        setx ACMC_TRUD_API_KEY "your_api_key_here"
+        ```
+
+    5. **Install TRUD within ACMC**
+        ```sh
+        acmc trud install
+        ```
+
+8. **Create Phenotype Configuration:**  
+    Modify the `config.yml` file as needed for your project settings.
+    For more information on see the [configuration file documentation](https://acmc.readthedocs.io/en/latest/#configuration-file). 
+
+9. **Validate the Phenotype Configuration:**  
+    Use the followijng `acmc` command to validate the phenotype configuration to ensure it's correct:
+    ```sh
+    acmc phen validate -d workspace\phen
+    ```
+    Checks that the phenotype definitions are correctly structured and valid.
+
+    Expected Output:
+    ```bash
+    [INFO] - Validating phenotype: <path>/concepts-processing/workspace/phen
+    [INFO] - Phenotype validated successfully
+    ```
+
+10. **Map Phenotype Data:**  
+    Maps the phenotype data using the `read2` vocabulary.
+    ```sh
+    acmc phen map -d workspace\phen -t read2
+    ```
+
+11. **Publish phenotype at an initial version**
+
+	Use the following `acmc` command to publish the phenotype at an initial version:
+
+    ```bash
+    acmc phen publish
+    ```
+
+12. **Compare the previous version `0.0.1` with the latest version**
+
+	Use the following `acmc` command to compare the previous version `0.0.1` with the latest version in the workspace phen directory:
+
+    ```bash
+    acmc phen diff -ov 0.0.1
+    ```
+
+13. **Publish the phenotype at a major version**
+
+	Use the following `acmc` command to publish the phenotype at a major version:
+
+    ```bash
+    acmc phen publish -i major
+    ```
+
+
+
+## Support
+
+If you need help please open an [issue in the repository](https://git.soton.ac.uk/meldb/concepts-processing/-/issues)
+
+
-- 
GitLab