deepd3


Namedeepd3 JSON
Version 0.1 PyPI version JSON
download
home_page
SummaryA tool for segmenting dendrites and dendritic spines.
upload_time2023-01-30 21:51:39
maintainer
docs_urlNone
authorAndreas M Kist
requires_python
licenseGPLv3
keywords spine segmentation
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            [![DeepD3 project website](https://img.shields.io/website-up-down-green-red/https/naereen.github.io.svg)](https://deepd3.forschung.fau.de/)

# DeepD3

We provide DeepD3, a framework for the **d**etection of **d**endritic spines and **d**endrites.

With DeepD3, you are able to

* train a deep neural network for dendritic spine and dendrite segmentation
* use pre-trained DeepD3 networks for inference
* build 2D and 3D ROIs
* export results to your favourite biomedical image analysis platform
* use command-line or graphical user interfaces

## How to install and run DeepD3

DeepD3 is written in Python. First, please download and install any Python-containing distribution, such as [Anaconda](https://www.anaconda.com/products/distribution). We recommend Python 3.7 and more recent version.

Then, installing DeepD3 is as easy as follows:

    pip install deepd3

Now, you have access to almost all the DeepD3 functionalities.

If you want to use the DeepD3 Neural Network inference mode, please install **Tensorflow** using either of the following commands:

    # With CPU support only
    conda install tensorflow

    # With additional GPU support
    conda install tensorflow-gpu

If you would like to access DeepD3-GUIs, use the following two shortcuts in your favourite shell:

    # Opening the segmentation and ROI building GUI
    deepd3-inference

    # Opening the training utilities
    deepd3-training

## Model zoo

We provide a comprehensive training dataset on zenodo and the [DeepD3 Website](https://deepd3.forschung.fau.de/):

* [DeepD3_8F.h5](https://deepd3.forschung.fau.de/models/DeepD3_8F.h5) - 8 base filters, original resolution
* [DeepD3_16F.h5](https://deepd3.forschung.fau.de/models/DeepD3_16F.h5) - 16 base filters, original resolution
* [DeepD3_32F.h5](https://deepd3.forschung.fau.de/models/DeepD3_32F.h5) - 32 base filters, original resolution
* [DeepD3_8F_94nm.h5](https://deepd3.forschung.fau.de/models/DeepD3_8F_94nm.h5) - 8 base filters, resized to 94 nm xy resolution
* [DeepD3_16F_94nm.h5](https://deepd3.forschung.fau.de/models/DeepD3_16F_94nm.h5) - 16 base filters, resized to 94 nm xy resolution
* [DeepD3_32F_94nm.h5](https://deepd3.forschung.fau.de/models/DeepD3_32F_94nm.h5) - 32 base filters, resized to 94 nm xy resolution

Brief description:

* Full (32F) DeepD3 model trained on 94 nm (fixed) or a blend of resolutions (free)
* Medium (16F) DeepD3 model trained on 94 nm (fixed) or a blend of resolutions (free)
* Tiny (8F) DeepD3 mode trained on 94 nm (fixed) or a blend of resolutions (free)


## Workflow

### Train DeepD3 on your own dataset

Use `deepd3-training` to start the GUI for generating training sets. 

For each of your training set, please provide

* The original stack as e.g. TIF files
* The spine annotations (binary labels) as TIF or MASK files (the latter from [pipra](https://github.com/anki-xyz/pipra))
* The dendrite annotations as SWC file (only tested for SWC-files generated by [NeuTube](https://neutracing.com/download/))

### Create training data

Click on the button "Create training data". For each of your stacks, import the stack, the spine annotation and the dendrite annotation file.
If you dendrite annotation is a SWC file, it will create a 3D reconstruction of the SWC file, which will be stored for later use. If you reload the SWC, it will ask you if you want to keep the 3D reconstruction.

After importing all files, enter the metadata (resolution in x, y and z) and determine the region of interest using the bounding box and the sliders.
Shortcuts are `B` for current plane is **z begin** and `E` for **z end**. You may enable or disable the cropping to the bounding box. If you are happy, save this region as `d3data`-file.

### View training data

Click on the button "View training data" to re-visit any `d3data` files. You also are able to see and potentially manipulate the metadata associated the `d3data` file.

### Arrange training data

For training, you need to create a `d3set`. This is an assembly of `d3data` files. Click on the button "Arrange training data". Then, simply load all relevant data using the "Add data to set" button and select appropriate `d3data` files. Clicking on "Create dataset" allows you to save your assembly as `d3set` file.

### Actual training

We have prepared a Jupyter notebook in the folder `examples`. Follow the instructions to train your own deep neural network for DeepD3 use.
For professionals, you also may utilize directly the files in `model` and `training` to allow highly individualized training.
You only should ensure that your model allows arbitrary input and outputs two separate channels (dendrites and spines).

### Inference

Open the inference mode using `deepd3-inference`. Load your stack of choice (we currently support TIF stacks) and specify the XY and Z dimensions. Next, you can segment dendrites and dendritic spines using a DeepD3 model from [the model zoo]() by clicking on `Analyze -> Segment dendrite and spines`. Afterwards, you may clean the predictions by clicking on `Analyze -> Cleaning`. Finally, you may build 2D or 3D ROIs using the respective functions in `Analyze`. To test the 3D ROI building, double click in the stack to a region of interest. A window opens that allows you to play with the hyperparameters and segments 3D ROIs in real-time.

All results can be exported to various file formats. For convenience, DeepD3 saves related data in its "proprietary" hdf5 file (that you can open using any hdf5 viewer/program/library). In particular, you may export the predictions as TIF files, the ROIs to ImageJ file format or a folder, the ROI map to a TIF file, or the ROI centroids to a file. 

Most functions can be assessed using a batch command script located in `deepd3/inference/batch.py`.


## How to cite

DeepD3 is available as preprint soon.

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "deepd3",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "spine segmentation",
    "author": "Andreas M Kist",
    "author_email": "andreas.kist@fau.de",
    "download_url": "",
    "platform": null,
    "description": "[![DeepD3 project website](https://img.shields.io/website-up-down-green-red/https/naereen.github.io.svg)](https://deepd3.forschung.fau.de/)\n\n# DeepD3\n\nWe provide DeepD3, a framework for the **d**etection of **d**endritic spines and **d**endrites.\n\nWith DeepD3, you are able to\n\n* train a deep neural network for dendritic spine and dendrite segmentation\n* use pre-trained DeepD3 networks for inference\n* build 2D and 3D ROIs\n* export results to your favourite biomedical image analysis platform\n* use command-line or graphical user interfaces\n\n## How to install and run DeepD3\n\nDeepD3 is written in Python. First, please download and install any Python-containing distribution, such as [Anaconda](https://www.anaconda.com/products/distribution). We recommend Python 3.7 and more recent version.\n\nThen, installing DeepD3 is as easy as follows:\n\n    pip install deepd3\n\nNow, you have access to almost all the DeepD3 functionalities.\n\nIf you want to use the DeepD3 Neural Network inference mode, please install **Tensorflow** using either of the following commands:\n\n    # With CPU support only\n    conda install tensorflow\n\n    # With additional GPU support\n    conda install tensorflow-gpu\n\nIf you would like to access DeepD3-GUIs, use the following two shortcuts in your favourite shell:\n\n    # Opening the segmentation and ROI building GUI\n    deepd3-inference\n\n    # Opening the training utilities\n    deepd3-training\n\n## Model zoo\n\nWe provide a comprehensive training dataset on zenodo and the [DeepD3 Website](https://deepd3.forschung.fau.de/):\n\n* [DeepD3_8F.h5](https://deepd3.forschung.fau.de/models/DeepD3_8F.h5) - 8 base filters, original resolution\n* [DeepD3_16F.h5](https://deepd3.forschung.fau.de/models/DeepD3_16F.h5) - 16 base filters, original resolution\n* [DeepD3_32F.h5](https://deepd3.forschung.fau.de/models/DeepD3_32F.h5) - 32 base filters, original resolution\n* [DeepD3_8F_94nm.h5](https://deepd3.forschung.fau.de/models/DeepD3_8F_94nm.h5) - 8 base filters, resized to 94 nm xy resolution\n* [DeepD3_16F_94nm.h5](https://deepd3.forschung.fau.de/models/DeepD3_16F_94nm.h5) - 16 base filters, resized to 94 nm xy resolution\n* [DeepD3_32F_94nm.h5](https://deepd3.forschung.fau.de/models/DeepD3_32F_94nm.h5) - 32 base filters, resized to 94 nm xy resolution\n\nBrief description:\n\n* Full (32F) DeepD3 model trained on 94 nm (fixed) or a blend of resolutions (free)\n* Medium (16F) DeepD3 model trained on 94 nm (fixed) or a blend of resolutions (free)\n* Tiny (8F) DeepD3 mode trained on 94 nm (fixed) or a blend of resolutions (free)\n\n\n## Workflow\n\n### Train DeepD3 on your own dataset\n\nUse `deepd3-training` to start the GUI for generating training sets. \n\nFor each of your training set, please provide\n\n* The original stack as e.g. TIF files\n* The spine annotations (binary labels) as TIF or MASK files (the latter from [pipra](https://github.com/anki-xyz/pipra))\n* The dendrite annotations as SWC file (only tested for SWC-files generated by [NeuTube](https://neutracing.com/download/))\n\n### Create training data\n\nClick on the button \"Create training data\". For each of your stacks, import the stack, the spine annotation and the dendrite annotation file.\nIf you dendrite annotation is a SWC file, it will create a 3D reconstruction of the SWC file, which will be stored for later use. If you reload the SWC, it will ask you if you want to keep the 3D reconstruction.\n\nAfter importing all files, enter the metadata (resolution in x, y and z) and determine the region of interest using the bounding box and the sliders.\nShortcuts are `B` for current plane is **z begin** and `E` for **z end**. You may enable or disable the cropping to the bounding box. If you are happy, save this region as `d3data`-file.\n\n### View training data\n\nClick on the button \"View training data\" to re-visit any `d3data` files. You also are able to see and potentially manipulate the metadata associated the `d3data` file.\n\n### Arrange training data\n\nFor training, you need to create a `d3set`. This is an assembly of `d3data` files. Click on the button \"Arrange training data\". Then, simply load all relevant data using the \"Add data to set\" button and select appropriate `d3data` files. Clicking on \"Create dataset\" allows you to save your assembly as `d3set` file.\n\n### Actual training\n\nWe have prepared a Jupyter notebook in the folder `examples`. Follow the instructions to train your own deep neural network for DeepD3 use.\nFor professionals, you also may utilize directly the files in `model` and `training` to allow highly individualized training.\nYou only should ensure that your model allows arbitrary input and outputs two separate channels (dendrites and spines).\n\n### Inference\n\nOpen the inference mode using `deepd3-inference`. Load your stack of choice (we currently support TIF stacks) and specify the XY and Z dimensions. Next, you can segment dendrites and dendritic spines using a DeepD3 model from [the model zoo]() by clicking on `Analyze -> Segment dendrite and spines`. Afterwards, you may clean the predictions by clicking on `Analyze -> Cleaning`. Finally, you may build 2D or 3D ROIs using the respective functions in `Analyze`. To test the 3D ROI building, double click in the stack to a region of interest. A window opens that allows you to play with the hyperparameters and segments 3D ROIs in real-time.\n\nAll results can be exported to various file formats. For convenience, DeepD3 saves related data in its \"proprietary\" hdf5 file (that you can open using any hdf5 viewer/program/library). In particular, you may export the predictions as TIF files, the ROIs to ImageJ file format or a folder, the ROI map to a TIF file, or the ROI centroids to a file. \n\nMost functions can be assessed using a batch command script located in `deepd3/inference/batch.py`.\n\n\n## How to cite\n\nDeepD3 is available as preprint soon.\n",
    "bugtrack_url": null,
    "license": "GPLv3",
    "summary": "A tool for segmenting dendrites and dendritic spines.",
    "version": "0.1",
    "split_keywords": [
        "spine",
        "segmentation"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "a8edfd2e4f872f6ae16d510256ddd72cab8ef35544e824c50a6e837eef65c855",
                "md5": "1351de4add247e84b1d9122172421bb4",
                "sha256": "e16d5c514c68f59512cdaa7e6257eab05186d58a989074f525c504b14a25b0b7"
            },
            "downloads": -1,
            "filename": "deepd3-0.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "1351de4add247e84b1d9122172421bb4",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 47915,
            "upload_time": "2023-01-30T21:51:39",
            "upload_time_iso_8601": "2023-01-30T21:51:39.407204Z",
            "url": "https://files.pythonhosted.org/packages/a8/ed/fd2e4f872f6ae16d510256ddd72cab8ef35544e824c50a6e837eef65c855/deepd3-0.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-01-30 21:51:39",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "lcname": "deepd3"
}
Andreas M Kist
Elapsed time: 0.03596s