docs(medcat-trainer): docs updates

medcat-trainer/docs/annotator_guide.md

@@ -21,26 +21,38 @@ Select spans by clicking them directly, then apply one status from the task bar.
 
 ### Supported concept statuses
 
-- **Correct**
-- **Incorrect**
-- **Terminate** (if enabled for project)
-- **Alternative** (choose a different concept)
-- **Irrelevant** (if enabled for project)
+| Status        | Meaning                                                                                   |
+|---------------|------------------------------------------------------------------------------------------|
+| **Correct**   | The detected concept annotation is correct for this span of text.                         |
+| **Incorrect** | The detected concept annotation is incorrect and should not be assigned to this span.     |
+| **Terminate** | (If enabled) This sends a strong signal to the underlying model that no further suggestions wanted like this. |
+| **Alternative** | The annotation is wrong, but a different concept should be assigned (choose another concept). |
+| **Irrelevant** | (If enabled) The annotation is not relevant to the project or task context.             |
 
 Only one status can be active per concept at a time.
 
 ### Adding missing annotations
 
 If the model missed a mention:
 
-1. Highlight text in the document.
-2. Right-click and choose **Add Term**.
-3. Search/select a concept in the concept picker.
-4. Confirm to create the annotation.
+| Step | Action | Screenshot |
+|------|--------|------------|
+| 1 | Highlight text in the document. | ![](_static/img/add-annotation-text.png) |
+| 2 | Right-click and choose **Add Term**. | ![](_static/img/add-annotation-menu.png) |
+| 3 | Search/select a concept in the concept picker. | ![](_static/img/add-annotation-concept.png) |
+| 4 | Confirm to create the annotation. | ![](_static/img/add-annotation-select-concept.png) |
 
-Projects with `add_new_entities` enabled can also create brand-new concepts.
+### Adding New Concepts
+
+Projects with `Add New Entities` enabled can also create brand-new concepts. This option should be used with caution as most concept databases will be complete for most use cases. Before creating new concepts agree with the project admin the set of concepts that should be created.
+
+![](_static/img/add-new-concept.png)
+
+
+### Overlapping Annotations
+
+This allows the data collection of entities that span the same portion of text across multiple entities.
 
-Overlapping annotations are supported.
 
 ## 3) Task bar and submission
 
@@ -56,9 +68,9 @@ The task bar contains status buttons and the **Submit** button.
 Top-right actions:
 
 - **Summary**: open document annotation summary.
-- **Help**: keyboard shortcuts and project guidance.
+- **Help**: keyboard shortcuts, project guidance.
 - **Reset document**: re-prepare current document and clear document-level
-  annotation state.
+  annotation state. This returns the document to its pre-annotated state.
 
 ## 5) Right sidebar (concept details)
 
@@ -74,12 +86,57 @@ If enabled by project settings, a **Comment** field is also available.
 !!! tip
     If the details are not showing in the sidebar after you've selected one, the issue is likely with an unfinished Project setup. See the section for "Concept lookup index (Solr import)" in the [Project Creation and Management Guide](project_admin.md) for details.
 
-## Meta annotations and relations
+## Meta annotations
 
 Depending on project configuration:
 
-- **Meta Annotation Tasks** appear for relevant concept statuses.
-- **Relation** tab appears to create/edit relations between annotated entities.
+Configured **Meta Annotation Tasks** appear for concepts that are marked as correct by an annotator
+
+!!! tip
+    Meta Annotation Tasks and the associated values for each task are imported automatically from MedCAT model packs once they are uploaded via `/project-admin/`.
+
+### Annotating Meta Tasks
+
+When a concept is selected and marked as **Correct** (or Alternative), the right sidebar will display **Meta Annotation Tasks** for that concept, if any are configured for the project. These are contextual classifications for the given concept.
+
+- Each task (e.g., Temporality, Assertion, Experiencer) appears as a set of selectable options (radio buttons or toggle chips).
+- Select the value(s) which best apply to the concept occurrence.
+- **Meta tasks must be completed as required** before the document can be submitted.
+
+Meta annotation fields may also show predicted values if your project uses a model pack with MetaCAT models. You can override or confirm these predictions before submission.
+
+**Example:**
+
+> For "sore throat":
+> - Temporality: **Present (selected)**
+> - Assertion: **Affirmed (selected)**
+> - Experiencer: **Patient (selected)**
+
+Missing or incomplete meta task selection will highlight the meta section and prevent submitting until all required fields are filled.
+
+For more on configuring meta tasks, see [Meta Annotations](meta_annotations.md).
+
+![Meta Annotation Interface](_static/img/meta-tasks-interface.png)
+
+### Annotating Relations
+
+Relation annotations allow you to specify the relationship(s) between two or more concepts in a document (for example, linking "right sided" as a laterality descriptor for a symptom e.g. "facial droop"). If your project is configured for relation annotation, the right sidebar will show available relation tasks when two or more relevant concepts are selected or highlighted in the document.
+
+- Each relation task will appear as a labeled field with possible relation types (e.g., "is treatment for", "causes", "associated with").
+- To annotate a relation, select the 'start' concept, then select the related 'end' concept. The relation options will become available between these concepts.
+- Pick the correct relation type from the options, or select "None" if no relation applies.
+- Some projects may allow multiple relations per concept pair.
+
+**Example:**
+
+> "right sided" ← **is a laterality descriptor for** → "facial droop"
+
+Relation annotation fields may be required before submitting a document, depending on the project setup. Incomplete required relations will block submission and highlight the needed fields.
+
+For guidance on configuring relations for your project, see [Meta Annotations](meta_annotations.md).
+
+![Relation Annotation Interface](_static/img/relation-interface.png)
+
 
 ## Keyboard shortcuts
 

medcat-trainer/docs/django_admin.md

@@ -0,0 +1,51 @@
+# Django Admin
+
+The **Django Admin** (`/admin`) provides advanced actions and low-level data
+management that are not available in the Project Admin UI (`/project-admin`).
+
+These include:
+
+
+
+## Concept lookup index (Solr import)
+
+Concept picker search requires CDB concepts to be imported into Solr.
+
+1. Open `/admin`.
+2. Go to **Concept Dbs**.
+3. Select one or more CDBs.
+4. Run **Import concepts** action.
+
+![](_static/img/select-concept-dbs.png)
+
+![](_static/img/import-concepts.png)
+
+After import, project list shows whether concepts are indexed for the selected
+`cdb_search_filter`.
+
+![](_static/img/concepts-imported-status.png)
+
+
+## Downloading annotations
+
+From Django admin (`/admin` -> **Project annotate entities**), use bulk actions
+to export annotations:
+
+- with source text
+- without source text
+- without source text but with document names
+
+![](_static/img/project_annotate_entities.png)
+
+![](_static/img/download-annos.png)
+
+Notebook examples for downstream processing are in:
+
+- `notebook_docs/Processing_Annotations.ipynb`
+
+## Saving and downloading model artifacts
+
+For online-learning projects, admins can save current model state from the
+project list. In general, offline retraining from exported annotations is still
+recommended for production model releases.
+

medcat-trainer/docs/index.md

@@ -38,6 +38,7 @@ review-only workflows (collect annotations without changing the model).
 - [Administrator Setup](admin_setup.md)
 - [Annotation Project Creation and Management](project_admin.md)
 - [Project Groups](project_group_admin.md)
+- [Django Admin](django_admin.md)
 - [Annotator Guide](annotator_guide.md)
 - [Meta Annotations](meta_annotations.md)
 - [Demo / Try Model](demo_page.md)

medcat-trainer/docs/installation.md

@@ -193,3 +193,6 @@ An example compose file is available at
 
 ## Next Steps
 Now that medcat trainer is installed and running, proceed to [Administrator Setup](admin_setup.md) to create the Admin user.
+
+
+<!-- LRTEST_MARKER_123 -->

medcat-trainer/docs/project_admin.md

@@ -1,56 +1,104 @@
 # Annotation Project Creation and Management
 
-MedCATtrainer supports two management surfaces:
+An annotation project requires 4 elements:
+
+| Element         | Description                                                                              |
+|-----------------|------------------------------------------------------------------------------------------|
+| Project setup   | Define the project’s name, purpose, and configuration settings.                          |
+| Model           | Manage the available MedCAT models or connect to a remote model service for annotation projects   |
+| Dataset         | Select or upload collections of documents to be annotated in projects             |
+| Users           | Manage admins, annotators and superusers who can participate in annotation projects.            |
+
+MedCATtrainer supports two management surfaces to create, update, delete these elements.
 
 - **Project Admin UI** (`/project-admin`) for most project operations.
 - **Django Admin** (`/admin`) for advanced actions and low-level data management.
 
-## Create a project (Project Admin UI)
+The following user guide covers. `/project-admin`
+
+## Project Administration
 
 1. Open `/project-admin`.
-2. Go to the **Projects** tab and select **Create New Project**.
-3. Fill in:
-    - **Basic information** (name, dataset, description, guideline link)
-    - **Model configuration**
-    - **Annotation settings**
-    - **Concept filter (optional)**
-    - **Members**
+2. Go to the **Projects** tab and select **+ Create New Project**. To edit an existing project select the project row.
+3. Complete the forms for your project. Specifics of each field are discussed below.
 4. Save.
 
-### Model configuration options
+### Basic Settings
+
+| Field                        | Description                                                                 |
+|------------------------------|-----------------------------------------------------------------------------|
+| **Project Name**             | Enter a name for your project.                                              |
+| **Dataset**                  | Select an existing dataset or [upload a new one](#dataset-administration) to associate with the project. |
+| **Description**              | Optionally provide a short summary describing your project.                 |
+| **Guideline Link**           | (Optional) Add a URL to annotation guidelines for annotators.               |
+
+### Project Settings
+| Field                        | Description                                                                 |
+|------------------------------|-----------------------------------------------------------------------------|
+| **Project Status** | Sets the current lifecycle stage of the project. Options are:<br>**Annotating** – Active annotation is ongoing;<br>**Complete** – Annotation is finished; further changes are prevented.<br>**Discontinued** – The project is no longer active and closed for annotation. |
+| **Project Locked** | Locks project from further annotation edits. |
+| **Annotation classification**        | **Checked**: Annotations are relevant for a 'global' model<br>**Unchecked**: Annotations are specific to this specific project and should not be used for further model training or fine-tuning |
 
-Pick exactly one of:
 
-1. **Model Pack** (recommended), or
-2. **Concept DB + Vocabulary** pair.
+### Model Configuration Settings
+Available MedCAT models are shown here. If this is empty, first [add a local model pack](#model-pack-administration).
 
-You may also enable:
+Pick one of:
+1. **Local Model Pack** (recommended), or
+2. **Use Concept DB + Vocabulary** pair. is a legacy MedCAT v1 option.
 
-- **Remote model service** (`use_model_service`) and provide
+- **Remote model service** (`use_model_service`) can be used where model inference is available at a remote url.
   `model_service_url`.
 
-Notes:
+!!! tip
+    - Remote model service projects do not support interim train-on-submit updates.
+    - You cannot set Model Pack and CDB/Vocab at the same time.
 
-- Remote model service projects do not support interim train-on-submit updates.
-- You cannot set Model Pack and CDB/Vocab at the same time.
+### Annotation Settings
+| Field                        | Description                                                                 |
+|------------------------------|-----------------------------------------------------------------------------|
+| **Require entity validation**        | If enabled, model suggestions must be explicitly reviewed before submit.|
+| **Train on submit**                  | If enabled, validated annotations are used for incremental training on submit. |
+| **Add new entities**               | Allows users to add brand-new concepts. Should be used with caution as most concept Dbs will be relatively complete for most use cases. |
+| **Restrict concept lookup** | Restricts concept search to project CUI filters. |
+| **Terminate available** | Shows terminate action in annotation toolbar. |
+| **Irrelevant available** | Shows irrelevant action in annotation toolbar. |
+| **Entity annotation comments** | Enables free-text comments per annotation. |
 
-### Key project settings
+### Concept Filtering
+| Field                        | Description                                                                 |
+|------------------------------|-----------------------------------------------------------------------------|
+| **Incl. Sub-concepts**         | Include all concepts that are descendants to the selected concepts below.
+| **Concept filter (optional)**| Add concept filters to limit available concepts for annotation by specifying a list of CUIs (Concept Unique Identifiers). Only these concepts will be available when annotating. |
+
+### Member Setting
+| Field                        | Description                                                                 |
+|------------------------------|-----------------------------------------------------------------------------|
+| **Members**                  | Add users to the project as annotators, administrators, or reviewers, controlling their access and editing permissions for this project. |
 
-| Setting | Description |
-|---|---|
-| `require_entity_validation` | If enabled, model suggestions must be explicitly reviewed before submit. |
-| `train_model_on_submit` | If enabled, validated annotations are used for incremental training on submit. |
-| `add_new_entities` | Allows users to add brand-new concepts. |
-| `restrict_concept_lookup` | Restricts concept search to project CUI filters. |
-| `terminate_available` | Shows terminate action in annotation toolbar. |
-| `irrelevant_available` | Shows irrelevant action in annotation toolbar. |
-| `enable_entity_annotation_comments` | Enables free-text comments per annotation. |
-| `tasks` | Meta annotation tasks available in the annotator UI. |
-| `relations` | Relation labels available for relation annotation. |
-| `project_locked` | Locks project from further annotation edits. |
-| `project_status` | Annotating / Complete / Discontinued. |
-
-## Dataset format
+
+## Model Pack Administration
+Manage the available local MedCAT models that can be configured into annotation projects
+
+1. Open `/project-admin`.
+2. Go to the **Model Packs** tab and select **+ Add Model Pack** OR a row to edit an existing model pack entry.
+3. Complete the forms for your project. Specifics of each field are discussed below.
+4. Save.
+
+To delete a model pack, use the action button.
+
+!!! tip
+    - Only model packs are shown here. Legacy ConceptDB, Vocabulary models are not availabe from `/project-admin/`, they are only available from `/admin/`.
+    - remote model service endpoints are directly entered as URLs within annotation projects
+
+
+## Dataset Administration
+Manage the availalbe datasets that can be configured into annotation projects.
+
+1. Open `/project-admin`.
+2. Go to the **Datasets** tab and select **+ Add Dataset** OR a row to edit a dataset entry.
+3. Complete the forms for your project. Specifics of each field are discussed below.
+4. Save.
 
 Upload CSV or XLSX with at least:
 
@@ -70,45 +118,3 @@ From the home **Projects** table:
 - Save current model state.
 - Select compatible projects and submit a metrics report.
 
-## Concept lookup index (Solr import)
-
-Concept picker search requires CDB concepts to be imported into Solr.
-
-1. Open `/admin`.
-2. Go to **Concept Dbs**.
-3. Select one or more CDBs.
-4. Run **Import concepts** action.
-
-After import, project list shows whether concepts are indexed for the selected
-`cdb_search_filter`.
-
-## Clone, reset, and delete
-
-### In Project Admin UI
-
-- **Clone**: duplicate project configuration under a new name.
-- **Reset**: remove annotations and clear prepared/validated document state.
-- **Delete**: permanently remove the project.
-
-### In Django Admin
-
-Equivalent bulk actions are available under **Project annotate entities**.
-
-## Downloading annotations
-
-From Django admin (`/admin` -> **Project annotate entities**), use bulk actions
-to export annotations:
-
-- with source text
-- without source text
-- without source text but with document names
-
-Notebook examples for downstream processing are in:
-
-- `notebook_docs/Processing_Annotations.ipynb`
-
-## Saving and downloading model artifacts
-
-For online-learning projects, admins can save current model state from the
-project list. In general, offline retraining from exported annotations is still
-recommended for production model releases.

medcat-trainer/mkdocs.yml

@@ -42,6 +42,7 @@ nav:
         - Administrator setup: admin_setup.md
         - Annotation Project admin: project_admin.md
         - Annotation Project group admin: project_group_admin.md
+        - Django Admin: django_admin.md
       - Meta annotations: meta_annotations.md
   - Reference: 
     - Advanced usage: advanced_usage.md