14.1.6. Event Processing

14.1.6.1. mosaic.process.adept2State module

digraph inheritance1604056825 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "adept2State.adept2State" [URL="#mosaic.process.adept2State.adept2State",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Analyze an event that is characteristic of PEG blockades. This method includes system "]; "metaEventProcessor.metaEventProcessor" -> "adept2State.adept2State" [arrowsize=0.5,style="setlinewidth(0.5)"]; "adept2State.datblock" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Smart data block that holds time-series data and keeps track"]; "metaEventProcessor.metaEventProcessor" [URL="mosaic.meta.html#mosaic.process.metaEventProcessor.metaEventProcessor",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip=".. warning:: |metaclass|"]; }

A class that extends metaEventProcessing to implement the step response algorithm from []

Created:

4/18/2013

Author:

Arvind Balijepalli <arvind.balijepalli@nist.gov>

License:

See LICENSE.TXT

ChangeLog:

06/28/16 AB Upgrade lmfit to > 0.9 (https://lmfit.github.io/lmfit-py/whatsnew.html#whatsnew-090-label)
03/30/16 AB Change UnlinkRCConst to LinkRCConst to avoid double negatives.
12/09/15 KB Added Windows specific optimizations
8/24/15 AB Rename algorithm to ADEPT 2 State.
7/23/15 JF Added a new test to reject RC Constants <=0
6/24/15 AB Added an option to unlink the RC constants in stepResponseAnalysis.
11/7/14 AB Error codes describing event rejection are now more specific.
11/5/14 AB Fixed a bug in the event fitting logic that prevented
long events from being correctly analyzed.
5/17/14 AB Modified md interface functions for metaMDIO support
2/16/14 AB Added new metadata field, ‘AbsEventStart’ to track
global time of event start to allow capture rate estimation.
6/20/13 AB Added an additional check to reject events
with blockade depths > BlockRejectRatio (default: 0.8)
4/18/13 AB Initial version
class mosaic.process.adept2State.adept2State(icurr, icurrU, Fs, **kwargs)[source]

Bases: metaEventProcessor

Analyze an event that is characteristic of PEG blockades. This method includes system information in the analysis, specifically the filtering effects (throught the RC constant) of either amplifiers or the membrane/nanopore complex. The analysis generates several parameters that are stored as metadata including:

  1. Blockade depth: the ratio of the open channel current to the blocked current

  2. Residence time: the time the molecule spends inside the pore

  3. Tau: the RC constant of the response to a step input (e.g. the entry or exit of the molecule into or out of the nanopore).

Keyword Args:
In addition to metaEventProcessor args,

  • FitTol : Tolerance value for the least squares algorithm that controls the convergence of the fit (Default: 1e-7).

  • FitIters : Maximum number of iterations before terminating the fit (Default: 50000).

  • LinkRCConst : When True, the RC constants associated with each state in the fit function are varied together. (Default: True)

Errors:

When an event cannot be analyzed, the blockade depth, residence time and rise time are set to -1.

formatsettings()[source]

Return a formatted string of settings for display

mdAveragePropertiesList()[source]

Return a list of meta-data properties that will be averaged and displayed at the end of a run.

14.1.6.2. mosaic.process.adept module

digraph inheritance9935b48c28 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "adept.InvalidEvent" [URL="#mosaic.process.adept.InvalidEvent",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top"]; "adept.adept" [URL="#mosaic.process.adept.adept",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Analyze a multi-step event that contains two or more states. This method includes system "]; "metaEventProcessor.metaEventProcessor" -> "adept.adept" [arrowsize=0.5,style="setlinewidth(0.5)"]; "metaEventProcessor.metaEventProcessor" [URL="mosaic.meta.html#mosaic.process.metaEventProcessor.metaEventProcessor",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip=".. warning:: |metaclass|"]; }

Analyze a multi-step event

Created:

4/18/2013

Author:

Arvind Balijepalli <arvind.balijepalli@nist.gov>

License:

See LICENSE.TXT

ChangeLog:

06/28/16 AB Upgrade lmfit to > 0.9 (https://lmfit.github.io/lmfit-py/whatsnew.html#whatsnew-090-label)
05/27/16 AB Added warnings when the reduced chi squared is not a number and if the fit parameters are unchanged from the initial guess values.
05/22/16 JF Added new test to reject BD < 0 or BD > 1, improved readability of error tests.
03/30/16 AB Change UnlinkRCConst to LinkRCConst to avoid double negatives.
3/16/16 AB Migrate InitThreshold setting to CUSUM StepSize.
2/22/16 AB Use CUSUM to estimate intial guesses in ADEPT for long events.
2/20/16 AB Format settings log.
12/09/15 KB Added Windows specific optimizations
8/24/15 AB Rename algorithm to ADEPT.
8/02/15 JF Added a new test to reject RC Constants <=0
4/12/15 AB Refactored code to improve reusability.
3/20/15 AB Added a maximum event length setting (MaxEventLength) that automatically rejects events longer than the specified value.
3/20/15 AB Added a new metadata column (mdStateResTime) that saves the residence time of each state to the database.
3/6/15 AB Added a new test for negative event delays
3/6/15 JF Added MinStateLength to output log
3/5/15 AB Updated initial state determination to include a minumum state length parameter (MinStateLength).
Initial state estimates now utilize gradient information for improved state identification.
1/7/15 AB Save the number of states in an event to the DB using the mdNStates column
12/31/14 AB Changed multi-state function to include a separate tau for
each state following Balijepalli et al, ACS Nano 2014.
12/30/14 JF Removed min/max constraint on tau
11/7/14 AB Error codes describing event rejection are now more specific.
11/6/14 AB Fixed a bug in the event fitting logic that prevents the
analysis of long states.
8/21/14 AB Added AbsEventStart and BlockDepth (constructed from mdCurrentStep
and mdOpenChCurrent) metadata.
5/17/14 AB Modified md interface functions for metaMDIO support
9/26/13 AB Initial version
exception mosaic.process.adept.InvalidEvent[source]

Bases: Exception

class mosaic.process.adept.adept(icurr, icurrU, Fs, **kwargs)[source]

Bases: metaEventProcessor

Analyze a multi-step event that contains two or more states. This method includes system information in the analysis, specifically the filtering effects (through the RC constant) of either amplifiers or the membrane/nanopore complex. The analysis generates several parameters that are stored as metadata including:

  1. Blockade depth: the ratio of the open channel current to the blocked current

  2. Residence time: the time the molecule spends inside the pore

  3. Tau: the RC constant of the response to a step input (e.g. the entry or exit of the molecule into or out of the nanopore).

Keyword Args:
In addition to metaEventProcessor args,

  • StepSize : The multiple of the standard deviations considered significant to dtecting an event (default: 3.0).

  • MinStateLength : minimum number of data points required to assign a state within an event (default: 4)

  • MaxEventLength : maximum length (in data points) of events that will be processed (default: 10000)

  • FitTol : fit tolerance for convergence (default: 1.e-7)

  • FitIters : maximum fit iterations (default: 5000)

  • LinkRCConst : When True, the RC constants associated with each state in the fit function are varied together. (Default: True)

Errors:

When an event cannot be analyzed, all metadata are set to -1.

formatsettings()[source]

Return a formatted string of settings for display

mdAveragePropertiesList()[source]

Return a list of meta-data properties that will be averaged and displayed at the end of a run.

14.1.6.3. mosaic.process.cusumPlus module

digraph inheritance6c5c146ee6 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "cusumPlus.InvalidEvent" [URL="#mosaic.process.cusumPlus.InvalidEvent",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top"]; "cusumPlus.cusumPlus" [URL="#mosaic.process.cusumPlus.cusumPlus",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="CUSUM+ will detect jumps that are smaller than `StepSize`, but they will have to be sustained longer. Threshold can be thought of, very roughly, as proportional to the length of time a subevent must be sustained for it to be detected. The algorithm will adjust the actual threshold used on a per-event basis in order to minimize false positive detection of current jumps This algorithm is based on code used in OpenNanopore, which you can read about here: http://pubs.rsc.org/en/Content/ArticleLanding/2012/NR/c2nr30951c#!divAbstract"]; "metaEventProcessor.metaEventProcessor" -> "cusumPlus.cusumPlus" [arrowsize=0.5,style="setlinewidth(0.5)"]; "cusumPlus.datblock" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Smart data block that holds a time-series of data and keeps track"]; "metaEventProcessor.metaEventProcessor" [URL="mosaic.meta.html#mosaic.process.metaEventProcessor.metaEventProcessor",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip=".. warning:: |metaclass|"]; }

Analyze a multi-step event with the CUSUM+ algorithm. Implements a modified version of the CUSUM algorithm (used by OpenNanopore for example) in MOSAIC. This approach sacrifices including system information in the analysis in favor of much faster fitting of single- and multi-level events.

Created:

2/10/2015

Author:

Kyle Briggs <kbrig035@uottawa.ca>

License:

See LICENSE.TXT

ChangeLog:

11/15/19 JR Updated output: calculates adn includes blockade standard deviation; simplified tab in code
6/3/17 AB Updated docstring.
8/24/15 AB Rename algorithm to CUSUM+
3/20/15 AB Added a new metadata column (mdStateResTime) that saves the residence time of each state to the database.
3/18/15 KB Implemented rise time skipping
3/17/15 KB Implemented adaptive threshold
2/12/15 AB Updated metadata representation to be consistent with stepResponseAnalysis and multiStateAnalysis
2/10/15 KB Initial version
exception mosaic.process.cusumPlus.InvalidEvent[source]

Bases: Exception

class mosaic.process.cusumPlus.cusumPlus(icurr, icurrU, Fs, **kwargs)[source]

Bases: metaEventProcessor

CUSUM+ will detect jumps that are smaller than StepSize, but they will have to be sustained longer. Threshold can be thought of, very roughly, as proportional to the length of time a subevent must be sustained for it to be detected. The algorithm will adjust the actual threshold used on a per-event basis in order to minimize false positive detection of current jumps This algorithm is based on code used in OpenNanopore, which you can read about here: http://pubs.rsc.org/en/Content/ArticleLanding/2012/NR/c2nr30951c#!divAbstract

Some known issues with CUSUM+:

  1. If the duration of a sub-event is shorter than than the MinLength parameter, CUSUM+ will be unable to detect it. CUSUM+ will not detect events within MinLength of a previous event.

  2. CUSUM assumes an instantaneous transition between current states. As a result, if the RC rise time of the system is large, CUSUM+ can trigger and detect intermediate states during the change time. This can be avoided by choosing a number of samples to skip equal to about 2-5RC.

  3. As a consequence of using a statistical t-test, CUSUM can have false positives. The algorithm has an adaptive threshold that tries to minimize the chances of this happening while maintaining good sensitivity (expected number of false positives within an event is less than 1).

Keyword Args:
In addition to metaEventProcessor args,

  • StepSize : The number of baseline standard deviations are considered significant (3 is usually a good starting point).

  • MinThreshold : One of two sensitivity parameters (lower is more sensitive). A good starting point is to set MinThreshold equal to StepSize.

  • MaxThreshold : One of two sensitivity parameters (lower is more sensitive). Set MaxThreshold about 3x higher than MinThreshold.

  • MinLength : The number of samples to skip after detecting a jump, in order to avoid triggering during the rise time and returning an artificially high number of states. This number of points is also skipped when averaging levels. About 4 times the RC constant of the system is a good starting value.

Errors:

When an event cannot be analyzed, all metadata are set to -1.

To use it requires four settings:

"cusumPlus": {
        "StepSize": 3.0, 
        "MinThreshold": 3.0,
        "MaxThreshold": 10.0,
        "MinLength" : 10,
}
formatsettings()[source]

Return a formatted string of settings for display

mdAveragePropertiesList()[source]

Return a list of meta-data properties that will be averaged and displayed at the end of a run.