HLSVDPROPY
======
Overview - Black box fitting of Time Domain Signals
------
This is a 'pure Python' implementation of the algorithm provided by the Fortran
based HLSVDPRO package, version 2.0.0.
The HLSVDPROPY package provides code to fit a model function (sum of lorentzians)
to time-domain data via a 'black box' state space approach (see references below).
One frequent use for this is by the clinical MRS community for residual water
removal from MRS signals in the time domain.
Internally, we use the scipy.linalg SVD libraries for computing the singular
value decomposition (SVD) of large and sparse matrices. The calculated singular
values and column vectors are subsequently processed into lists of parameters
that describe the sum of lorentzians that approximate the data based on the
paper by Laudadio (see below). Parameters are numpy arrays of: frequencies,
damping factors, amplitudes, and phases.
**Example:**
```
import hlsvdpropy
import numpy as np
import matplotlib.pyplot as plt
data = hlsvdpropy.get_testdata()
npts = len(data)
indat = hlsvdpropy.TESTDATA # this is a built-in dict with test data
dwell = float(indat['step_size'])
nsv_sought = indat['n_singular_values']
result = hlsvdpropy.hlsvd(data, nsv_sought, dwell)
nsv_found, singvals, freq, damp, ampl, phas = result
print("np.allclose(freq, indat['freq0']) = ", np.allclose(freq, np.array(indat['freq0'])) )
fid = hlsvdpropy.create_hlsvd_fids(result, npts, dwell, sum_results=True, convert=False)
chop = ((((np.arange(len(fid)) + 1) % 2) * 2) - 1)
dat = data * chop
fit = fid * chop
dat[0] *= 0.5
fit[0] *= 0.5
plt.plot(np.fft.fft(dat).real, color='r')
plt.plot(np.fft.fft(fit).real, color='b')
plt.plot(np.fft.fft(dat-fit).real, color='g')
plt.show()
```
HLSVDPROPY Methods
------
- `hlsvdpropy.hlsvdpro(data, nsv_sought, m=None, sparse=True)` - the main method
for running the hlsvdpro algorithm. It does not require the dwell time of the
time domain data, but it also does not convert the results to standard units. It
does allow the user to specify the dimensions of the Hankel matrix, and whether
a sparse SVD is performed or not.
- `hlsvdpropy.hlsvd(data, nsv_sought, dwell_time)` - provides backwards
compatibility to the API for HLSVDPRO version 1.x. It calls the hlsvdpro() method
with default values corresponding to the algorithm used in version 1.x. See
docstring for more information on the default values used.
HLSVDPROPY Utility Methods
------
- `hlsvdpropy.create_hlsvd_fids(result, npts, dwell, sum_results=False, convert=True)` -
can be used to create FIDs from the results tuple from either the `hlsvd()`
or the `hlsvdpro()` methods. It can return either individual FIDs or a sum of
all FIDs as a result.
- `hlsvdpropy.convert_hlsvd_result(result, dwell)` - uses the dwell time to
convert the `hlsvdpro()` result tuple to more standard units. Frequencies
convert to [kHz], and damping factors to [ms]. Phases convert to [degrees].
Singular values, amplitudes and row and column matrices are maintained at
their same values and output tuple locations. Note - the `hlsvd()` method
automatically calls this internally, so you don't have to convert values
if you use that method.
- `hlsvdpropy.get_testdata()` - returns a numpy array of 1024 complex data
points that represents a real world short TE single voxel PRESS data set.
This function converts the base64 encoded string saved in the TESTDATA dict
into a numpy array for you. Additional information about the data and the
known values for fitting it via the hlsvd() method can be retrieved from
the TESTDATA dict. See 'Example' for more usage information.
Technical Overview and References
------
For complete copyright and license information, see the LICENSE file. The
references are for HLSVDPRO and are provided for completeness.
The state space approach is described in S.Y. Kung, K.S. Arun and D.V. Bhaskar
Rao, J. Opt. Soc. Am. 73, 1799 (1983).
HLSVDPRO version 1.0.x was implemented based on the paper by W.W.F. Pijnappel,
A. van den Boogaart, R. de Beer, D. van Ormondt, J. Magn. Reson. 97, 122 (1992)
and made use of code from PROPACK version 1.x.
HLSVDPRO version 2.x was adaptated to use PROPACK library version 2.1 to
implement the HLSVDPRO algorithm as described in T. Laudadio, N. Mastronardi
L. Vanhamme, P. Van Hecke and S. Van Huffel, "Improved Lanczos algorithms for
blackbox MRS data quantitation", Journal of Magnetic Resonance, Volume 157,
pages 292-297, 2002.
Raw data
{
"_id": null,
"home_page": "https://github.com/bsoher/hlsvdpropy",
"name": "hlsvdpropy",
"maintainer": "Brian J. Soher",
"docs_url": null,
"requires_python": "",
"maintainer_email": "bsoher@briansoher.com",
"keywords": "svd,hlsvd,hlsvdpro,propack,time domain,fitting",
"author": "Brian J. Soher",
"author_email": "bsoher@briansoher.com",
"download_url": "",
"platform": "Linux",
"description": "HLSVDPROPY\r\n======\r\n\r\nOverview - Black box fitting of Time Domain Signals\r\n------\r\n\r\nThis is a 'pure Python' implementation of the algorithm provided by the Fortran\r\nbased HLSVDPRO package, version 2.0.0. \r\n\r\nThe HLSVDPROPY package provides code to fit a model function (sum of lorentzians) \r\nto time-domain data via a 'black box' state space approach (see references below). \r\nOne frequent use for this is by the clinical MRS community for residual water \r\nremoval from MRS signals in the time domain. \r\n\r\nInternally, we use the scipy.linalg SVD libraries for computing the singular \r\nvalue decomposition (SVD) of large and sparse matrices. The calculated singular \r\nvalues and column vectors are subsequently processed into lists of parameters \r\nthat describe the sum of lorentzians that approximate the data based on the \r\npaper by Laudadio (see below). Parameters are numpy arrays of: frequencies, \r\ndamping factors, amplitudes, and phases. \r\n\r\n\r\n**Example:**\r\n\r\n```\r\nimport hlsvdpropy\r\nimport numpy as np\r\nimport matplotlib.pyplot as plt\r\n\r\ndata = hlsvdpropy.get_testdata()\r\nnpts = len(data)\r\nindat = hlsvdpropy.TESTDATA \t\t# this is a built-in dict with test data \r\ndwell = float(indat['step_size'])\r\nnsv_sought = indat['n_singular_values']\r\n\r\nresult = hlsvdpropy.hlsvd(data, nsv_sought, dwell)\r\n\r\nnsv_found, singvals, freq, damp, ampl, phas = result\r\n\r\nprint(\"np.allclose(freq, indat['freq0']) = \", np.allclose(freq, np.array(indat['freq0'])) )\r\n\r\nfid = hlsvdpropy.create_hlsvd_fids(result, npts, dwell, sum_results=True, convert=False)\r\n\r\nchop = ((((np.arange(len(fid)) + 1) % 2) * 2) - 1)\r\ndat = data * chop\r\nfit = fid * chop\r\ndat[0] *= 0.5\r\nfit[0] *= 0.5\r\n\r\nplt.plot(np.fft.fft(dat).real, color='r') \r\nplt.plot(np.fft.fft(fit).real, color='b') \r\nplt.plot(np.fft.fft(dat-fit).real, color='g')\r\nplt.show()\r\n\r\n```\r\n\r\nHLSVDPROPY Methods\r\n------\r\n\r\n- `hlsvdpropy.hlsvdpro(data, nsv_sought, m=None, sparse=True)` - the main method \r\nfor running the hlsvdpro algorithm. It does not require the dwell time of the \r\ntime domain data, but it also does not convert the results to standard units. It\r\ndoes allow the user to specify the dimensions of the Hankel matrix, and whether\r\na sparse SVD is performed or not.\r\n\r\n- `hlsvdpropy.hlsvd(data, nsv_sought, dwell_time)` - provides backwards \r\ncompatibility to the API for HLSVDPRO version 1.x. It calls the hlsvdpro() method\r\nwith default values corresponding to the algorithm used in version 1.x. See \r\ndocstring for more information on the default values used.\r\n\r\nHLSVDPROPY Utility Methods\r\n------\r\n- `hlsvdpropy.create_hlsvd_fids(result, npts, dwell, sum_results=False, convert=True)` - \r\ncan be used to create FIDs from the results tuple from either the `hlsvd()` \r\nor the `hlsvdpro()` methods. It can return either individual FIDs or a sum of \r\nall FIDs as a result. \r\n\r\n- `hlsvdpropy.convert_hlsvd_result(result, dwell)` - uses the dwell time to \r\nconvert the `hlsvdpro()` result tuple to more standard units. Frequencies \r\nconvert to [kHz], and damping factors to [ms]. Phases convert to [degrees]. \r\nSingular values, amplitudes and row and column matrices are maintained at \r\ntheir same values and output tuple locations. Note - the `hlsvd()` method \r\nautomatically calls this internally, so you don't have to convert values\r\nif you use that method.\r\n\r\n- `hlsvdpropy.get_testdata()` - returns a numpy array of 1024 complex data \r\npoints that represents a real world short TE single voxel PRESS data set.\r\nThis function converts the base64 encoded string saved in the TESTDATA dict\r\ninto a numpy array for you. Additional information about the data and the \r\nknown values for fitting it via the hlsvd() method can be retrieved from \r\nthe TESTDATA dict. See 'Example' for more usage information.\r\n\r\nTechnical Overview and References\r\n------\r\n\r\nFor complete copyright and license information, see the LICENSE file. The \r\nreferences are for HLSVDPRO and are provided for completeness.\r\n\r\nThe state space approach is described in S.Y. Kung, K.S. Arun and D.V. Bhaskar\r\nRao, J. Opt. Soc. Am. 73, 1799 (1983).\r\n\r\nHLSVDPRO version 1.0.x was implemented based on the paper by W.W.F. Pijnappel, \r\nA. van den Boogaart, R. de Beer, D. van Ormondt, J. Magn. Reson. 97, 122 (1992)\r\nand made use of code from PROPACK version 1.x.\r\n\r\nHLSVDPRO version 2.x was adaptated to use PROPACK library version 2.1 to \r\nimplement the HLSVDPRO algorithm as described in T. Laudadio, N. Mastronardi\r\nL. Vanhamme, P. Van Hecke and S. Van Huffel, \"Improved Lanczos algorithms for \r\nblackbox MRS data quantitation\", Journal of Magnetic Resonance, Volume 157, \r\npages 292-297, 2002. \r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "https://opensource.org/licenses/BSD-3-Clause",
"summary": "This is a 'pure Python' implementation of the HLSVDPRO package version 2.0.0. It fits time domain data to a model function that is a set of lorentzian decaying sinusoids using the state space approach.",
"version": "2.0.2",
"project_urls": {
"Homepage": "https://github.com/bsoher/hlsvdpropy"
},
"split_keywords": [
"svd",
"hlsvd",
"hlsvdpro",
"propack",
"time domain",
"fitting"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2835f12c5390402aead1faeedfa78f8784737c8cbf4bf72480c3f161388ad284",
"md5": "66ca44ee028f259a7db755a2895ed02d",
"sha256": "3ed1788e5b05bfe823c6d8463c6aebf6fc45cedb5c00906da50c098bb46b9eae"
},
"downloads": -1,
"filename": "hlsvdpropy-2.0.2-py2-none-any.whl",
"has_sig": false,
"md5_digest": "66ca44ee028f259a7db755a2895ed02d",
"packagetype": "bdist_wheel",
"python_version": "py2",
"requires_python": null,
"size": 29663,
"upload_time": "2023-07-24T21:59:39",
"upload_time_iso_8601": "2023-07-24T21:59:39.326765Z",
"url": "https://files.pythonhosted.org/packages/28/35/f12c5390402aead1faeedfa78f8784737c8cbf4bf72480c3f161388ad284/hlsvdpropy-2.0.2-py2-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4273f8d3e0961e3df970c552a0b3d3687a4ec4f6cf642ec715cd2ee80145ccd7",
"md5": "76864d3bdd3754b07c1a4cc094f6a1c8",
"sha256": "7a05554f84963e76427bad136ad03125dbed0385bcfd7d5a8cfbe3240b92ca37"
},
"downloads": -1,
"filename": "hlsvdpropy-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "76864d3bdd3754b07c1a4cc094f6a1c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 29621,
"upload_time": "2023-07-24T21:59:40",
"upload_time_iso_8601": "2023-07-24T21:59:40.397054Z",
"url": "https://files.pythonhosted.org/packages/42/73/f8d3e0961e3df970c552a0b3d3687a4ec4f6cf642ec715cd2ee80145ccd7/hlsvdpropy-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-24 21:59:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bsoher",
"github_project": "hlsvdpropy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hlsvdpropy"
}
JSON
