diff --git a/medcat-trainer/docs/admin_setup.md b/medcat-trainer/docs/admin_setup.md index 96bf88e7b..0508f2b77 100644 --- a/medcat-trainer/docs/admin_setup.md +++ b/medcat-trainer/docs/admin_setup.md @@ -13,23 +13,30 @@ Before first startup in production-like environments, set: If not set, MedCATtrainer defaults to `admin` / `admin`, which is not suitable for production. -## 2) Sign in and create operational admin users +## 2) Sign in -You can manage users from: +Staff and superuser accounts see a cog icon at the top-right of the header. +That opens **Project Administration** (`/project-admin`), used to set up +users, datasets, model packs, projects, and project groups. See +[Project Administration](project_admin.md). -- **Project Admin UI** (`/project-admin`) for day-to-day project operations -- **Django Admin** (`/admin`) for full platform administration +Django Admin (`/admin`) remains the place for full platform administration, +including passwords and actions this screen does not cover. -In Django admin (`/admin`), create at least one dedicated administrator account -and grant: +Create at least one dedicated administrator and grant: -- `Staff status` for admin access -- `Superuser status` for full unrestricted access +- `Staff status`, so the account can open the cog icon +- `Superuser status`, for unrestricted access, including Django admin ## 3) Create annotator users -Create users for annotators and add them to project membership lists. -Annotators do not need staff/superuser flags. +Add annotators from the **Users** tab on Project Administration, then add +them to a project or project group. Annotators do not need staff or +superuser flags. + +The password field on that form is not stored. Set each password in Django +admin (`/admin` -> **Users**), or through the password-reset flow, before +the person signs in. ## 4) Remove or rotate bootstrap credentials @@ -42,7 +49,7 @@ After creating named administrator accounts: When `USE_OIDC=1`, user permissions are mapped from IdP roles: -- `medcattrainer_superuser` -> Django superuser + staff -- `medcattrainer_staff` -> Django staff +- `medcattrainer_superuser` -> Django superuser + staff. This role shows the cog icon. +- `medcattrainer_staff` -> Django staff. This role does not show the cog icon. Ensure role assignment is correct in Keycloak before onboarding users. diff --git a/medcat-trainer/docs/advanced_usage.md b/medcat-trainer/docs/advanced_usage.md index 9fef36305..36f9e7de0 100644 --- a/medcat-trainer/docs/advanced_usage.md +++ b/medcat-trainer/docs/advanced_usage.md @@ -37,6 +37,7 @@ Modern project-admin UI uses dedicated endpoints: - `GET/PUT/DELETE /api/project-admin/projects//` - `POST /api/project-admin/projects//clone/` - `POST /api/project-admin/projects//reset/` +- `POST /api/project-groups/` creates a project group and, by default, one annotation project per annotator ## Project Group APIs diff --git a/medcat-trainer/docs/annotator_guide.md b/medcat-trainer/docs/annotator_guide.md index eabf4529d..4fc6b4166 100644 --- a/medcat-trainer/docs/annotator_guide.md +++ b/medcat-trainer/docs/annotator_guide.md @@ -96,7 +96,7 @@ The sidebar shows details for the currently selected concept, including: 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. + If the details are not showing in the sidebar after you've selected one, the issue is likely with an unfinished Project setup. See [Concept lookup index (Solr import)](project_admin.md#concept-lookup-index-solr-import) in the Project Administration guide. ## Meta annotations diff --git a/medcat-trainer/docs/client.md b/medcat-trainer/docs/client.md index 1decdc658..1e7d3b3e2 100644 --- a/medcat-trainer/docs/client.md +++ b/medcat-trainer/docs/client.md @@ -98,6 +98,8 @@ required. - `get_meta_tasks()` - `get_rel_tasks()` - `get_projects()` +- `create_project_group(...)` +- `get_project_groups()` - `get_datasets()` - `get_project_annos(projects)` - `upload_projects_export(...)` @@ -108,8 +110,8 @@ required. ## Notes -- `create_project` and `create_project_group` expect **either** `modelpack` - **or** `concept_db + vocab`. +- `create_project` and `create_project_group` expect **either** `modelpack` **or** `concept_db + vocab`. +- `create_project_group` creates one annotation project per annotator when `create_associated_projects` is left at its default, `True`. - Wrapper objects (`MCTDataset`, `MCTConceptDB`, etc.) can often be passed by object or resolved by name. - See [Project Groups](project_group_admin.md) for the UI workflow these client diff --git a/medcat-trainer/docs/django_admin.md b/medcat-trainer/docs/django_admin.md index 1c22e0f36..aebed87e0 100644 --- a/medcat-trainer/docs/django_admin.md +++ b/medcat-trainer/docs/django_admin.md @@ -1,9 +1,13 @@ # 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`). +management that are not available from the cog icon +([Project Administration](project_admin.md), `/project-admin`). -These include: +Use it to edit an existing **project group** and push those settings onto its +projects, to attach projects that were created separately, to set user +passwords, and for the actions below. Creating a project or a new project +group is done from the cog icon. diff --git a/medcat-trainer/docs/index.md b/medcat-trainer/docs/index.md index 960e83d4f..04f11ce06 100644 --- a/medcat-trainer/docs/index.md +++ b/medcat-trainer/docs/index.md @@ -29,7 +29,7 @@ review-only workflows (collect annotations without changing the model). 1. Install and configure MedCATtrainer. 2. Create users and upload model artifacts (Model Pack or CDB/Vocab). [Administrator Setup](admin_setup.md) -3. Create a project and assign annotators. [Annotation Project Creation and Management](project_admin.md) +3. Open the cog icon and create a project or a project group, then assign annotators. [Project Administration](project_admin.md) 4. Annotate and submit documents. [Annotator Guide](annotator_guide.md) 5. Export annotations and evaluate with the metrics tools. @@ -37,7 +37,7 @@ review-only workflows (collect annotations without changing the model). - [Installation](installation.md) - [Administrator Setup](admin_setup.md) -- [Annotation Project Creation and Management](project_admin.md) +- [Project Administration](project_admin.md) - [Project Groups](project_group_admin.md) - [Django Admin](django_admin.md) - [Annotator Guide](annotator_guide.md) diff --git a/medcat-trainer/docs/project_admin.md b/medcat-trainer/docs/project_admin.md index 6d9bf3fa5..622f4f71e 100644 --- a/medcat-trainer/docs/project_admin.md +++ b/medcat-trainer/docs/project_admin.md @@ -1,22 +1,28 @@ -# Annotation Project Creation and Management +# Project Administration -An annotation project requires 4 elements: +The cog icon in the top-right of the header opens **Project Administration** +at `/project-admin`. Use it to set up the pieces an annotation campaign needs: +users, a dataset, a model, and then either one annotation project or a +project group. -| 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. | +Staff and superuser accounts see the cog. With username/password login that +is any user marked **Staff** or **Superuser**. With OIDC it is users who have +the `medcattrainer_superuser` realm role. Annotators do not see the icon and +are sent back to the home page if they open `/project-admin` directly. -MedCATtrainer supports two management surfaces to create, update, delete these elements. +Django Admin (`/admin`) is still used for low-level actions that this screen +does not cover. See [Django Admin](django_admin.md). -- **Project Admin UI** (`/project-admin`) for most project operations. -- **Django Admin** (`/admin`) for advanced actions and low-level data management. +## Screen layout -The following user guide covers. `/project-admin` +The page has four tabs: -## Project Administration +| Tab | Use it to | +| --- | --- | +| **Projects** | Create and edit annotation projects, and create project groups. | +| **Model Packs** | Upload a MedCAT model pack, or register a legacy Concept DB and vocabulary pair. | +| **Datasets** | Upload the documents that projects annotate. | +| **Users** | Add annotators and administrators. | 1. Open `/project-admin`. 2. Go to the **Projects** tab and select **+ Create New Project**. To create several annotator projects that share one configuration, switch the create form to **Project Group** instead — see [Project Groups](project_group_admin.md). @@ -24,101 +30,266 @@ The following user guide covers. `/project-admin` 4. Complete the forms for your project. Specifics of each field are discussed below. 5. Save. -### Basic Settings +A practical order for a new deployment: -| 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. | +1. Add users. +2. Upload a dataset. +3. Upload a model pack. +4. Create a project, or a project group. + +## Projects + +The **Projects** tab lists annotation projects you belong to, and projects in +groups you administer. It does not list every project on the server. Saving +a new project adds you as a member, so projects you create appear here +afterwards. + +Each row shows the title, description, status, mode, dataset, and created and +modified dates. Description is hidden on narrower windows. The list is sorted +by last modified, newest first. Click a column heading to sort by title, +created date, or modified date. Filter the title box, or use the **Status** +and **Mode** dropdowns. **Clear filters** appears when nothing matches. + +| Mode badge | Meaning | +| --- | --- | +| **Annotate** | **Require Entity Validation** is on. Model suggestions must be reviewed before submit. | +| **Validate** | **Require Entity Validation** is off. Suggestions are not held for review. | + +| Status badge | Meaning | +| --- | --- | +| **Annotating** | Collection is in progress. | +| **Complete** | Collection has finished. | +| **Discontinued** | The project was stopped. | + +Click a row to edit that project. The row actions are: + +| Action | Effect | +| --- | --- | +| **Clone** | Copies the project configuration, members, concept search filter, meta tasks, and relations under a new name. Annotations are not copied. The suggested name is ` (Clone)`. | +| **Reset** | Deletes every annotation on the project and clears its validated and prepared documents. Settings, dataset, and model stay as they are. | +| **Delete** | Deletes the project. This cannot be undone. | + +An empty list offers **Create Your First Project** and **Create a Project +Group**. + +### Create a project + +1. Open the cog icon, stay on **Projects**, and click **Create**. +2. Leave the switch on **Project**. +3. Fill in the form. Required fields are marked with `*`. +4. Click **Save Project**. + +The same form is used to edit an existing project. Click **Back** to return +to the list without saving. + +### Create a project group + +A project group stores one shared configuration and, by default, creates one +annotation project per annotator. Use a group for double annotation, +agreement metrics, or adjudication, where each annotator should see the same +dataset and the same settings. + +1. Open the cog icon and click **Create** (or **Create a Project Group** on an empty list). +2. Switch the form to **Project Group**. +3. Leave **Create an annotation project for each annotator** checked unless you only want the group record. +4. Fill in the shared settings. Select at least one annotator when the checkbox above is on. +5. Click **Save Project Group**. + +The banner on the group form reads: shared settings across annotators, used +for agreement metrics and adjudication. + +With the checkbox on, MedCATtrainer creates one project per selected +annotator: + +- Name: ` - ` +- Members: every selected administrator, the annotator for that project, and you +- Settings: the dataset, model, filters, tasks, and annotation options from the form + +You are added as a group administrator even if you did not select yourself. +Generated projects show up as normal rows on this tab and on the home +**Projects** list. The group itself is opened from the home **Project +Groups** tab. See [Project Groups](project_group_admin.md). + +Uncheck **Create an annotation project for each annotator** to save the group +without creating projects. The settings are still stored on the group. Attach +existing projects to it later from Django admin. The checkbox only applies +when the group is first saved. This screen does not edit a group after that. +To change the shared template, or to push those changes down into the child +projects, use Django admin (`/admin` -> **Project groups**). Editing one +generated project here changes only that project. + +For an agreement study, turn **Train Model on Submit** off so each annotator +reviews the same model output. + +The same setup can be scripted with `mctclient`. See +[Python Client](client.md). + +## Project and group form + +Projects and project groups share the sections below. The members section +changes when **Project Group** is selected. + +### Basic Information + +| Field | Description | +| --- | --- | +| **Project Name** * | Name shown in project lists. Must be unique. For a group, this is the group name; each generated project appends the annotator username. | +| **Dataset** * | Documents to annotate. Upload one on the **Datasets** tab if the list is empty. | +| **Description** | Short note on what is being collected and why. | +| **Annotation Guideline Link** | Optional URL, for example a Google Doc or SharePoint page, shown to annotators. | +| **Use Default Guideline** | Fills the link with the built-in example guideline and locks the URL field. Clear the box to enter your own link. | ### Project Settings -| Field | Description | -|------------------------------|-----------------------------------------------------------------------------| -| **Project Status** | Sets the current lifecycle stage of the project. Options are:
**Annotating** – Active annotation is ongoing;
**Complete** – Annotation is finished; further changes are prevented.
**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
**Unchecked**: Annotations are specific to this specific project and should not be used for further model training or fine-tuning | +| Field | Description | +| --- | --- | +| **Project Status** | **Annotating** (default), **Complete**, or **Discontinued (Fail)**. | +| **Project Locked** | Marks collection as finished. Leave unchecked while annotators are still working. | +| **Annotation Classification** | Checked when the labels are suitable for a general-purpose model. Leave unchecked when the labels are local to this clinical area or use case. If in doubt, leave it unchecked. | + +### Model Configuration -### Model Configuration Settings -Available MedCAT models are shown here. If this is empty, first [add a local model pack](#model-pack-administration). +Pick one model source: -Pick one of: -1. **Local Model Pack** (recommended), or -2. **Use Concept DB + Vocabulary** pair. is a legacy MedCAT v1 option. +1. **Local Model Pack** (recommended). Upload the pack on the **Model Packs** tab first. +2. **Use Concept DB / Vocabulary pair**, for a legacy MedCAT v1 concept database and vocabulary. +3. **Use remote MedCAT service API**, and enter **Remote Model Service URL** (for example `http://medcat-service:8000`). -- **Remote model service** (`use_model_service`) can be used where model inference is available at a remote url. - `model_service_url`. +A project must have a model pack, or both a Concept DB and a vocabulary, +unless it uses a remote service. A model pack and a Concept DB / vocabulary +pair cannot be set together. Choosing a remote service turns off the local +model pack selector. !!! 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 apply train-on-submit updates. + Interim training needs a local model pack. + +Choosing a model pack that includes MetaCAT models pre-selects the meta +annotation tasks linked to those models. ### 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. | -### Meta Annotation & Relation Tasks -| Field | Description | -|------------------------------|-----------------------------------------------------------------------------| -| **Meta Annotation Tasks** | Multi-select of Meta Tasks (for example Temporality, Assertion, Experiencer) shown in the annotator sidebar for Correct/Alternative concepts. Define task values in Django admin (`/admin`) first, or upload a model pack that includes MetaCAT models. Selecting a model pack with linked MetaCAT models pre-fills matching tasks. | -| **Relation Tasks** | Multi-select of relation types available between annotated concepts in the Relation tab. | +| Field | Default | Description | +| --- | --- | --- | +| **Require Entity Validation** | On | Suggestions start unvalidated and must be marked before the document can be submitted. This is the **Annotate** mode in the project list. | +| **Train Model on Submit** | On | Each submission incrementally trains the local model. Has no effect on a remote model service. Turn this off for agreement studies. | +| **Add New Entities** | Off | Lets annotators create concepts that are not already in the concept database. Leave off unless the database is known to be missing terms you intend to add. | +| **Restrict Concept Lookup** | Off | Limits concept search to the CUI filter below. Has no effect when that filter is empty. | +| **Terminate Available** | On | Shows **Terminate** in the annotation toolbar. | +| **Irrelevant Available** | Off | Shows **Irrelevant** in the annotation toolbar. | +| **Enable Entity Annotation Comments** | Off | Shows a free-text comment on each annotation. | ### 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. | +Limit the concepts annotators can use by building a CUI list. +- Select a model pack, or a Concept DB via the legacy option, then search with the concept picker. Each pick is added as a pill. +- **Paste CUIs (optional)** accepts identifiers separated by commas, semicolons, or new lines. -## Model Pack Administration -Manage the available local MedCAT models that can be configured into annotation projects +An empty filter means every concept in the model is available. **Restrict +Concept Lookup** only searches within this list. -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. +Saving a project or group sets the concept-lookup database to the Concept DB +inside the selected model pack, or to the Concept DB chosen in the legacy +pair. + +### Meta Annotation & Relation Tasks -To delete a model pack, use the action button. +| Field | Description | +| --- | --- | +| **Meta Annotation Tasks** | Tasks such as Temporality or Experiencer, shown in the annotator sidebar for Correct and Alternative concepts. Hold Ctrl (Cmd on macOS) to select more than one. | +| **Relation Tasks** | Relation types that can be marked between annotated concepts. | -!!! 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 +If both lists are empty, create the tasks in Django admin (`/admin`, under +**Meta tasks** and **Relations**), or upload a model pack that already links +MetaCAT models. Task values are defined in Django admin. See +[Meta Annotations](meta_annotations.md). +### Members -## Dataset Administration -Manage the availalbe datasets that can be configured into annotation projects. +For a single project, **Project Members** are the users who can open it. +Hold Ctrl (Cmd on macOS) to select more than one. You are added if you are +not already in the list. -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. +For a project group the section is **Group Members**: + +| Field | Description | +| --- | --- | +| **Administrators** | Users who can see and manage every project in the group. You are added automatically. | +| **Annotators** * | Required while **Create an annotation project for each annotator** is checked. One project is created for each username selected here. | + +## Concept lookup index (Solr import) + +Concept search in the annotator sidebar reads a Solr index of the project's +concept database. Saving a project or project group checks that index. If it +is missing, MedCATtrainer starts an import in the background and shows +"Started importing concepts for the selected model." Large databases take a +few minutes. The home project list then shows whether concepts are imported. -Upload CSV or XLSX with at least: +If the sidebar never shows concept details, the import has not finished or +did not start. You can run it yourself from Django admin. See +[Concept lookup index (Solr import)](django_admin.md#concept-lookup-index-solr-import). + +## Model Packs + +1. Open the **Model Packs** tab. +2. Click **Add Model Pack**, or click a row to edit one. +3. Enter a name and choose a `.zip` model pack. +4. Click **Save Model Pack**. + +**Legacy model upload (CBD & Vocab)** switches the form to an existing +Concept DB and vocabulary instead of a zip file. Both are required in that +mode. Those files themselves are uploaded from Django admin, not from this +tab. + +The trash icon deletes a model pack. Projects that were using it no longer +have a model and need another one before annotation can continue. + +## Datasets + +1. Open the **Datasets** tab. +2. Click **Add Dataset**, or click a row to edit the name and description or to replace the file. +3. Click **Save Dataset**. + +The file is `.csv` or `.xlsx` and must include: | name | text | -|---|---| +| --- | --- | | unique-doc-id | document text to annotate | -`name` should be unique per dataset. +`name` is the document id and must be unique inside the dataset. `text` is +the text annotators see. Any other columns are ignored. + +Example: + +```csv +name,text +doc001,"This is the first document to annotate." +doc002,"This is the second document with medical text." +``` + +The file is required when the dataset is created. The trash icon deletes the +dataset and its file. + +## Users + +1. Open the **Users** tab. +2. Click **Add User**, or click a row to edit username, email, and flags. +3. Click **Save User**. -## Project list operations +| Field | Description | +| --- | --- | +| **Username** * | Sign-in name. | +| **Email** | Optional. | +| **Password** | Shown when adding a user. It is not saved from this screen. Set the password in Django admin (`/admin` -> **Users**) or with the password-reset flow before the person signs in. | +| **Staff** | Lets the user open this screen from the cog icon. | +| **Superuser (Admin)** | Full platform access, including Django admin. | -From the home **Projects** table: +Annotators only need a username and a password set in Django admin. Leave +**Staff** and **Superuser (Admin)** off for them. This tab does not delete +users. +## Where to go next - Open and annotate a project. - Run document preparation in the background. The same run is available from the API (`POST /api/run-model/`) and the Python client (`session.run_model`) @@ -126,6 +297,9 @@ From the home **Projects** table: - View model-loaded state and clear model cache. - Save current model state. - Select compatible projects and submit a metrics report. +- Annotate from the home **Projects** list. See [Annotator Guide](annotator_guide.md). +- Open a group from the home **Project Groups** tab. See [Project Groups](project_group_admin.md). +- Export annotations, import concepts by hand, and edit a group after creation in [Django Admin](django_admin.md). ## Metrics reports diff --git a/medcat-trainer/docs/project_group_admin.md b/medcat-trainer/docs/project_group_admin.md index 775a2b817..9005a00fa 100644 --- a/medcat-trainer/docs/project_group_admin.md +++ b/medcat-trainer/docs/project_group_admin.md @@ -1,19 +1,24 @@ # Annotation Project Groups -Project Groups help coordinate multi-annotator projects at scale. +A project group is one shared annotation setup applied across several +projects, usually one project per annotator. Groups are how MedCATtrainer +runs double annotation, agreement metrics, and adjudication without cloning +and re-permissioning a template by hand. -They allow admins to define shared configuration once and apply it across a set -of associated annotation projects. +Create a group from the cog icon. See +[Create a project group](project_admin.md#create-a-project-group) for the +form fields. This page covers what that save does, and how admins use the +group afterwards. -## When to use Project Groups +## When to use a group Use a group when you need: -- one project per annotator over the same dataset/configuration, -- centralized settings management for those projects, or -- grouped visibility in the home screen. +- one project per annotator over the same dataset and model, +- one place that records that shared configuration, +- the projects listed together on the home screen. -## Creating a Project Group +A single project is enough when only one person is annotating. Prefer **Project Admin** (`/project-admin`) for day-to-day group creation. @@ -33,42 +38,67 @@ You can still create or edit groups in Django admin (`/admin` -> **Project group On save, MedCATtrainer automatically creates one `ProjectAnnotateEntities` per selected annotator. -Naming pattern: +Its members are the group's administrators, plus that annotator. The person +who saved the group is an administrator even if they were not selected. The +dataset, model, CUI filter, meta tasks, relations, and annotation options are +copied from the group form onto every generated project. -- ` - ` +For an agreement study, turn **Train Model on Submit** off on the group form +before saving, so each annotator reviews the same suggestions. -Administrators are added to each generated project, plus the corresponding -annotator. +## Saving a group without projects -### `create_associated_projects = false` +Clear **Create an annotation project for each annotator** to store the group +and its settings without creating projects. Do this when the projects already +exist and you only need to group them. -No child projects are created automatically. Use this if you already have -projects and want to group them manually. +Those existing projects are attached from Django admin +(`/admin` -> **Project annotate entities**), by setting each project's group. +The Project Administration screen does not assign an existing project to a +group. -## Updating a group +## Changing a group later -When associated projects exist and remain aligned, group-level edits propagate -to child project settings (for example CUI filters, model settings, tasks). +The cog screen creates a group. It does not open the group for editing. +Clicking a generated project there edits that one project only. -If child projects were manually added/removed outside the expected structure, -automatic propagation may fail and projects should then be edited individually. +To change the shared settings and copy them onto the child projects, edit the +group in Django admin (`/admin` -> **Project groups**) and save. Propagation +updates each child project's model, filters, tasks, and annotation options, +and renames each project to ` - `. -## Using groups in the UI +Propagation expects the child projects to still match the group's annotators. +If projects were added or removed by hand, save reports that the projects are +out of sync. Edit those projects individually, or recreate the set, instead +of relying on the group save. -Admins can switch between **Single Projects** and **Project Groups** from the -home page and inspect projects within each group. +## Using groups on the home page -Regular annotators typically work with individual projects and may not need the -group view. +Admins see **Projects** and **Project Groups** tabs on the home page. +Annotators only see their own projects. + +![Home page with the Project Groups control](_static/img/project-groups-view-available.png) + +**Project Groups** lists each group by name, description, and last modified +time. Last modified follows the most recently changed project in the group. +The list is built from projects you can see, so a group appears once it has +at least one of those projects. + +![Project groups list](_static/img/project-groups-view.png) + +Click a row to open the projects in that group. From there, open a project +to annotate, or use the same admin actions as on the main project list +(prepare documents, concept-import status, model cache, save model, metrics). + +## Good practice + +- Keep one group per annotator, with one shared dataset and model. +- Turn off **Train Model on Submit** when the goal is agreement between annotators. +- Leave generated names as ` - ` so reports stay easy to compare. +- Change shared settings on the group in Django admin, rather than editing each child project differently, while the projects are still in sync. ## Automating with the Python client `mctclient` can create and list project groups for provisioning scripts and CI. See [Python Client](client.md). -## Best practices - -- For inter-annotator agreement studies, disable `train_model_on_submit` in - all group projects. -- Keep naming conventions consistent for easy report comparison. -- Prefer one shared configuration template per annotation campaign.