=======================================
HistomicsUI |build-status| |codecov-io|
=======================================
Organize, visualize, and analyze histology images.
`HistomicsUI`_ organizes and manages whole slide image (WSI) files using Girder_. It has a dedicated interface to select WSI, add annotations manually, and to run analysis and algorithms on all or parts of images.
Girder provides authentication, access control, and diverse storage options, including using local file systems and Amazon S3. WSI images are read and displayed via the large_image_ module. Algorithms are containerized using Docker_ and are run using the slicer_cli_web_ Girder plugin. These can be run on multiple worker machines via `Girder Worker`_ and celery_.
A set of common algorithms are provided by HistomicsTK_.
License
-----------------------------------------------------------
HistomicsUI is made available under the Apache License, Version 2.0. For more details, see `LICENSE <https://github.com/DigitalSlideArchive/HistomicsUI/blob/master/LICENSE>`_
Community
-----------------------------------------------------------
`Discussions <https://github.com/DigitalSlideArchive/digital_slide_archive/discussions>`_ | `Issues <https://github.com/DigitalSlideArchive/HistomicsUI/issues>`_ | `Contact Us <https://www.kitware.com/contact-us/>`_
Installation
------------
Linux
=====
In linux with Python 3.8 or newer:
Prerequisites:
- MongoDB must be installed and running.
- An appropriate version of Python must be installed.
HistomicsUI uses large_image sources to read different image file formats. You need to install appropriate sources for the files that will be used.
.. code-block:: bash
# install all sources from the main repo
pip install large-image[sources] --find-links https://girder.github.io/large_image_wheels
or
.. code-block:: bash
# install openslide and tiff sources
pip install large-image-source-tiff large-image-source-openslide --find-links https://girder.github.io/large_image_wheels
Now install the histomicsui package, have Girder build its UI, and start the Girder server. Note that at Girder may still require an old version of node (14.x) to build correctly -- nvm can be used to manage multiple versions of node.
.. code-block:: bash
pip install histomicsui[analysis]
girder build
girder serve
To use Girder Worker:
.. code-block:: bash
pip install girder_slicer_cli_web[worker]
GW_DIRECT_PATHS=true girder-worker -l info -Ofair --prefetch-multiplier=1
Girder Worker needs the rabbitmq message service to be running to communicate with Girder. Both Girder and Girder Worker should be run as a user that is a member of the docker group.
The first time you start HistomicsUI, you'll also need to configure Girder with at least one user and one assetstore (see the Girder_ documentation). Additionally, it is recommended that you install the HistomicsTK_ algorithms. This can be done going to the Admin Console, Plugins, Slicer CLI Web settings. Set a default task upload folder, then import the ``dsarchive/histomicstk:latest`` docker image.
Reference Deployment
====================
The standard deployment of HistomicsUI is the `Digital Slide Archive`_. The associated repository has tools for readily installing via Docker, VirtualBox, or shell scripts on Ubuntu.
Development
===========
The most convenient way to develop on HistomicsUI is to use the `devops scripts from the Digital Slide Archive <https://github.com/DigitalSlideArchive/digital_slide_archive/tree/master/devops>`_.
If you are making changes to the HistomicsUI frontend, you can make Girder watch the source code and perform hot reloads on changes using the ``--watch-plugin`` argument to ``girder build``. See the `Girder docs <https://girder.readthedocs.io/en/stable/development.html#during-development>`_ for more information.
Annotations and Metadata from Jobs
----------------------------------
This handles ingesting annotations and metadata that are uploaded and associating them with existing large image items in the Girder database. These annotations and metadata re commonly generated through jobs, such as HistomicTK tasks, but can also be added manually.
If a file is uploaded to the Girder system that includes a ``reference`` record, and that ``reference`` record contains an ``identifier`` field and at least one of a ``fileId`` and an ``itemId`` field, specific identifiers can be used to ingest the results. If a ``userId`` is specified in the ``reference`` record, permissions for adding the annotation or metadata are associated with that user.
Metadata
========
Identifiers ending in ``ItemMetadata`` are loaded and then set as metadata on the associated item that contains the specified file. Conceptually, this is the same as calling the ``PUT`` ``item/{id}/metadata`` endpoint.
Annotations
===========
Identifiers ending in ``AnnotationFile`` are loaded as annotations, associated with the item that contains the specified file. Conceptually, this is the same as uploaded the file via the annotation endpoints for the item associated with the specified ``fileId`` or ``itemId``.
If the annotation file contains any annotations with elements that contain ``girderId`` values, the ``girderId`` values can be ``identifier`` values from files that were uploaded with a ``reference`` record that contains a matching ``uuid`` field. The ``uuid`` field is required for this, but is treated as an arbitrary string.
Funding
-------
This work was funded in part by the NIH grant U24-CA194362-01_.
.. _HistomicsUI: https://github.com/DigitalSlideArchive/HistomicsUI
.. _Docker: https://www.docker.com/
.. _Kitware: https://www.kitware.com/
.. _U24-CA194362-01: http://grantome.com/grant/NIH/U24-CA194362-01
.. _Girder: http://girder.readthedocs.io/en/latest/
.. _Girder Worker: https://girder-worker.readthedocs.io/en/latest/
.. _large_image: https://github.com/girder/large_image
.. _slicer_cli_web: https://github.com/girder/slicer_cli_web
.. _slicer execution model: https://www.slicer.org/slicerWiki/index.php/Slicer3:Execution_Model_Documentation
.. _celery: http://www.celeryproject.org/
.. _HistomicsTK: https://github.com/DigitalSlideArchive/HistomicsTK
.. _Digital Slide Archive: https://github.com/DigitalSlideArchive/digital_slide_archive
.. |build-status| image:: https://circleci.com/gh/DigitalSlideArchive/HistomicsUI.svg?style=svg
:target: https://circleci.com/gh/DigitalSlideArchive/HistomicsUI
:alt: Build Status
.. |codecov-io| image:: https://img.shields.io/codecov/c/github/DigitalSlideArchive/HistomicsUI.svg
:target: https://codecov.io/github/DigitalSlideArchive/HistomicsUI?branch=master
:alt: codecov.io
Raw data
{
"_id": null,
"home_page": "https://github.com/DigitalSlideArchive/histomicsui",
"name": "histomicsui",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "girder-plugin,histomicsui",
"author": "Kitware, Inc.",
"author_email": "kitware@kitware.com",
"download_url": "https://files.pythonhosted.org/packages/5b/21/bc1a3bdfc1fdf1070b6554a195b87ee79e946a60413fd3c603bd86b43558/histomicsui-1.5.0.tar.gz",
"platform": null,
"description": "=======================================\nHistomicsUI |build-status| |codecov-io|\n=======================================\n\nOrganize, visualize, and analyze histology images.\n\n`HistomicsUI`_ organizes and manages whole slide image (WSI) files using Girder_. It has a dedicated interface to select WSI, add annotations manually, and to run analysis and algorithms on all or parts of images.\n\nGirder provides authentication, access control, and diverse storage options, including using local file systems and Amazon S3. WSI images are read and displayed via the large_image_ module. Algorithms are containerized using Docker_ and are run using the slicer_cli_web_ Girder plugin. These can be run on multiple worker machines via `Girder Worker`_ and celery_.\n\nA set of common algorithms are provided by HistomicsTK_.\n\nLicense\n-----------------------------------------------------------\n\nHistomicsUI is made available under the Apache License, Version 2.0. For more details, see `LICENSE <https://github.com/DigitalSlideArchive/HistomicsUI/blob/master/LICENSE>`_\n\nCommunity\n-----------------------------------------------------------\n\n`Discussions <https://github.com/DigitalSlideArchive/digital_slide_archive/discussions>`_ | `Issues <https://github.com/DigitalSlideArchive/HistomicsUI/issues>`_ | `Contact Us <https://www.kitware.com/contact-us/>`_\n\nInstallation\n------------\n\nLinux\n=====\n\nIn linux with Python 3.8 or newer:\n\nPrerequisites:\n\n- MongoDB must be installed and running.\n- An appropriate version of Python must be installed.\n\nHistomicsUI uses large_image sources to read different image file formats. You need to install appropriate sources for the files that will be used.\n\n.. code-block:: bash\n\n # install all sources from the main repo\n pip install large-image[sources] --find-links https://girder.github.io/large_image_wheels\n\nor\n\n.. code-block:: bash\n\n # install openslide and tiff sources\n pip install large-image-source-tiff large-image-source-openslide --find-links https://girder.github.io/large_image_wheels\n\nNow install the histomicsui package, have Girder build its UI, and start the Girder server. Note that at Girder may still require an old version of node (14.x) to build correctly -- nvm can be used to manage multiple versions of node.\n\n.. code-block:: bash\n\n pip install histomicsui[analysis]\n girder build\n girder serve\n\nTo use Girder Worker:\n\n.. code-block:: bash\n\n pip install girder_slicer_cli_web[worker]\n GW_DIRECT_PATHS=true girder-worker -l info -Ofair --prefetch-multiplier=1\n\nGirder Worker needs the rabbitmq message service to be running to communicate with Girder. Both Girder and Girder Worker should be run as a user that is a member of the docker group.\n\nThe first time you start HistomicsUI, you'll also need to configure Girder with at least one user and one assetstore (see the Girder_ documentation). Additionally, it is recommended that you install the HistomicsTK_ algorithms. This can be done going to the Admin Console, Plugins, Slicer CLI Web settings. Set a default task upload folder, then import the ``dsarchive/histomicstk:latest`` docker image.\n\nReference Deployment\n====================\n\nThe standard deployment of HistomicsUI is the `Digital Slide Archive`_. The associated repository has tools for readily installing via Docker, VirtualBox, or shell scripts on Ubuntu.\n\nDevelopment\n===========\n\nThe most convenient way to develop on HistomicsUI is to use the `devops scripts from the Digital Slide Archive <https://github.com/DigitalSlideArchive/digital_slide_archive/tree/master/devops>`_.\n\nIf you are making changes to the HistomicsUI frontend, you can make Girder watch the source code and perform hot reloads on changes using the ``--watch-plugin`` argument to ``girder build``. See the `Girder docs <https://girder.readthedocs.io/en/stable/development.html#during-development>`_ for more information.\n\nAnnotations and Metadata from Jobs\n----------------------------------\n\nThis handles ingesting annotations and metadata that are uploaded and associating them with existing large image items in the Girder database. These annotations and metadata re commonly generated through jobs, such as HistomicTK tasks, but can also be added manually.\n\nIf a file is uploaded to the Girder system that includes a ``reference`` record, and that ``reference`` record contains an ``identifier`` field and at least one of a ``fileId`` and an ``itemId`` field, specific identifiers can be used to ingest the results. If a ``userId`` is specified in the ``reference`` record, permissions for adding the annotation or metadata are associated with that user.\n\nMetadata\n========\n\nIdentifiers ending in ``ItemMetadata`` are loaded and then set as metadata on the associated item that contains the specified file. Conceptually, this is the same as calling the ``PUT`` ``item/{id}/metadata`` endpoint.\n\nAnnotations\n===========\n\nIdentifiers ending in ``AnnotationFile`` are loaded as annotations, associated with the item that contains the specified file. Conceptually, this is the same as uploaded the file via the annotation endpoints for the item associated with the specified ``fileId`` or ``itemId``.\n\nIf the annotation file contains any annotations with elements that contain ``girderId`` values, the ``girderId`` values can be ``identifier`` values from files that were uploaded with a ``reference`` record that contains a matching ``uuid`` field. The ``uuid`` field is required for this, but is treated as an arbitrary string.\n\n\nFunding\n-------\nThis work was funded in part by the NIH grant U24-CA194362-01_.\n\n.. _HistomicsUI: https://github.com/DigitalSlideArchive/HistomicsUI\n.. _Docker: https://www.docker.com/\n.. _Kitware: https://www.kitware.com/\n.. _U24-CA194362-01: http://grantome.com/grant/NIH/U24-CA194362-01\n\n.. _Girder: http://girder.readthedocs.io/en/latest/\n.. _Girder Worker: https://girder-worker.readthedocs.io/en/latest/\n.. _large_image: https://github.com/girder/large_image\n.. _slicer_cli_web: https://github.com/girder/slicer_cli_web\n.. _slicer execution model: https://www.slicer.org/slicerWiki/index.php/Slicer3:Execution_Model_Documentation\n.. _celery: http://www.celeryproject.org/\n.. _HistomicsTK: https://github.com/DigitalSlideArchive/HistomicsTK\n.. _Digital Slide Archive: https://github.com/DigitalSlideArchive/digital_slide_archive\n\n.. |build-status| image:: https://circleci.com/gh/DigitalSlideArchive/HistomicsUI.svg?style=svg\n :target: https://circleci.com/gh/DigitalSlideArchive/HistomicsUI\n :alt: Build Status\n\n.. |codecov-io| image:: https://img.shields.io/codecov/c/github/DigitalSlideArchive/HistomicsUI.svg\n :target: https://codecov.io/github/DigitalSlideArchive/HistomicsUI?branch=master\n :alt: codecov.io\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Organize, visualize, and analyze histology images.",
"version": "1.5.0",
"project_urls": {
"Homepage": "https://github.com/DigitalSlideArchive/histomicsui"
},
"split_keywords": [
"girder-plugin",
"histomicsui"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bc3fd72dba896fd046d720b8bfe56f9af98bea1e8fe251d57d727c5b1b52106b",
"md5": "2785e8d2526bbc85fc0548cf0f60745a",
"sha256": "290256e177d80354093069d411b27274264997b1795b07cc630d61796cf8548c"
},
"downloads": -1,
"filename": "histomicsui-1.5.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "2785e8d2526bbc85fc0548cf0f60745a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 214554,
"upload_time": "2024-02-01T21:16:32",
"upload_time_iso_8601": "2024-02-01T21:16:32.116579Z",
"url": "https://files.pythonhosted.org/packages/bc/3f/d72dba896fd046d720b8bfe56f9af98bea1e8fe251d57d727c5b1b52106b/histomicsui-1.5.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5b21bc1a3bdfc1fdf1070b6554a195b87ee79e946a60413fd3c603bd86b43558",
"md5": "2b8522a216cb94a6121d5bd293f81cff",
"sha256": "382ff54b3e88981c97a06961c8f15140ddc02d59db272be4ea82f4b15b442f78"
},
"downloads": -1,
"filename": "histomicsui-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "2b8522a216cb94a6121d5bd293f81cff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 711213,
"upload_time": "2024-02-01T21:16:35",
"upload_time_iso_8601": "2024-02-01T21:16:35.501993Z",
"url": "https://files.pythonhosted.org/packages/5b/21/bc1a3bdfc1fdf1070b6554a195b87ee79e946a60413fd3c603bd86b43558/histomicsui-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-01 21:16:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DigitalSlideArchive",
"github_project": "histomicsui",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"tox": true,
"lcname": "histomicsui"
}
JSON
