:py:mod:`change_point` ====================== .. py:module:: change_point .. autoapi-nested-parse:: Module for handling analysis of change points and creation of consequent levels. Based on 'Detection of Intensity Change Points in Time-Resolved Single-Molecule Measurements' from Watkins nad Yang, J. Phys. Chem. B 2005, 109, 617-628 (http://pubs.acs.org/doi/abs/10.1021/jp0467548) Joshua Botha University of Pretoria 2019 Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: change_point.ParticleMicrotimesSubset change_point.ChangePoints change_point.Err change_point.Level change_point.TauData change_point.ChangePointAnalysis Functions ~~~~~~~~~ .. autoapisummary:: change_point.main Attributes ~~~~~~~~~~ .. autoapisummary:: change_point.__docformat__ change_point.logger .. py:data:: __docformat__ :value: "'NumPy'" .. py:data:: logger :value: "'change_point'" .. py:class:: ParticleMicrotimesSubset(particle: smsh5.Particle, start_ind: int, end_ind: int) A container for a custom list that accesses a subset of a H5 dataset .. py:property:: _micro_dataset .. py:attribute:: _particle .. py:attribute:: _start_ind .. py:attribute:: _end_ind .. py:method:: __len__() .. py:method:: _get_ind(ind) -> int .. py:method:: __getitem__(i) .. py:method:: __iter__() .. py:method:: __repr__() .. py:method:: __eq__(other) .. py:class:: ChangePoints(particle, confidence=None, run_levels: bool = None) Contains all the attributes to describe the found change points in an analysed particles. .. py:property:: has_levels .. py:property:: levels :type: List[Level] .. py:property:: num_levels .. py:property:: level_ints .. py:property:: level_dwelltimes .. py:property:: cpa_has_run .. py:property:: confidence .. py:property:: cpt_inds .. py:property:: num_cpts .. py:property:: conf_regions .. py:attribute:: bursts_deleted :value: 'None' .. py:attribute:: _particle .. py:attribute:: uuid .. py:attribute:: _cpa .. py:attribute:: has_burst :value: 'False' .. py:attribute:: burst_levels :value: 'None' .. py:method:: run_cpa(all_sums: generate_sums.CPSums, confidence=None, run_levels=None, end_time_s=None) Run change point analysis. Performs the change point analysis on the parent particle object with the confidence either provided as an argument here or in the __init__ method. :param confidence: Must be 0.99, 0.95, 0.90 or 0.69. :type confidence: Confidence level with which to resolve the change points with. :param run_levels: parent particle object by running its add_levels method. :type run_levels: If true the change point analysis will be used to add a list of levels to the :param end_time_s: .. py:method:: calc_mean_std() .. py:method:: check_burst() .. py:method:: remove_bursts() .. py:method:: restore_bursts() .. py:class:: Err(lower: float, upper: float) .. py:attribute:: lower .. py:attribute:: upper .. py:attribute:: sum .. py:class:: Level(particle: smsh5.Particle, particle_ind: int, level_inds: Tuple[int, int], int_p_s: float = None, group_ind: int = None) Defines the start, end and intensity of a single level. .. py:property:: abs_times .. py:property:: times_s .. py:property:: dwell_time_s .. py:attribute:: _particle .. py:attribute:: particle_ind .. py:attribute:: level_inds .. py:attribute:: num_photons .. py:attribute:: times_ns .. py:attribute:: dwell_time_ns .. py:attribute:: microtimes .. py:attribute:: group_ind :value: 'None' .. py:attribute:: histogram :value: 'None' .. py:class:: TauData(confidence=None) Loads and stores the tau_a and tau_b files from text files for specific confidence and stores as attributes. .. py:method:: get_tau_a(num_data_points=None) Get tau_a value for n = num_data_points. Retrieve the a tau data for the given number of data points. :param num_data_points: Number of data points that the tau data is needed for. **Note**, only use values up to and smaller than 1000 for accuracy. :return: tau_a value :rtype: float .. py:method:: get_tau_b(num_data_points=None) Get tau_a value for n = num_data_points. Retrieve the a tau data for the given number of data points. :param num_data_points: Number of data points that the tau data is needed for. **Note**, only use values up to and smaller than 1000 for accuracy. :return: tau_a value :rtype: float .. py:class:: ChangePointAnalysis(particle: smsh5.Particle = None, confidence=None) Perform analysis of particle abstimes data to resolve change points. .. py:property:: _abstimes .. py:property:: _microtimes .. py:property:: level_ints .. py:property:: level_dwelltimes .. py:attribute:: _particle :value: 'None' .. py:attribute:: has_run :value: 'False' .. py:attribute:: end_at_photon :value: 'None' .. py:attribute:: num_photons .. py:attribute:: confidence :value: 'None' .. py:attribute:: cpt_inds .. py:attribute:: conf_regions :value: '[]' .. py:attribute:: _finding :value: 'False' .. py:attribute:: found_cpts :value: 'False' .. py:attribute:: num_cpts :value: 'None' .. py:attribute:: has_levels :value: 'False' .. py:attribute:: levels :value: 'None' .. py:attribute:: num_levels :value: 'None' .. py:attribute:: _i :value: 'None' .. py:attribute:: settings .. py:method:: load_settings() .. py:method:: reset(confidence: float = None) .. py:method:: __weighted_likelihood_ratio(all_sums: generate_sums.CPSums, seg_inds=None) -> Tuple[bool, Optional[int]] Calculates the Weighted & Standardised Likelihood ratio and detects the possible change point. Based on 'Detection of Intensity Change Points in Time-Resolved Single-Molecule Measurements' from Watkins nad Yang, J. Phys. Chem. B 2005, 109, 617-628 (http://pubs.acs.org/doi/abs/10.1021/jp0467548) If the possible change point is greater than the tau_a value for the corresponding confidence interval and number of data points the detected change points, it's confidence region (as defined by tau_b), and the corresponding uncertainty in time is added to this instance of ChangePointAnalysis. :param seg_inds: Segment indexes (start, end). :type seg_inds: (int, int), optional :returns: * **cpt_found** (*bool*) -- True if a change point was detected. * **cpt** (*int, Optional*) -- The index of the change point, if one was detected. .. py:method:: _next_seg_ind(prev_seg_inds: Tuple[int, int] = None, side: str = None, rights_cpt: int = None) -> Tuple[int, int] Calculates the next segments indexes. Uses the indexes of the previous segment, as well as the latest change point to calculate the index values of the next segment. See code2flow.com for flow diagram of if statements. https://code2flow.com/svLn85 :param prev_seg_inds: Contains the start and end of the previous segment (start, end) :type prev_seg_inds: (int, int) :param side: If a change point was detected in the previous segment choose left or right of it. Possible values are 'left' or 'right'. :type side: str, Optional :param rights_cpt: The index of the change point for the right leg (the next_seg_start if side = 'left'). :type rights_cpt: int, Optional :returns: **next_seg** -- The next segments indexes. :rtype: (int, int) .. py:method:: _find_all_cpts(all_sums: generate_sums.CPSums, _seg_inds: Tuple[int, int] = None, _side: str = None, _right_cpt: int = None) Find all change points in particle. Recursive function that finds all change points that meets the confidence criteria. .. note:: The first call doesn't need to be called with any parameters. .. note:: The top level assigns the number of detected change points to the .num_cpts attribute of this instance of ChangePointAnalysis. :param _right_cpt: The index of the change point for the right leg (the next_seg_start if side = 'left'). :type _right_cpt: int, Optional :param _seg_inds: The index of the segment that is to be searched. Calculated by _next_seg_ind method. :type _seg_inds: (int, int), Optional :param _side: Determines current segment is left or right of a previously detected change point. Valid values are 'left' or 'right'. :type _side: str, Optional .. py:method:: define_levels(remove_prev: bool = None) -> None Creates a list of levels as defined by the detected change points. Uses the detected change points to create a list of Level instances that contain attributes that define each resolved level. This method populate the .levels attribute of the parent particle instance by using its add_levels method. :param remove_prev: If true, previous levels will be removed. :type remove_prev: bool, Optional .. py:method:: run_cpa(all_sums: generate_sums.CPSums, confidence=None, end_time_s=None) Runs the change point analysis. If the ChangePointAnalysis wasn't initialised with a confidence interval, or if the analysis is to be rerun with a new confidence interval, this method starts said analysis. :param end_time_s: Time at which to end analysis. If not provided the whole trace will be used. :type end_time_s: float :param confidence: Confidence interval. Valid values are 0.99, 0.95, 0.90 and 0.69. :type confidence: float :returns: * **num_cpts** (*int*) -- Number of change points detected * **cpt_inds** (*ndarray*) -- Indexes of change points * **conf_regions** (*list(tuple(int, int))*) -- Index region corresponding to confidence interval * **dt_uncertainty** (*ndarray*) -- Array of uncertainty in time corresonding to confidence interval .. py:function:: main() Tests ChangePoints init