# H2MM_C
[](https://github.com/harripd/H2MMpythonlib/actions)
[](https://h2mmpythonlib.readthedocs.io/en/latest/?badge=latest)
## Project Desciption
H2MM_C is a python extension module that implements the H<sup>2</sup>MM algorithm originally developed by [Pirchi, Tsukanov et. al. J. Phys. Chem B. 2016, 120, 13065-12075](http://dx.doi.org/10.1371/journal.pone.0160716) in a highly efficent and multithreaded manner, along with functions for posterior analysis with the *Viterbi* algorithm.
`H2MM_C` was designed from the ground up to handle multiparameter models, described in [Harris, P.D., Narducci, A., Gebhardt, C. et al. Multi-parameter photon-by-photon hidden Markov modeling. Nat Commun 13, 1000 (2022).]( https://doi.org/10.1038/s41467-022-28632-x), which also introduced this package.
The API is intended to be user friendly, while still allowing for great flexibility. Suggestions are welcome for ways to improve the code and interface.
## Full Documentation
Full codumentation can be found at [h2mmpythonlib.readthedocs.io](https://h2mmpythonlib.readthedocs.io)
### See Also
This package is offers the basic function to perform H<sup>2</sup>MM, which means that it does not restrict the use of H<sup>2</sup>MM to any particular modality. However this means that much of the analysis specific to smFRET applications is left up to the user.
For those
## Core Features
- H<sup>2</sup>MM model optimization: finding the ideal model given a set of data.
- limit functions to bound the values that a model can take
- *Viterbi* analysis: finds the most likely state path through a set of data given a H<sup>2</sup>MM model
- Reporting of model reliability statistics BIC and ICL
- Simulation functions: Monte Carlo type simulations based on a hidden Markov model
- Useful for verifying results
## Installation
The easiest way to install `H2MM_C` is via pip:
```bash
$ pip install H2MM-C
```
It should be noted that the setup files require a recent version of numpy, and at least Python 3.7.
This is not because the code actually requires features introduced in these verstions, but rather because in Linux, with the numpy version change, the size of certain numpy data-types changed, making compiles with recent versions of numpy incompatible with earler versions. These recent numpy versions do not support Python 3.6.
Therefore, the intrepid programmer can download the code, edit the setup files, and compile with earlier versions of numpy and/or Python, and the code *should* still work.
### Alternative Installation Methods
If for some reason installing from PyPi doesn't work, you can try installing directly from github:
```bash
$ pip install git+https://github.com/harripd/H2MMpythonlib
```
Or, if you download the repository, and have the files stored locally, from the top directory of the project (where the `setup.py` file is):
```bash
$ python setup.py install
```
or if you only want to have it accessible from the current directory, use:
```bash
$ python setup.py build_ext --inplace
```
*Note on some systems the commands are `pip3` and `python3` instead of `pip` and `python` respectively.
### Compatibility
We are trying to provide the broadest degree of compatibility as possible, but there are limitations, and assistance is welcome to expand compatibility as much as possible.
Currently we are using github actions and `cibuildwheel` to generate wheels that are uploaded to PyPi, as well as the sdist archive (`.tar.gz` file), however we are having trouble building certain wheels.
Working wheels:
- Windows wheels
- manylinux wheels
- MacOS X wheels
Currently we do not have wheels for:
- musllinux
For systems we do not have wheels for, it may still be possible to compile from the sdist archive (`.tar.gz` file).
`cibuildwheel` uses the most recent version of numpy. This means that these wheels will generally not work if you have a version of numpy before 1.20.0, and therefore this is given as a minimum version requirement.
However, we have been able to compile working versions with lesser versions of numpy.
Therefore, if you wish to keep your version of numpy, we suggest downloading the github repository, editing the `setup.py` file to support your version of numpy, and compiling with the following commands (run from the base directory where you have your local copy).
```bash
$ python setup.py bdist_wheel sdist
$ pip install *path to wheel file*
```
## Tutorial Code
For a full tutorial on H2MM_C, please see the zenodo repository:
[](https://doi.org/10.5281/zenodo.5566886)
Below is a small sample of tutorial code.
~~~
# H2MM_C accepts numpy arrays, so we mush import numpy
import numpy as np
import H2MM_C
# note: it can be more convenient to use from H2MM_C import * so that it is unnecessary to type H2MM_C. repeatedly
###Data must be defined, so here is some data *made purely for demonstration, and not meant to be realistic*
# lets define sum fake bursts IMPORTANT: this is ENTIRELY FOR DEMONSTRATION, the fake data below is not based on any model
# burst 1
burst_stream1 = np.array([ 0, 1, 0, 1, 0, 2, 0, 1, 2, 0, 1, 2])
burst_times1 = np.array([100,110,112,117,123,124,128,131,139,148,168,182]) # note that burst_stream1 is of the same length as burst_times1
# burst 2
burst_stream2 = np.array([ 2, 1, 0, 0, 2, 1, 0, 1, 0, 0])
burst_times2 = np.array([202,231,340,370,372,381,390,405,410,430]) # note that burst_stream2 is of the same length as burst_times2, but different from burst_stream1 and burst_stream1
# burst N
burst_streamN = np.array([ 0, 2, 1, 2, 0, 2, 1, 0, 1, 2, 1, 0, 1, 0, 0])
burst_timesN = np.array([500,502,511,515,518,522,531,540,544,548,561,570,581,590,593]) # again burst_streamN is the same length as burst_timeN
###The burst arrays must now be put into two lists, one for the photon streams and one for the arrival times
# Now the bursts must be put into lists (real data should have hundreds to thousands of bursts)
# Also, normally, you will be importing the data from a file, so the previous definition of burst_streamN and burst_timesN
# will more likely be done with a file read, or by using your burst-analysis software to split your data into bursts
streams = [burst_stream1, burst_stream2, burst_streamN] # each element is a numpy array of indexes identifying the stream of each photon
times = [burst_times1, burst_times2, burst_timesN] # each element is a numpy array of arrival times, must be in in order
###The above does not invoke H2MM_C (except the import statements), they are purely for demonstrating how to format the data that H2MM_C accepts.
###The rest is actually using H2MM_C, first, an initial model must be defined, (an object of the 'H2MM_C.h2mm_model' class) and then initial model and data can be given to the 'H2MM_C.EM_H2MM_C' for optimization.
# first define the initial arrays for the initial guess
prior = np.array([0.3, 0.7]) # 1D array, the size is the number of states, here we have 2, the array will sum to 1
trans = np.array([[0.99, 0.01],[0.01,0.99]]) # 2D square array, each dimenstion the number of states
obs = np.array([[0.1, 0.4, 0.5],[0.3, 0.2, 0.5]]) # 2D array, number of rows is the number of states, the number of columns is the number of detectors
# Now make the initial model
initial_model = H2MM_C.h2mm_model(prior,trans,obs)
# Run the main algorithm
optimized_model = H2MM_C.EM_H2MM_C(initial_model,streams,times)
# Printing out the main results
print(optimized_model.prior, optimized_model.trans, optimized_model.obs)
# Print out the number of iterations it took to converge
print(optimized_model.niter)
###And viterbi analysis
# doing the fitting
fitting = H2MM_C.viterbi_sort(optimized_model,streams,times)
print(fitting[0]) # print the ICL
# the state path is in index 1
print(fitting[1])
~~~
## Classes
1. `h2mm_model`: the core python extension type of the package: this contains the *H<sup>2</sup>MM* model, which has the core fields:
- nstate: the number of states in the model
- ndet: the number of photon streams in the model
- trans: the transition probability matrix
- obs: the emmision probability matrix, shape nstate x ndet
- prior: the prior probability, shape nstate
- k: the number of free parameters in the model
- loglik: the loglikelihood of the model
- nphot: the number of photons in the dataset that the model is optimized against
- bic: the Baysian Information Criterion of the model
- converged: True if the model reached convergence criterion, False if the optimization stopped due to reaching the maximum number of iterations or if an error occured in the next iteration.
2. `h2mm_limits`: class for bounding the values a model can take, min/max values can be specified for all 3 core arrays (trans, obs, and prior) of an h2mm_model, either as single floats, or full arrays, values are specified as keyword arguments, not specifiying a value for a particular field will mean that field will be unbounded
- min_trans: the minimum values for the trans array (ie the slowest possible transition rate(s) allowed), values on the diagonal will be ignored
- max_trans: the maximum values for the trans array (ie the fastest possible transition rate(s) allowed), values on the diagonal will be ignored
- min_obs: the minimum values for the obs array
- max_obs: the maximum values for the obs array
- min_prior: the minimum value for the prior array
- max_prior: the maximum value for the prior array
## Functions
1. `EM_H2MM_C`: the core function of the package, used to perform model optimizations.
Arguments:
- Initial model : an `h2mm_model` object that will be optimized.
- Streams: a set of burst photon indeces. Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s of photon indeces, must be of integer type, and positive. The indeces will be converted to `unsigned long int` when given to C-code
- Times: a set of burst photon times (macrotimes), Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s. The macrotimes will be converted to `unsigned long long int` when given to C-code. Therefore while floating point arrays are accepted, they are **strongly discouraged**. Must be same length as streams
Returns:
- Optimized model: the `h2mm_model` optimized for the given input data.
2. `H2MM_arr`: calculate the loglik of a bunch of h2mm_model objects at once, but with no optimization. The first agruments can be an h2mm_model, of a list, tuple, or numpy array of h2mm_model objects. The second and third arguments are the same as in EM_H2MM_C
Arguments:
- Models : a `list`, `tuple` or `numpy.ndarray` of `h2mm_model` objects whose *loglikelihood* will be calculated agains the given data.
- Streams: a set of burst photon indeces. Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s of photon indeces, must be of integer type, and positive. The indeces will be converted to `unsigned long int` when given to C-code
- Times: a set of burst photon times (macrotimes), Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s. The macrotimes will be converted to `unsigned long long int` when given to C-code. Therefore while floating point arrays are accepted, they are **strongly discouraged**. Must be same length as streams
Returns:
- Calculated Models: a set of `h2mm_model` objects organized in the same way as Models
3. `viterbi_path`: takes the same inputs as EM_H2MM_C, but the 'h2mm_model' should be optimized through 'EM_H2MM_C' first, returns a tuple the:
Arguments:
- Model : an `h2mm_model` object that will has been optimized against the given data.
- Streams: a set of burst photon indeces. Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s of photon indeces, must be of integer type, and positive. The indeces will be converted to `unsigned long int` when given to C-code
- Times: a set of burst photon times (macrotimes), Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s. The macrotimes will be converted to `unsigned long long int` when given to C-code. Therefore while floating point arrays are accepted, they are **strongly discouraged**. Must be same length as streams
Returns:
- path: the most likely state path
- scale: the posterior probability of each photon
- ll: the loglikelihood of the path for each burst
- icl: the Integrated Complete Likelihood (ICL) of the state path given the model and data, provides an extremum based criterion for selecting the ideal number of states
4. `viterbi_sort`: the viterbi algorithm but with additional parameters included:
Arguments:
- Model : an `h2mm_model` object that will has been optimized against the given data.
- Streams: a set of burst photon indeces. Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s of photon indeces, must be of integer type, and positive. The indeces will be converted to `unsigned long int` when given to C-code
- Times: a set of burst photon times (macrotimes), Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s. The macrotimes will be converted to `unsigned long long int` when given to C-code. Therefore while floating point arrays are accepted, they are **strongly discouraged**. Must be same length as streams
Returns:
- icl: the Integrated Complete Likelihood (ICL) of the state path given the model and data, provides an extremum based criterion for selecting the ideal number of states
- path: the most likely state path
- scale: the posterior probability of each photon
- ll: the loglikelihood of the path for each burst
- burst_type: a binary classification of which states are in each burst
- dwell_mid: returns the lengths of dwells in each state, for dwells with full residence time in the burst
- dwell_beg: same as dwell_mid, except for dwells that begin each burst
- dwell_end: same as dwell_beg, but for ending dwells
- ph_counts: gives counts of photons per stream per dwell
- ph_mid: same as ph_counts, but further sorted as in dwell_mid
- ph_beg: same as ph_counts, but futher sorted as in dwell_beg
- ph_end: same as ph_counts, but futher sorted as in dwell_end
- ph_burst: same as ph_counts, but futher soreted as in dwell_burst
5. `sim_statepath`: from an model, generate a random state path of equally spaced time points
Arguments:
- Model: a `h2mm_model` object to use as the defined parameters of the simulation
- Length: the number of time steps to simulate, defines the number of elements in the ouput array
Returns:
- Path: an array of the states of the system at each time point, based on Monte-Carlo simulation
6. `sim_sparsestatepath`: from a model and a set of sparse times, generate a random state path
Arguments:
- Model: a `h2mm_model` object to use as the defined parameters of the simulation
- Times: a 1D `numpy.ndarray` object of times for a simulated burst
Returns:
- Path: the states of the simulated photons based on the input times
7. `sim_phtraj_from_state`: randomly select photons given a set of states and a model
Arguments:
- Model: a `h2mm_model` object to use as the defined parameters of the simulation.. Note: the model transition rates are ignored, only the emission probability matrix is considered
- states: a 1D `numpy.ndarray` of positive integers, specifying the state of each photon. Note: this state path over-rides any transition probability matrix used in the model
Returns:
- Stream: the indeces (photon indeces) of the simulated photons
8. `sim_phtraj_from_times`: from a model and a set of sparse times, generate a random photon trajectory
Arguments:
- Model: a `h2mm_model` object to use as the defined parameters of the simulation
- Times: a 1D `numpy.ndarray` object of times for a simulated burst
Returns:
- Path:
- Stream: a 1D `numpy.ndarray` of the simulated photon indeces (streams)
## Acknowledgements
Significant advice and help in understanding C code was provided by William Harris, who was also responsible for porting the code to Windows
## License and Copyright
This work falls under the MIT open source lisence
Raw data
{
"_id": null,
"home_page": "https://github.com/harripd/H2MMpythonlib",
"name": "H2MM-C",
"maintainer": "Paul David Harris",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "harripd@gmail.com",
"keywords": "single-molecule FRET",
"author": "Paul David Harris",
"author_email": "harripd@gmail.com",
"download_url": "https://github.com/harripd/H2MMpythonlib",
"platform": null,
"description": "# H2MM_C\n\n[](https://github.com/harripd/H2MMpythonlib/actions)\n[](https://h2mmpythonlib.readthedocs.io/en/latest/?badge=latest)\n\n## Project Desciption\nH2MM_C is a python extension module that implements the H<sup>2</sup>MM algorithm originally developed by [Pirchi, Tsukanov et. al. J. Phys. Chem B. 2016, 120, 13065-12075](http://dx.doi.org/10.1371/journal.pone.0160716) in a highly efficent and multithreaded manner, along with functions for posterior analysis with the *Viterbi* algorithm. \n\n`H2MM_C` was designed from the ground up to handle multiparameter models, described in [Harris, P.D., Narducci, A., Gebhardt, C. et al. Multi-parameter photon-by-photon hidden Markov modeling. Nat Commun 13, 1000 (2022).]( https://doi.org/10.1038/s41467-022-28632-x), which also introduced this package.\n\nThe API is intended to be user friendly, while still allowing for great flexibility. Suggestions are welcome for ways to improve the code and interface.\n\n## Full Documentation\nFull codumentation can be found at [h2mmpythonlib.readthedocs.io](https://h2mmpythonlib.readthedocs.io)\n\n### See Also\n\nThis package is offers the basic function to perform H<sup>2</sup>MM, which means that it does not restrict the use of H<sup>2</sup>MM to any particular modality. However this means that much of the analysis specific to smFRET applications is left up to the user.\n\nFor those \n\n## Core Features\n- H<sup>2</sup>MM model optimization: finding the ideal model given a set of data.\n\t- limit functions to bound the values that a model can take\n- *Viterbi* analysis: finds the most likely state path through a set of data given a H<sup>2</sup>MM model\n\t- Reporting of model reliability statistics BIC and ICL\n- Simulation functions: Monte Carlo type simulations based on a hidden Markov model\n\t- Useful for verifying results\n\n## Installation\n\nThe easiest way to install `H2MM_C` is via pip:\n\n```bash\n$ pip install H2MM-C\n```\nIt should be noted that the setup files require a recent version of numpy, and at least Python 3.7.\nThis is not because the code actually requires features introduced in these verstions, but rather because in Linux, with the numpy version change, the size of certain numpy data-types changed, making compiles with recent versions of numpy incompatible with earler versions. These recent numpy versions do not support Python 3.6.\nTherefore, the intrepid programmer can download the code, edit the setup files, and compile with earlier versions of numpy and/or Python, and the code *should* still work.\n\n### Alternative Installation Methods\n\nIf for some reason installing from PyPi doesn't work, you can try installing directly from github:\n\n```bash\n$ pip install git+https://github.com/harripd/H2MMpythonlib\n```\n\nOr, if you download the repository, and have the files stored locally, from the top directory of the project (where the `setup.py` file is):\n\n```bash\n$ python setup.py install\n```\n\nor if you only want to have it accessible from the current directory, use:\n\n```bash\n$ python setup.py build_ext --inplace\n```\n\n*Note on some systems the commands are `pip3` and `python3` instead of `pip` and `python` respectively.\n\n### Compatibility\n\nWe are trying to provide the broadest degree of compatibility as possible, but there are limitations, and assistance is welcome to expand compatibility as much as possible. \nCurrently we are using github actions and `cibuildwheel` to generate wheels that are uploaded to PyPi, as well as the sdist archive (`.tar.gz` file), however we are having trouble building certain wheels.\n\nWorking wheels:\n\n- Windows wheels\n- manylinux wheels\n- MacOS X wheels\n\nCurrently we do not have wheels for:\n\n- musllinux\n\nFor systems we do not have wheels for, it may still be possible to compile from the sdist archive (`.tar.gz` file). \n`cibuildwheel` uses the most recent version of numpy. This means that these wheels will generally not work if you have a version of numpy before 1.20.0, and therefore this is given as a minimum version requirement. \nHowever, we have been able to compile working versions with lesser versions of numpy. \nTherefore, if you wish to keep your version of numpy, we suggest downloading the github repository, editing the `setup.py` file to support your version of numpy, and compiling with the following commands (run from the base directory where you have your local copy).\n```bash\n$ python setup.py bdist_wheel sdist\n$ pip install *path to wheel file*\n```\n\n## Tutorial Code\nFor a full tutorial on H2MM_C, please see the zenodo repository:\n[](https://doi.org/10.5281/zenodo.5566886)\n\nBelow is a small sample of tutorial code.\n~~~\n\t# H2MM_C accepts numpy arrays, so we mush import numpy\n\timport numpy as np\n\timport H2MM_C\n\t# note: it can be more convenient to use from H2MM_C import * so that it is unnecessary to type H2MM_C. repeatedly\n\n\t###Data must be defined, so here is some data *made purely for demonstration, and not meant to be realistic*\n\n\t# lets define sum fake bursts IMPORTANT: this is ENTIRELY FOR DEMONSTRATION, the fake data below is not based on any model\n\t# burst 1\n\tburst_stream1 = np.array([ 0, 1, 0, 1, 0, 2, 0, 1, 2, 0, 1, 2]) \n\tburst_times1 = np.array([100,110,112,117,123,124,128,131,139,148,168,182]) # note that burst_stream1 is of the same length as burst_times1\n\t\n\t# burst 2\n\tburst_stream2 = np.array([ 2, 1, 0, 0, 2, 1, 0, 1, 0, 0])\n\tburst_times2 = np.array([202,231,340,370,372,381,390,405,410,430]) # note that burst_stream2 is of the same length as burst_times2, but different from burst_stream1 and burst_stream1\n\t\n\t# burst N\n\tburst_streamN = np.array([ 0, 2, 1, 2, 0, 2, 1, 0, 1, 2, 1, 0, 1, 0, 0])\n\tburst_timesN = np.array([500,502,511,515,518,522,531,540,544,548,561,570,581,590,593]) # again burst_streamN is the same length as burst_timeN\n\n\n\t###The burst arrays must now be put into two lists, one for the photon streams and one for the arrival times\n\n\n\t# Now the bursts must be put into lists (real data should have hundreds to thousands of bursts)\n\t# Also, normally, you will be importing the data from a file, so the previous definition of burst_streamN and burst_timesN\n\t# will more likely be done with a file read, or by using your burst-analysis software to split your data into bursts\n\tstreams = [burst_stream1, burst_stream2, burst_streamN] # each element is a numpy array of indexes identifying the stream of each photon\n\ttimes = [burst_times1, burst_times2, burst_timesN] # each element is a numpy array of arrival times, must be in in order\n\n\n\t###The above does not invoke H2MM_C (except the import statements), they are purely for demonstrating how to format the data that H2MM_C accepts.\n\t###The rest is actually using H2MM_C, first, an initial model must be defined, (an object of the 'H2MM_C.h2mm_model' class) and then initial model and data can be given to the 'H2MM_C.EM_H2MM_C' for optimization.\n\n\n\t# first define the initial arrays for the initial guess\n\tprior = np.array([0.3, 0.7]) # 1D array, the size is the number of states, here we have 2, the array will sum to 1\n\ttrans = np.array([[0.99, 0.01],[0.01,0.99]]) # 2D square array, each dimenstion the number of states\n\tobs = np.array([[0.1, 0.4, 0.5],[0.3, 0.2, 0.5]]) # 2D array, number of rows is the number of states, the number of columns is the number of detectors\n\t\n\t# Now make the initial model\n\tinitial_model = H2MM_C.h2mm_model(prior,trans,obs) \n\t\n\t# Run the main algorithm\n\toptimized_model = H2MM_C.EM_H2MM_C(initial_model,streams,times)\n\t\n\t# Printing out the main results\n\tprint(optimized_model.prior, optimized_model.trans, optimized_model.obs)\n\t# Print out the number of iterations it took to converge\n\tprint(optimized_model.niter)\n\n\n\t###And viterbi analysis\n\n\n\t# doing the fitting\n\tfitting = H2MM_C.viterbi_sort(optimized_model,streams,times)\n\t\n\tprint(fitting[0]) # print the ICL\n\t# the state path is in index 1\n\tprint(fitting[1])\n~~~\n\n\n## Classes\n1. `h2mm_model`: the core python extension type of the package: this contains the *H<sup>2</sup>MM* model, which has the core fields:\n\t- nstate: the number of states in the model\n\t- ndet: the number of photon streams in the model\n \t- trans: the transition probability matrix\n\t- obs: the emmision probability matrix, shape nstate x ndet\n\t- prior: the prior probability, shape nstate\n\t- k: the number of free parameters in the model\n\t- loglik: the loglikelihood of the model\n\t- nphot: the number of photons in the dataset that the model is optimized against\n\t- bic: the Baysian Information Criterion of the model\n\t- converged: True if the model reached convergence criterion, False if the optimization stopped due to reaching the maximum number of iterations or if an error occured in the next iteration.\n\n2. `h2mm_limits`: class for bounding the values a model can take, min/max values can be specified for all 3 core arrays (trans, obs, and prior) of an h2mm_model, either as single floats, or full arrays, values are specified as keyword arguments, not specifiying a value for a particular field will mean that field will be unbounded\n\t- min_trans: the minimum values for the trans array (ie the slowest possible transition rate(s) allowed), values on the diagonal will be ignored\n\t- max_trans: the maximum values for the trans array (ie the fastest possible transition rate(s) allowed), values on the diagonal will be ignored\n\t- min_obs: the minimum values for the obs array\n\t- max_obs: the maximum values for the obs array\n\t- min_prior: the minimum value for the prior array\n\t- max_prior: the maximum value for the prior array\n\n## Functions\n\n1. `EM_H2MM_C`: the core function of the package, used to perform model optimizations.\n \n Arguments:\n - Initial model : an `h2mm_model` object that will be optimized.\n - Streams: a set of burst photon indeces. Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s of photon indeces, must be of integer type, and positive. The indeces will be converted to `unsigned long int` when given to C-code\n - Times: a set of burst photon times (macrotimes), Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s. The macrotimes will be converted to `unsigned long long int` when given to C-code. Therefore while floating point arrays are accepted, they are **strongly discouraged**. Must be same length as streams\n \n Returns:\n\t- Optimized model: the `h2mm_model` optimized for the given input data.\n\n2. `H2MM_arr`: calculate the loglik of a bunch of h2mm_model objects at once, but with no optimization. The first agruments can be an h2mm_model, of a list, tuple, or numpy array of h2mm_model objects. The second and third arguments are the same as in EM_H2MM_C\n \n Arguments:\n - Models : a `list`, `tuple` or `numpy.ndarray` of `h2mm_model` objects whose *loglikelihood* will be calculated agains the given data.\n - Streams: a set of burst photon indeces. Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s of photon indeces, must be of integer type, and positive. The indeces will be converted to `unsigned long int` when given to C-code\n - Times: a set of burst photon times (macrotimes), Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s. The macrotimes will be converted to `unsigned long long int` when given to C-code. Therefore while floating point arrays are accepted, they are **strongly discouraged**. Must be same length as streams\n \n Returns:\n\t- Calculated Models: a set of `h2mm_model` objects organized in the same way as Models\n \n3. `viterbi_path`: takes the same inputs as EM_H2MM_C, but the 'h2mm_model' should be optimized through 'EM_H2MM_C' first, returns a tuple the:\n Arguments:\n - Model : an `h2mm_model` object that will has been optimized against the given data.\n - Streams: a set of burst photon indeces. Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s of photon indeces, must be of integer type, and positive. The indeces will be converted to `unsigned long int` when given to C-code\n - Times: a set of burst photon times (macrotimes), Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s. The macrotimes will be converted to `unsigned long long int` when given to C-code. Therefore while floating point arrays are accepted, they are **strongly discouraged**. Must be same length as streams\n \n Returns:\n\t- path: the most likely state path\n\t- scale: the posterior probability of each photon\n\t- ll: the loglikelihood of the path for each burst\n\t- icl: the Integrated Complete Likelihood (ICL) of the state path given the model and data, provides an extremum based criterion for selecting the ideal number of states\n\n4. `viterbi_sort`: the viterbi algorithm but with additional parameters included:\n Arguments:\n - Model : an `h2mm_model` object that will has been optimized against the given data.\n - Streams: a set of burst photon indeces. Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s of photon indeces, must be of integer type, and positive. The indeces will be converted to `unsigned long int` when given to C-code\n - Times: a set of burst photon times (macrotimes), Must be given as a `list`, `tuple` or 1-D object `numpy.ndarray` of 1D `numpy.ndarray`s. The macrotimes will be converted to `unsigned long long int` when given to C-code. Therefore while floating point arrays are accepted, they are **strongly discouraged**. Must be same length as streams\n \n Returns:\n\t- icl: the Integrated Complete Likelihood (ICL) of the state path given the model and data, provides an extremum based criterion for selecting the ideal number of states\n\t- path: the most likely state path\n\t- scale: the posterior probability of each photon\n\t- ll: the loglikelihood of the path for each burst\n\t- burst_type: a binary classification of which states are in each burst\n\t- dwell_mid: returns the lengths of dwells in each state, for dwells with full residence time in the burst\n\t- dwell_beg: same as dwell_mid, except for dwells that begin each burst\n\t- dwell_end: same as dwell_beg, but for ending dwells\n\t- ph_counts: gives counts of photons per stream per dwell\n\t- ph_mid: same as ph_counts, but further sorted as in dwell_mid\n\t- ph_beg: same as ph_counts, but futher sorted as in dwell_beg\n\t- ph_end: same as ph_counts, but futher sorted as in dwell_end\n\t- ph_burst: same as ph_counts, but futher soreted as in dwell_burst\n\n5. `sim_statepath`: from an model, generate a random state path of equally spaced time points\n \n Arguments:\n - Model: a `h2mm_model` object to use as the defined parameters of the simulation\n - Length: the number of time steps to simulate, defines the number of elements in the ouput array\n \n Returns:\n - Path: an array of the states of the system at each time point, based on Monte-Carlo simulation\n\n6. `sim_sparsestatepath`: from a model and a set of sparse times, generate a random state path\n \n Arguments:\n - Model: a `h2mm_model` object to use as the defined parameters of the simulation\n - Times: a 1D `numpy.ndarray` object of times for a simulated burst\n \n Returns:\n - Path: the states of the simulated photons based on the input times\n\n7. `sim_phtraj_from_state`: randomly select photons given a set of states and a model\n Arguments:\n - Model: a `h2mm_model` object to use as the defined parameters of the simulation.. Note: the model transition rates are ignored, only the emission probability matrix is considered\n - states: a 1D `numpy.ndarray` of positive integers, specifying the state of each photon. Note: this state path over-rides any transition probability matrix used in the model\n \n Returns:\n - Stream: the indeces (photon indeces) of the simulated photons\n\n8. `sim_phtraj_from_times`: from a model and a set of sparse times, generate a random photon trajectory\n\n Arguments:\n - Model: a `h2mm_model` object to use as the defined parameters of the simulation\n - Times: a 1D `numpy.ndarray` object of times for a simulated burst\n \n Returns:\n - Path: \n - Stream: a 1D `numpy.ndarray` of the simulated photon indeces (streams) \n\n## Acknowledgements\nSignificant advice and help in understanding C code was provided by William Harris, who was also responsible for porting the code to Windows\n## License and Copyright\nThis work falls under the MIT open source lisence\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "C level implementation of H2MM algorithm by Pirchi. 2016",
"version": "1.0.2",
"split_keywords": [
"single-molecule",
"fret"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f1ec26de83b7fbaa89298f29ee1ede47bc95ba4ff5cfaf2a7d3fb8783398b8f",
"md5": "f9387dbb8e37d0a0b4131d33108910a7",
"sha256": "b29cc1798f794420c2c90847866b58f45dd5c19599f37e75be222f2933433bcf"
},
"downloads": -1,
"filename": "H2MM_C-1.0.2-cp310-cp310-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "f9387dbb8e37d0a0b4131d33108910a7",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.7",
"size": 460431,
"upload_time": "2023-01-24T08:07:09",
"upload_time_iso_8601": "2023-01-24T08:07:09.794104Z",
"url": "https://files.pythonhosted.org/packages/8f/1e/c26de83b7fbaa89298f29ee1ede47bc95ba4ff5cfaf2a7d3fb8783398b8f/H2MM_C-1.0.2-cp310-cp310-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a11146f9058e8629e0edb37f49059fd3dbc5b72dd34b40b45b9e7fba5be2b1c2",
"md5": "162de0ca5ce0ebe504bda06a151d26a9",
"sha256": "6b818c63bc31ad36d8c1f5cf3ababc0993f39106e4564a86997ea087c1389327"
},
"downloads": -1,
"filename": "H2MM_C-1.0.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "162de0ca5ce0ebe504bda06a151d26a9",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.7",
"size": 2254851,
"upload_time": "2023-01-24T08:07:53",
"upload_time_iso_8601": "2023-01-24T08:07:53.549080Z",
"url": "https://files.pythonhosted.org/packages/a1/11/46f9058e8629e0edb37f49059fd3dbc5b72dd34b40b45b9e7fba5be2b1c2/H2MM_C-1.0.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6c0291480071f02ddb7ffcc02727f7635720379eee7752305e806f8250718442",
"md5": "28c1bc1495e340afd93c1417d5e514a8",
"sha256": "18f657868a995a018fd9da82357e53b877b0f541a53e80ba609c2fe26df4e71d"
},
"downloads": -1,
"filename": "H2MM_C-1.0.2-cp310-cp310-win_amd64.whl",
"has_sig": false,
"md5_digest": "28c1bc1495e340afd93c1417d5e514a8",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.7",
"size": 280679,
"upload_time": "2023-01-24T08:08:00",
"upload_time_iso_8601": "2023-01-24T08:08:00.714892Z",
"url": "https://files.pythonhosted.org/packages/6c/02/91480071f02ddb7ffcc02727f7635720379eee7752305e806f8250718442/H2MM_C-1.0.2-cp310-cp310-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "803cbbe65d2692f60095a2402c6990c732fe5802421729cd99b2820d1c812120",
"md5": "e6044caafe2caf493eb3fcbae1eb5ecf",
"sha256": "9fe2b9c358d8c028af014751d697e581ae603039ebe54babd69c151f8ae5a229"
},
"downloads": -1,
"filename": "H2MM_C-1.0.2-cp311-cp311-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "e6044caafe2caf493eb3fcbae1eb5ecf",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.7",
"size": 457988,
"upload_time": "2023-01-24T08:08:11",
"upload_time_iso_8601": "2023-01-24T08:08:11.746333Z",
"url": "https://files.pythonhosted.org/packages/80/3c/bbe65d2692f60095a2402c6990c732fe5802421729cd99b2820d1c812120/H2MM_C-1.0.2-cp311-cp311-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5963dde5e671d13a43d65496103bf2e3cdaa87528bc7b23a142b6c0049dbdd2b",
"md5": "65fcd3fba568a33ae887fe7a5e96b369",
"sha256": "9b0567ecaef8049237b6d5cebdd83049ca4a173714229976babf531f2f543c18"
},
"downloads": -1,
"filename": "H2MM_C-1.0.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "65fcd3fba568a33ae887fe7a5e96b369",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.7",
"size": 2495970,
"upload_time": "2023-01-24T08:09:00",
"upload_time_iso_8601": "2023-01-24T08:09:00.024549Z",
"url": "https://files.pythonhosted.org/packages/59/63/dde5e671d13a43d65496103bf2e3cdaa87528bc7b23a142b6c0049dbdd2b/H2MM_C-1.0.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "997edec2713c9a1c75bfea16c5406e4fe9ebf6f2609383d70c5d95c4317438b8",
"md5": "a969334916c5fe51eed9a063ced4e75f",
"sha256": "900757dd08991e25132e5de22ee21343e01d9f437ab9a55511af9efb12577cb9"
},
"downloads": -1,
"filename": "H2MM_C-1.0.2-cp311-cp311-win_amd64.whl",
"has_sig": false,
"md5_digest": "a969334916c5fe51eed9a063ced4e75f",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.7",
"size": 280728,
"upload_time": "2023-01-24T08:09:07",
"upload_time_iso_8601": "2023-01-24T08:09:07.614642Z",
"url": "https://files.pythonhosted.org/packages/99/7e/dec2713c9a1c75bfea16c5406e4fe9ebf6f2609383d70c5d95c4317438b8/H2MM_C-1.0.2-cp311-cp311-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "22e7551ea1a4888c381f05574f2aa11e9479fec844782a6891a7f476eae35980",
"md5": "a058e85fef6e4a73bfb84758c59f2554",
"sha256": "35d9be0d8268976180e4a1bb4bd6dd4d4907d2afbcfb8fe55e74c6ed3551acc9"
},
"downloads": -1,
"filename": "H2MM_C-1.0.2-cp37-cp37m-macosx_10_9_x86_64.whl",
"has_sig": false,
"md5_digest": "a058e85fef6e4a73bfb84758c59f2554",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 438181,
"upload_time": "2023-01-24T08:09:17",
"upload_time_iso_8601": "2023-01-24T08:09:17.958882Z",
"url": "https://files.pythonhosted.org/packages/22/e7/551ea1a4888c381f05574f2aa11e9479fec844782a6891a7f476eae35980/H2MM_C-1.0.2-cp37-cp37m-macosx_10_9_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "81743a3294b6094a6ad4c77d9611e82772ea67a01f9d9e01e6f107e478b0d8c4",
"md5": "92a9a378113180023caa37a285390d3a",
"sha256": "4b19d5dc52ad59ce0258c2c4d4bfa3997da2f4da4c166a0e24ac8e3934a92b3b"
},
"downloads": -1,
"filename": "H2MM_C-1.0.2-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "92a9a378113180023caa37a285390d3a",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.7",
"size": 2057867,
"upload_time": "2023-01-24T08:09:57",
"upload_time_iso_8601": "2023-01-24T08:09:57.962026Z",
"url": "https://files.pythonhosted.org/packages/81/74/3a3294b6094a6ad4c77d9611e82772ea67a01f9d9e01e6f107e478b0d8c4/H2MM_C-1.0.2-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-24 08:07:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "harripd",
"github_project": "H2MMpythonlib",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "h2mm-c"
}
JSON
