{"id":28514414,"url":"https://github.com/digitalslidearchive/histomics-label","last_synced_at":"2025-07-04T11:31:01.188Z","repository":{"id":80497382,"uuid":"563088547","full_name":"DigitalSlideArchive/histomics-label","owner":"DigitalSlideArchive","description":"A user-interface used in conjunction with HistomicsUI to facilitate active learning on whole slide images","archived":false,"fork":false,"pushed_at":"2025-06-19T17:39:59.000Z","size":18145,"stargazers_count":3,"open_issues_count":18,"forks_count":7,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-06-19T18:44:25.010Z","etag":null,"topics":["bioimage-informatics","digital-slide-archive","guided-labeling","histology","python","whole-slide-annotation","whole-slide-images"],"latest_commit_sha":null,"homepage":"","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DigitalSlideArchive.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-11-07T22:03:26.000Z","updated_at":"2025-06-19T17:40:02.000Z","dependencies_parsed_at":"2024-03-18T14:50:08.624Z","dependency_job_id":"8c5b331c-87bf-4a14-a0e7-5251e7611734","html_url":"https://github.com/DigitalSlideArchive/histomics-label","commit_stats":null,"previous_names":["digitalslidearchive/histomics-label","digitalslidearchive/wsi-superpixel-guided-labeling"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DigitalSlideArchive/histomics-label","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalSlideArchive%2Fhistomics-label","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalSlideArchive%2Fhistomics-label/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalSlideArchive%2Fhistomics-label/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalSlideArchive%2Fhistomics-label/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DigitalSlideArchive","download_url":"https://codeload.github.com/DigitalSlideArchive/histomics-label/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalSlideArchive%2Fhistomics-label/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263501497,"owners_count":23476439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioimage-informatics","digital-slide-archive","guided-labeling","histology","python","whole-slide-annotation","whole-slide-images"],"created_at":"2025-06-09T01:36:37.766Z","updated_at":"2025-07-04T11:31:01.171Z","avatar_url":"https://github.com/DigitalSlideArchive.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"==============================\nHistomics Label\n==============================\n\nHistomics Label is a `Girder 3 \u003chttps://github.com/girder\u003e`_ plugin designed to be used in conjunction with `HistomicsUI \u003chttps://github.com/DigitalSlideArchive/HistomicsUI\u003e`_ and `HistomicsTK \u003chttps://github.com/DigitalSlideArchive/HistomicsTK\u003e`_ to facilitate active learning on whole slide images.\n\nThis plugin leverages the output of certain HistomicsTK/SlicerCLI jobs to allow end users to label superpixel regions of whole slide images to be used as input for machine learning algorithms.\n\nAn example algorithm is contained within the ``dsarchive/superpixel:latest`` docker image. This can be used to generate superpixels, features, and machine learning models for active learning on a directory of images. See the installation instructions below for how to include the image as part of your Digital Slide Archive deployment.\n\nOnce the appropriate data is generated, a new view becomes available for labeling and retraining.\n\nInstallation\n------------\n\nThe recommended way to use this plugin is by adding it to the `Digital Slide Archive's \u003chttps://github.com/DigitalSlideArchive/digital_slide_archive\u003e`_ ``docker-compose`` deployment. First, check out both this repository and ``digital_slide_archive`` from Github, if you do not yet have a running instance of the Digital Slide Archive.\n\nIf you don't already use a provisioning yaml file as part of your DSA deployment, you'll want to create one, e.g. ``provision.local.yaml``. Make sure this file contains the following: ::\n\n    pip:\n        - /opt/histomics-label\n    rebuild-client: True\n    resources:\n        - model: collection\n          name: Tasks\n          creator: resource:admin\n          public: True\n        - model: folder\n          parent: resource:collection/Tasks\n          parentType: collection\n          name: \"Slicer CLI Web Tasks\"\n          creator: resource:admin\n          public: True\n        - model: collection\n          name: \"Active Learning\"\n          creator: resource:admin\n          public: True\n        - model: folder\n          parent: \"resource:collection/Active Learning\"\n          parentType: collection\n          name: Data\n          creator: resource:admin\n          public: True\n          metadata: {'active_learning': \"true\"}\n          metadata_update: True\n        - model: folder\n          parent: \"resource:collection/Active Learning/Data\"\n          parentType: folder\n          name: Annotations\n          creator: resource:admin\n          public: True\n        - model: folder\n          parent: \"resource:collection/Active Learning/Data\"\n          parentType: folder\n          name: Models\n          creator: resource:admin\n          public: True\n        - model: folder\n          parent: \"resource:collection/Active Learning/Data\"\n          parentType: folder\n          name: Features\n          creator: resource:admin\n          public: True\n    slicer-cli-image-pull:\n        - dsarchive/histomicstk:latest\n        - dsarchive/superpixel:latest\n\nIn ``digital_slide_archive/devops/dsa/``, you'll want to add or modify ``docker-compose.override.yaml`` in the following manner: ::\n\n    ---\n    version: '3'\n    services:\n        girder:\n            volumes:\n                - ./provision.local.yaml:/opt/digital_slide_archive/devops/dsa/provision.yaml\n                - \u003cpath\u003e/\u003cto\u003e/histomics-label:/opt/histomics-label\n\nWhere ``\u003cpath\u003e/\u003cto\u003e/histomics-label`` is the path to this directory. These changes mount the source code for this plugin to the docker container so the plugin can be built. It also ensures the provisioning yaml will be used to install the plugin and perform some initial setup.\n\nIn the same directory, run ``DSA_USER=$(id -u):$(id -g) docker compose up``. (If that and ``docker compose version`` fail you may first need to invoke ``sudo apt install docker-compose-plugin``.) Once the deployment is stood up, you can verify that everything has been provisioned correctly by visiting ``localhost:8080``.\n\nTo verify, login as the provisioned admin user and check that the \"Histomics Label\" plugin is installed by navigating to the Admin console from the sidebar and clicking \"Plugins.\" Additionally there should be a collection called \"Active Learning\", which should contain one folder called \"Data\", which in turn should contain folders \"Annotations,\" \"Features,\" and \"Models.\"\n\nUsing the Plugin\n----------------\n\nAfter following the installation instructions, you should have a folder called **Data** in a collection called **Active Learning**, which looks like the following:\n\n.. image:: docs/screenshots/active_learning_folder.png\n   :alt: Active Learning/Data folder after provision\n\nTo enable launching the Active Learning UI from a folder, you'll need to set metadata on the folder. You can do this from here by clicking the blue plus button in the metadata header, selected ``Simple``, and adding the following metadata property. If you used the recommended provisioning values, this will have already been done.\n\n.. image:: docs/screenshots/active_learning_metadata.png\n   :alt: Metadata to add. Key: active_learning, Value: true\n\nAlternatively, you can set the ``activeLearning`` key to ``true`` in the ``.histomicsui_config.yaml`` file for the folder.\n\n.. code-block:: yaml\n\n   activeLearning: true\n\nUpload the whole slide images you'd like to use for active learning to this folder, using the green upload button. Once your images have been uploaded, the ``Active Learning`` button should appear in the top right. If not, try refreshing the page. Click the ``Active Learning`` button to begin generating features and models for active learning.\n\n.. image:: docs/screenshots/active_learning_button.png\n    :alt: Button to launch the Active Learning workflow\n\nThe first step is to generate the superpixels and feature vectors. Using the form, you can control the approximate size of the superpixels generated (default is 100 pixels), and the magnification level at which to generate the superpixels (default is 5). You can also set the ``certainty metric`` (the default is ``confidence``) and the ``feature shape`` (the default is ``image``). Once you have chosen values for these fields, click the ``Generate Superpixels`` button. This will start a background process which can be monitored from the Girder Admin Console. This job could take some time to finish, and will take longer the more images you have in your folder. If you remain on the page, you will be taken to the next step automatically and as superpixels become available for each image you can begin labeling while the job completes.\n\n.. image:: docs/screenshots/superpixel_generation.png\n    :alt: The form for superpixel generation\n\nIn the initial labeling step, you will be able to create a set of categories for the superpixels, and label superpixels across your dataset to begin training the active learning models.\n\n.. image:: docs/screenshots/initial_labels.png\n    :alt: The initial label user interface\n\nThis view allows users to create new categories, set category colors, rename categories, and delete and/or merge categories. You can then use those categories to label superpixels by interacting with the image viewer. The ``Image`` drop down menu allows switching the current image shown in the image viewer. Clicking on a superpixel in the image viewer will label that superpixel with the currently displayed category. Clicking again on that superpixel will remove the label. Select the crosshairs on the labeling dialog to enable painting mode where you can continuously label or unlabel superpixels. A running total of superpixels labeled per category is available to the right of the image viewer.\n\nClicking on ``Begin Training`` will kick off a background process to begin training the active learning model using the labels provided in this step. Once that task is completed, you will be presented with a new view containing predictions as described below.\n\n.. image:: docs/screenshots/active_learning_view.png\n    :alt: The active learning view\n\nFrom here, you can label superpixel features using the film strip area at the bottom to retrain the model. Each block of the film strip depicts one superpixel. The bar at the top of each block shows the most recent prediction. The superpixels shown are sorted so that users are shown the least confident predictions first. Users can add a label by either selecting a category that matches or differs from the prediction. Either the drop down menu can be used or you can use the hotkey assigned to the category. This hotkey value can also be changed in the labeling dialog.\n\nIn order to clear all user inputs on this screen , a ``Reset All`` button is provided. If the predictions for all of the visible blocks matches the actual class of the regions shown, there is an ``Agree to All`` button. You can also view a color-coded pixelmap of the current batch of predictions by clicking the ``Show/hide Predictions`` button.\n\nAfter labeling some superpixels, a retrain can be triggered with the ``Retrain`` button. This will kick off a job to generate a new batch of predictions, using the newly created labels as input. This job should not take as long as the first, since superpixel and feature generation only needs to be performed once. While that job is running, interactions with this view are disabled. Once the job is finished, new superpixels will be shown to the user for labeling.\n\nYou can review trained or predicted superpixels via the review mode. This allows grouping by label, filtering, comparisons, and checking on another user's labeling choices.\n\n.. image:: docs/screenshots/reviewmode.png\n    :alt: The review mode\n\nFeatures\n--------\n\n* Adds a new view which can be accessed from the Girder 3 UI for folders that are configured for this workflow\n\nUpdating CLI Images\n-------------------\n\nThe Superpixel CLI Docker image that is used for computing superpixels, extracting features, training models, and predicting labels can be updated without updating the whole system.  This can be done by selecting ``Collections`` -\u003e ``Tasks`` -\u003e ``Slicer CLI Web Tasks`` -\u003e ``dsarchive/superpixel`` -\u003e ``latest`` and then clicking on the ``Pull Latest`` button near the upper right.\n\nIn the provisioning yaml file, if ``slicer-cli-image-pull`` is used rather than ``slicer-cli-image``, this will also ensure the latest version of the docker image is available when the system is restarted with docker compose.\n\n\nAcknowledgements\n----------------\n\nThis work has been funded in part by National Library of Medicine grant 5R01LM013523 entitled \"Guiding humans to create better labeled datasets for machine learning in biomedical research\".\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalslidearchive%2Fhistomics-label","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalslidearchive%2Fhistomics-label","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalslidearchive%2Fhistomics-label/lists"}