{ "info": { "author": "Michael Ebner", "author_email": "michael.ebner@kcl.ac.uk", "bugtrack_url": null, "classifiers": [ "Intended Audience :: Developers", "Intended Audience :: Healthcare Industry", "Intended Audience :: Science/Research", "License :: OSI Approved :: BSD License", "Programming Language :: Python", "Programming Language :: Python :: 2", "Programming Language :: Python :: 3", "Topic :: Scientific/Engineering :: Medical Science Apps.", "Topic :: Software Development :: Build Tools" ], "description": "# Numerical Solver Library \n\nThe Numerical Solver Library (NSoL) is a Python-based open-source toolkit for research developed within the [GIFT-Surg][giftsurg] project and contains several implementations of denoising and deconvolution algorithms.\n\nThe algorithm and software were developed by [Michael Ebner][mebner]\nat the [Wellcome/EPSRC Centre for Interventional and Surgical Sciences][weiss], [University College London (UCL)][ucl] (2015 -- 2019), and the [Department of Surgical and Interventional Sciences][sie], [King's College London (KCL)][kcl] (since 2019).\n\nIf you have any questions or comments, please drop an email to `michael.ebner@kcl.ac.uk`.\n\n## Features\n\nImplemented solvers include\n* **Primal-Dual Methods** as described in [[Chambolle and Pock, 2010]](https://link.springer.com/article/10.1007/s10851-010-0251-1)\n* **Alternating Direction Method of Multipliers (ADMM)** as described in, e.g., [[Diamond and Boyd, 2015]](http://stanford.edu/~boyd/papers/admm_distr_stats.html) \n\nto solve\n* **L1- and L2-denoising** problems, i.e.\n\n\n\n\n

\n\n

\nand\n\n* **robust L2-deconvolution** problems, i.e.\n\n\n\n\n

\n\n

\n\nin 1D, 2D or 3D for a variety of regularizers ![img](http://latex.codecogs.com/svg.latex?%5Ctext%7BReg%7D) and data loss functions ![img](http://latex.codecogs.com/svg.latex?%5Cvarrho).\n\n---\n\nThe **available regularizers**, depending on the minimization problem, include\n\n\n\n\n\n* Zeroth-order Tikhonov (TK0): ![img](http://latex.codecogs.com/svg.latex?%5Ctext%7BReg%7D%28%5Cvec%7Bx%7D%29%3D%5Cfrac%7B1%7D%7B2%7D%5CVert%5Cvec%7Bx%7D%5CVert_%7B%5Cell%5E2%7D%5E2)\n* First-order Tikhonov (TK1): ![img](http://latex.codecogs.com/svg.latex?%5Ctext%7BReg%7D%28%5Cvec%7Bx%7D%29%3D%5Cfrac%7B1%7D%7B2%7D%5CVert%5Cnabla%5Cvec%7Bx%7D%5CVert_%7B%5Cell%5E2%7D%5E2)\n* Isotropic Total Variation (TV): ![img](http://latex.codecogs.com/svg.latex?%5Ctext%7BReg%7D%28%5Cvec%7Bx%7D%29%3D%5Ctext%7BTV%7D_%5Ctext%7Biso%7D%28%5Cvec%7Bx%7D%29%3D%5Cbig%5CVert%7C%5Cnabla%5Cvec%7Bx%7D%7C%5Cbig%5CVert_%7B%5Cell%5E1%7D)\n* Huber Function: ![img](http://latex.codecogs.com/svg.latex?%5Ctext%7BReg%7D%28%5Cvec%7Bx%7D%29%3D%5Cfrac%7B1%7D%7B2%5Cgamma%7D%5Cbig%7C%7C%5Cnabla%5Cvec%7Bx%7D%7C%5Cbig%7C_%7B%5Cgamma%7D)\n\n---\n\n**Data loss functions** ![img](http://latex.codecogs.com/svg.latex?%5Cvarrho) are motivated by [SciPy](https://docs.scipy.org/doc/scipy-0.19.0/reference/generated/scipy.optimize.least_squares.html) and allow for robust outlier rejection. Implemented data loss functions are:\n\n\n\n\n\n* `linear`: ![img](http://latex.codecogs.com/svg.latex?%5Cvarrho%28e%29%3De)\n* `soft_l1`: ![img](http://latex.codecogs.com/svg.latex?%5Cvarrho%28e%29%3D2%28%5Csqrt%7B1%2Be%7D-1%29)\n* `huber`: ![img](http://latex.codecogs.com/svg.latex?%5Cvarrho%28e%29%3D%7Ce%7C_%5Cgamma%3D%5Cbegin%7Bcases%7De%2C%26e%3C%5Cgamma%5E2%5C%5C2%5Cgamma%5Csqrt%7Be%7D-%5Cgamma%5E2%2C%26e%5Cge%5Cgamma%5E2%5Cend%7Bcases%7D)\n* `arctan`: ![img](http://latex.codecogs.com/svg.latex?%5Cvarrho%28e%29%3D%5Carctan%28e%29)\n* `cauchy`: ![img](http://latex.codecogs.com/svg.latex?%5Cvarrho%28e%29%3D%5Cln%281%2Be%29)\n\n---\n\nAdditionally, the choice of finding optimal reconstruction parameters is facilitated by providing several evaluation methods including\n* **L-curve studies**, and \n* the **evaluation of similarity measures** (in case a reference image is available) \n\nin the course of **parameter studies**. Implemented similarity measures are\n\n* Sum of Squared Differences (SSD)\n* Mean Absolute Error (MAE)\n* Mean Square Error (MSE)\n* Root Mean Square Error (RMSE)\n* Peak-Signal-to-Noise Ratio (PSNR)\n* Mutual Information (MI)\n* Normalized Mutual Information (NMI)\n* Structural Similarity (SSIM)\n* Normalized Cross Correlation (NCC)\n\n## Installation\n\nNSoL was developed in\n\n* Mac OS X 10.10 and 10.12\n* Ubuntu 14.04 and 16.04\n\nand tested for Python 2.7.12 and 3.5.2.\n\nIn case NSoL is used in conjuction with any of the toolkits of [NiftyMIC][niftymic], [Volumetric Reconstruction From Printed Films][volumetricreconstructionfromprintedfilms] or [SimpleReg][simplereg], please \n* install [ITK_NiftyMIC][itkniftymic]\n\nIf NSoL is used standalone, please run instead\n* `pip install itk`\n\nAfterwards, clone this repository via \n* `git clone git@github.com:gift-surg/NSoL.git`\n\nwhere all remaining dependencies can be installed using `pip`:\n* `pip install -e .`\n\n\n## Usage\n\n### Denoising\n\nTVL1/TVL2/HuberL2/HuberL1 Denoising can be run via\n\n```\nnsol_run_denoising \\\n--observation path-to-observation-png-nii-mat \\\n--result path-to-denoised-result-png-nii-mat \\\n--reconstruction-type TVL1 \\\n--alpha 0.05 \\\n--iterations 50\n```\n```\nnsol_run_denoising \\\n--observation path-to-observation-png-nii-mat \\\n--reference path-to-reference-png-nii-mat \\\n--result path-to-denoised-result-png-nii-mat \\\n--reconstruction-type TVL1 \\\n--alpha 0.05 \\\n--iterations 50\n```\n\n### Deconvolution\nExamples for TK0L2/TK1L2/TVL2/HuberL2 deconvolution calls are\n\n```\nnsol_run_deconvolution \\\n--observation path-to-observation-png-nii-mat \\\n--result path-to-denoised-result-png-nii-mat \\\n--reconstruction-type HuberL2 \\\n--blur 1.2 \\\n--alpha 0.05 \\\n--iterations 50\n```\n```\nnsol_run_deconvolution \\\n--observation path-to-observation-png-nii-mat \\\n--reference path-to-reference-png-nii-mat \\\n--result path-to-denoised-result-png-nii-mat \\\n--reconstruction-type HuberL2 \\\n--alpha 0.05 \\\n--blur 1.2 \\\n--iterations 50 \\\n--data-loss soft_l1 \\\n--minimizer L-BFGS-B\n```\n\n### Parameter Studies\nParameter studies for the denoising problem (and, similarly, for deconvolution problem) can be performed by, e.g.,\n```\nnsol_run_denoising_study \\\n--observation path-to-observation-png-nii-mat \\\n--dir-output path-to-parameter-study \\\n--reference path-to-reference-png-nii-mat \\\n--reconstruction-type TVL2 \\\n--study-name TVL2-Denoising \\\n--measures RMSE PSNR NCC NMI SSIM \\\n--alpha-range 0.001 0.05 20\n```\n\nThe results can be visualized by\n```\nnsol_show_parameter_study \\\n--dir-input path-to-parameter-study \\\n--study-name TVL2-Denoising \\\n--dir-output-figures dir-to-figures\n```\n\n## Licensing and Copyright\nCopyright (c) 2019 Michael Ebner and contributors.\nThis framework is made available as free open-source software under the [BSD-3-Clause License][bsd]. Other licenses may apply for dependencies.\n\n## Funding\nThis work is partially funded by the UCL [Engineering and Physical Sciences Research Council (EPSRC)][epsrc] Centre for Doctoral Training in Medical Imaging (EP/L016478/1), the Innovative Engineering for Health award ([Wellcome Trust][wellcometrust] [WT101957] and [EPSRC][epsrc] [NS/A000027/1]), and supported by researchers at the [National Institute for Health Research][nihr] [University College London Hospitals (UCLH)][uclh] Biomedical Research Centre.\n\n## References\nAssociated publications are \n* [[Ebner2019]](https://onlinelibrary.wiley.com/doi/abs/10.1002/mrm.27852) Ebner, M., Patel, P. A., Atkinson, D., Caselton, C., Firmin, F., Amin, Z., Bainbridge, A., De Coppi, P., Taylor, S. A., Ourselin, S., Chouhan, M. D., & Vercauteren, T. (2019). Super\u2010resolution for upper abdominal MRI: Acquisition and post\u2010processing protocol optimization using brain MRI control data and expert reader validation. Magnetic Resonance in Medicine.\n* [[EbnerWang2018]](http://link.springer.com/10.1007/978-3-030-00928-1_36) Ebner, M., Wang, G., Li, W., Aertsen, M., Patel, P. A., Melbourne, A., Doel, T., David, A. L., Deprest, J., Ourselin, S., & Vercauteren, T. (2018). An Automated Localization, Segmentation and Reconstruction Framework for Fetal Brain MRI. In Medical Image Computing and Computer-Assisted Intervention -- MICCAI 2018 (pp. 313\u2013320). Springer\n* [[Ebner2018]](https://www.sciencedirect.com/science/article/pii/S1053811917308042) Ebner, M., Chung, K. K., Prados, F., Cardoso, M. J., Chard, D. T., Vercauteren, T., & Ourselin, S. (2018). Volumetric reconstruction from printed films: Enabling 30 year longitudinal analysis in MR neuroimaging. NeuroImage, 165, 238\u2013250.\n* [[Xie2017]](https://www.spiedigitallibrary.org/journals/Journal_of_Biomedical_Optics/volume-22/issue-11/116006/Wide-field-spectrally-resolved-quantitative-fluorescence-imaging-system--toward/10.1117/1.JBO.22.11.116006.full) Xie, Y., Thom, M., Ebner, M., Wykes, V., Desjardins, A., Miserocchi, A., Ourselin, S., McEvoy, A. W., and Vercauteren, T. (2017). Wide-field spectrally resolved quantitative fluorescence imaging system: toward neurosurgical guidance in glioma resection. Journal of Biomedical Optics, 22(11).\n* [[Ranzini2017]](https://mski2017.files.wordpress.com/2017/09/miccai-mski2017.pdf) Ranzini, M. B., Ebner, M., Cardoso, M. J., Fotiadou, A., Vercauteren, T., Henckel, J., Hart, A., Ourselin, S., and Modat, M. (2017). Joint Multimodal Segmentation of Clinical CT and MR from Hip Arthroplasty Patients. MICCAI Workshop on Computational Methods and Clinical Applications in Musculoskeletal Imaging (MSKI) 2017.\n* [[Ebner2017]](https://link.springer.com/chapter/10.1007%2F978-3-319-52280-7_1) Ebner, M., Chouhan, M., Patel, P. A., Atkinson, D., Amin, Z., Read, S., Punwani, S., Taylor, S., Vercauteren, T., and Ourselin, S. (2017). Point-Spread-Function-Aware Slice-to-Volume Registration: Application to Upper Abdominal MRI Super-Resolution. In Zuluaga, M. A., Bhatia, K., Kainz, B., Moghari, M. H., and Pace, D. F., editors, Reconstruction, Segmentation, and Analysis of Medical Images. RAMBO 2016, volume 10129 of Lecture Notes in Computer Science, pages 3\u201313. Springer International Publishing.\n\n[mebner]: https://www.linkedin.com/in/ebnermichael\n[weiss]: https://www.ucl.ac.uk/interventional-surgical-sciences\n[bsd]: https://opensource.org/licenses/BSD-3-Clause\n[giftsurg]: http://www.gift-surg.ac.uk\n[cmic]: http://cmic.cs.ucl.ac.uk\n[guarantors]: https://guarantorsofbrain.org/\n[ucl]: http://www.ucl.ac.uk\n[kcl]: https://www.kcl.ac.uk\n[sie]: https://www.kcl.ac.uk/bmeis/our-departments/surgical-interventional-engineering\n[uclh]: http://www.uclh.nhs.uk\n[epsrc]: http://www.epsrc.ac.uk\n[wellcometrust]: http://www.wellcome.ac.uk\n[mssociety]: https://www.mssociety.org.uk/\n[nihr]: http://www.nihr.ac.uk/research\n[itkniftymic]: https://github.com/gift-surg/ITK_NiftyMIC/wikis/home\n[niftymic]: https://github.com/gift-surg/NiftyMIC\n[nsol]: https://github.com/gift-surg/NSoL\n[simplereg]: https://github.com/gift-surg/SimpleReg\n[simplereg-dependencies]: https://github.com/gift-surg/SimpleReg/wikis/simplereg-dependencies\n[pysitk]: https://github.com/gift-surg/PySiTK\n[volumetricreconstructionfromprintedfilms]: https://github.com/gift-surg/VolumetricReconstructionFromPrintedFilms", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/gift-surg/NSoL", "keywords": "development numericalsolver convexoptimisation", "license": "BSD-3-Clause", "maintainer": "", "maintainer_email": "", "name": "NSoL", "package_url": "https://pypi.org/project/NSoL/", "platform": "", "project_url": "https://pypi.org/project/NSoL/", "project_urls": { "Homepage": "https://github.com/gift-surg/NSoL" }, "release_url": "https://pypi.org/project/NSoL/0.1.14/", "requires_dist": null, "requires_python": "", "summary": "The Numerical Solver Library (NSoL) is a research-focused toolkit for denoising and deconvolution applications using ADMM and Primal-Dual methods.", "version": "0.1.14" }, "last_serial": 5662010, "releases": { "0.1.10": [ { "comment_text": "", "digests": { "md5": "9eb851bf752c1ff1bb4e8cb5df6573e5", "sha256": "dead814d02672bc267522dad12afa68e08a27648ef3232060fe36ea4aa4e1cf1" }, "downloads": -1, "filename": "NSoL-0.1.10.tar.gz", "has_sig": false, "md5_digest": "9eb851bf752c1ff1bb4e8cb5df6573e5", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 63650, "upload_time": "2019-03-24T01:19:55", "url": "https://files.pythonhosted.org/packages/31/2e/2af4e7949ed90b73d29155fb5a423b1f605caf3feafeec2cca408191bf2c/NSoL-0.1.10.tar.gz" } ], "0.1.11": [ { "comment_text": "", "digests": { "md5": "946936daa3ffaba1c73e38250a872d83", "sha256": "07ddfaf408ad52aa4eecce4c6934443b0831566191fe1b121291c2e2692cff2c" }, "downloads": -1, "filename": "NSoL-0.1.11.tar.gz", "has_sig": false, "md5_digest": "946936daa3ffaba1c73e38250a872d83", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 63668, "upload_time": "2019-03-24T14:08:45", "url": "https://files.pythonhosted.org/packages/bc/9e/1cca8caf014285197ca9253a6bd7577bddea7ac9e0185a4d0f7282082e3a/NSoL-0.1.11.tar.gz" } ], "0.1.12": [ { "comment_text": "", "digests": { "md5": "ce85c525c896056657e12d338dd0f9b4", "sha256": "510d8615e65ccedc1d8415e1f434da4d62c832e42eb3a03b570f58cffed62e10" }, "downloads": -1, "filename": "NSoL-0.1.12.tar.gz", "has_sig": false, "md5_digest": "ce85c525c896056657e12d338dd0f9b4", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 64140, "upload_time": "2019-03-28T16:27:00", "url": "https://files.pythonhosted.org/packages/a6/5d/872bb23b7fb09129cc3f38d7d507a921c91939dc89e93d0d11150d5e3649/NSoL-0.1.12.tar.gz" } ], "0.1.13": [ { "comment_text": "", "digests": { "md5": "fb222ff96f58a595fd63a246c96895b9", "sha256": "cd0b6ca31486550a96f2a5e6433f40fbc0a9a413f7f63b5bea2088c1acfa0a58" }, "downloads": -1, "filename": "NSoL-0.1.13.tar.gz", "has_sig": false, "md5_digest": "fb222ff96f58a595fd63a246c96895b9", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 64694, "upload_time": "2019-07-26T10:54:46", "url": "https://files.pythonhosted.org/packages/77/94/257756dd27c4569e818ed43c7db1ad9f5fb894b716796c4bc949d7a1773a/NSoL-0.1.13.tar.gz" } ], "0.1.14": [ { "comment_text": "", "digests": { "md5": "053cabc44b8cba10817b38c599c35c3e", "sha256": "f2c9dc35a586073a6a06df10f6ea5a3ba83164f793a4aff49e4dd44c06a0aeef" }, "downloads": -1, "filename": "NSoL-0.1.14.tar.gz", "has_sig": false, "md5_digest": "053cabc44b8cba10817b38c599c35c3e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 64808, "upload_time": "2019-08-11T12:25:53", "url": "https://files.pythonhosted.org/packages/e7/9f/31ce1ad828217cfc793130a2e4820fea994a24733bad8b4846667d54ff81/NSoL-0.1.14.tar.gz" } ], "0.1.6": [ { "comment_text": "", "digests": { "md5": "f9778177143f2b07f1bd4431e188691d", "sha256": "518891f9854c934c6ecbcc4f4e5712667617fe4a3371b178c6a09d9b4477cc13" }, "downloads": -1, "filename": "NSoL-0.1.6.tar.gz", "has_sig": false, "md5_digest": "f9778177143f2b07f1bd4431e188691d", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 57964, "upload_time": "2019-01-15T23:42:30", "url": "https://files.pythonhosted.org/packages/b4/11/835fc8da125c535fed063e576cf746fb4bd69afcdc8edb2d3b08eaa43138/NSoL-0.1.6.tar.gz" } ], "0.1.6.2": [ { "comment_text": "", "digests": { "md5": "8e14a8672f468b7de732cba9a0cbd74b", "sha256": "38ac03ba8772b6d452427c2eb2c1789af7465c06eef2165fdf19f918f8962a32" }, "downloads": -1, "filename": "NSoL-0.1.6.2.tar.gz", "has_sig": false, "md5_digest": "8e14a8672f468b7de732cba9a0cbd74b", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 58533, "upload_time": "2019-02-10T13:13:13", "url": "https://files.pythonhosted.org/packages/48/6f/23d8a1969bd4cf197bbd9e76e06f5007af063280676b5fc3d175ab066d69/NSoL-0.1.6.2.tar.gz" } ], "0.1.7": [ { "comment_text": "", "digests": { "md5": "9f22045d453279160bad9e4a6ab812c5", "sha256": "ec69409f639f525663c10df982f3a7259e244510f97eebffef5b915908767f0f" }, "downloads": -1, "filename": "NSoL-0.1.7.tar.gz", "has_sig": false, "md5_digest": "9f22045d453279160bad9e4a6ab812c5", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 58547, "upload_time": "2019-02-10T13:13:38", "url": "https://files.pythonhosted.org/packages/d5/e5/c559a70ce8668dc77350c44751cf4366af7ba90872bc22e6d9b47d04e147/NSoL-0.1.7.tar.gz" } ], "0.1.8": [ { "comment_text": "", "digests": { "md5": "e9bc070e9229ab07881cdec889b3650b", "sha256": "8d86c92cc89d9eebaf7ceca77c159f73ae0a7c29792e0a29ca82a4e59c81058e" }, "downloads": -1, "filename": "NSoL-0.1.8.tar.gz", "has_sig": false, "md5_digest": "e9bc070e9229ab07881cdec889b3650b", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 62480, "upload_time": "2019-02-20T16:25:54", "url": "https://files.pythonhosted.org/packages/2b/1c/3e42efcff97b5f9b86bb213e10ccc72a83be82f6bde65594ba6da7d65178/NSoL-0.1.8.tar.gz" } ], "0.1.9": [ { "comment_text": "", "digests": { "md5": "cbbebcd9509ce2e45a2383bcfea1292f", "sha256": "2832212f057d7b09d42c4a9b3f91280708e2223f782546faab141992a9f0a247" }, "downloads": -1, "filename": "NSoL-0.1.9.tar.gz", "has_sig": false, "md5_digest": "cbbebcd9509ce2e45a2383bcfea1292f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 63342, "upload_time": "2019-03-21T15:02:39", "url": "https://files.pythonhosted.org/packages/8e/e4/7836ed857c014f13e08a4966f22ef51eff44b1be82ae0d3224e4bee15cfa/NSoL-0.1.9.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "053cabc44b8cba10817b38c599c35c3e", "sha256": "f2c9dc35a586073a6a06df10f6ea5a3ba83164f793a4aff49e4dd44c06a0aeef" }, "downloads": -1, "filename": "NSoL-0.1.14.tar.gz", "has_sig": false, "md5_digest": "053cabc44b8cba10817b38c599c35c3e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 64808, "upload_time": "2019-08-11T12:25:53", "url": "https://files.pythonhosted.org/packages/e7/9f/31ce1ad828217cfc793130a2e4820fea994a24733bad8b4846667d54ff81/NSoL-0.1.14.tar.gz" } ] }