# dafne-models
Repository for model generators
## Important!
git-lfs is required to properly check out the model weights for the "thigh" and "leg" models.
## How to use the model trainer
The model trainer is a python script that can be used to train a model on a set of images.
It is based on the keras library and uses a tensorflow backend. The model architecture is 2D and is the
same as the "thigh" and "leg" models, that is, a modified V-Net.
The input data is in the form of "Numpy bundle" files, which contain the image dataset with the "data" key,
the resolution under the "resolution" key, in the form of a numpy vector with 2 or 3 elements corresponding
to the voxel size in the three dimensions, and various binary masks in the form of 3D numpy arrays with the same
dimensions as the data with "mask_<roi1>", "mask_<roi2>" etc. keys (where <roi1> and <roi2> are the names of the
regions of interest, e.g. mask_tibia, mask_fibula, etc).
This numpy bundle can (and should) be saved from Dafne by selecting the "Export masks"->"Numpy bundle" option.
Once multiple such datasets are collected under the same folder, the model trainer can be used.
### Usage
The recommended usage is by using the GUI for fitting, as it allows a wider range of options.
Assuming you have cloned the dafne_models repository, install it locally together with its dependencies with
```pip install -e .[gui]```
Then, run the GUI with
```python create_model_ui.py```
or simply with
```create_model_ui```
Load the data by clicking on "Choose" next to the "Data location" field and selecting the folder containing
the numpy bundles.
Then, select the model name and the output folder and click on "Fit model". The model will start training.
You can monitor the progress from the plots that will be displayed. On the right, one segmentation of a validation
slice is displayed at the end of every epoch. The slider on the bottom chooses which validation slice is displayed.
Next to it, a checkbox lets the user choose whether the training should be stopped when the validation loss starts
to increase. This is useful to avoid overfitting, but the user can choose to stop it manually instead.
The model will be saved in the output folder as a keras model (.hdf5 file) and as a dafne model (.model file). A .py
file is also saved to build the .model file from the .hdf5 file.
### Importing a new model into Dafne
The model can be imported into Dafne by selecting "Local" as the model location in the settings, and then choosing
"Import model" from the "File" menu. If ou don't see "Import model" under the "File" menu, double-check that the
Model location is set to "Local".
### Caveats
It is highly recommended to have a correctly configured GPU for the training. Make sure that you have tensorflow
installed for the python version that you are using, and that the GPU libraries are compatible with this tensorflow
version.
## Command line usage
A command-line model trainer is also provided. It can be used to train a model from the command line, without
the GUI. It is recommended to use the GUI instead, as it allows a wider range of options.
To train a model from the command line, run
```python create_model.py <model_name> <data folder>```
where <data_folder> is the folder containing the numpy bundles, and <model_name> is the name of the model
to be trained. The model will be saved in the current folder.
Raw data
{
"_id": null,
"home_page": "https://github.com/dafne-imaging/dafne-models",
"name": "dafne-models",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Francesco Santini",
"author_email": "francesco.santini@unibas.ch",
"download_url": "https://files.pythonhosted.org/packages/7c/ab/2d630919c1275b6549fbd215dcd736de314a517320d3c8c3e872d41d515d/dafne-models-1.1.tar.gz",
"platform": null,
"description": "# dafne-models\nRepository for model generators\n\n## Important!\ngit-lfs is required to properly check out the model weights for the \"thigh\" and \"leg\" models.\n\n## How to use the model trainer\nThe model trainer is a python script that can be used to train a model on a set of images.\nIt is based on the keras library and uses a tensorflow backend. The model architecture is 2D and is the \nsame as the \"thigh\" and \"leg\" models, that is, a modified V-Net.\n\nThe input data is in the form of \"Numpy bundle\" files, which contain the image dataset with the \"data\" key,\nthe resolution under the \"resolution\" key, in the form of a numpy vector with 2 or 3 elements corresponding\nto the voxel size in the three dimensions, and various binary masks in the form of 3D numpy arrays with the same\ndimensions as the data with \"mask_<roi1>\", \"mask_<roi2>\" etc. keys (where <roi1> and <roi2> are the names of the\nregions of interest, e.g. mask_tibia, mask_fibula, etc).\n\nThis numpy bundle can (and should) be saved from Dafne by selecting the \"Export masks\"->\"Numpy bundle\" option.\n\nOnce multiple such datasets are collected under the same folder, the model trainer can be used.\n\n### Usage\nThe recommended usage is by using the GUI for fitting, as it allows a wider range of options.\nAssuming you have cloned the dafne_models repository, install it locally together with its dependencies with\n\n```pip install -e .[gui]```\n\nThen, run the GUI with\n\n```python create_model_ui.py```\n\nor simply with\n\n```create_model_ui```\n\nLoad the data by clicking on \"Choose\" next to the \"Data location\" field and selecting the folder containing \nthe numpy bundles.\nThen, select the model name and the output folder and click on \"Fit model\". The model will start training.\nYou can monitor the progress from the plots that will be displayed. On the right, one segmentation of a validation\nslice is displayed at the end of every epoch. The slider on the bottom chooses which validation slice is displayed.\nNext to it, a checkbox lets the user choose whether the training should be stopped when the validation loss starts\nto increase. This is useful to avoid overfitting, but the user can choose to stop it manually instead.\n\nThe model will be saved in the output folder as a keras model (.hdf5 file) and as a dafne model (.model file). A .py\nfile is also saved to build the .model file from the .hdf5 file.\n\n### Importing a new model into Dafne\nThe model can be imported into Dafne by selecting \"Local\" as the model location in the settings, and then choosing\n\"Import model\" from the \"File\" menu. If ou don't see \"Import model\" under the \"File\" menu, double-check that the\nModel location is set to \"Local\".\n\n### Caveats\nIt is highly recommended to have a correctly configured GPU for the training. Make sure that you have tensorflow\ninstalled for the python version that you are using, and that the GPU libraries are compatible with this tensorflow\nversion.\n\n## Command line usage\nA command-line model trainer is also provided. It can be used to train a model from the command line, without\nthe GUI. It is recommended to use the GUI instead, as it allows a wider range of options.\n\nTo train a model from the command line, run\n\n```python create_model.py <model_name> <data folder>```\n\nwhere <data_folder> is the folder containing the numpy bundles, and <model_name> is the name of the model\nto be trained. The model will be saved in the current folder.\n",
"bugtrack_url": null,
"license": "",
"summary": "Deep Learning models module for Dafne",
"version": "1.1",
"project_urls": {
"Bug Tracker": "https://github.com/dafne-imaging/dafne-model/issues",
"Homepage": "https://github.com/dafne-imaging/dafne-models"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2c4af6cf0dc55928ea48efffbca5785e88cbce1c1fabb122d02355f6d34f0a59",
"md5": "5062cc1de7fc9db42b571e3b876e802e",
"sha256": "26518e6f2ffbb91c297e2ff04e3cbf206a02f67833d96d2c1b0374d39e9be37d"
},
"downloads": -1,
"filename": "dafne_models-1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5062cc1de7fc9db42b571e3b876e802e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 29675,
"upload_time": "2024-02-08T06:41:44",
"upload_time_iso_8601": "2024-02-08T06:41:44.512309Z",
"url": "https://files.pythonhosted.org/packages/2c/4a/f6cf0dc55928ea48efffbca5785e88cbce1c1fabb122d02355f6d34f0a59/dafne_models-1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7cab2d630919c1275b6549fbd215dcd736de314a517320d3c8c3e872d41d515d",
"md5": "8b6549d59ef7161f48c1cd89617bca20",
"sha256": "80431046454b2e3dd3efa491efd4bdb6e70616064d6436d410694582572dae95"
},
"downloads": -1,
"filename": "dafne-models-1.1.tar.gz",
"has_sig": false,
"md5_digest": "8b6549d59ef7161f48c1cd89617bca20",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 28780,
"upload_time": "2024-02-08T06:41:46",
"upload_time_iso_8601": "2024-02-08T06:41:46.407461Z",
"url": "https://files.pythonhosted.org/packages/7c/ab/2d630919c1275b6549fbd215dcd736de314a517320d3c8c3e872d41d515d/dafne-models-1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-08 06:41:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dafne-imaging",
"github_project": "dafne-models",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "dafne-models"
}
JSON
