python-microscopy 25.11.20__cp313-cp313-win_amd64.whl

PYME/Analysis/piecewiseMapping.py

@@ -0,0 +1,304 @@
+#!/usr/bin/python
+
+##################
+# piecewiseMapping.py
+#
+# Copyright David Baddeley, 2009
+# d.baddeley@auckland.ac.nz
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+##################
+
+import numpy as np
+
+def times_to_frames(t, events, mdh):
+    """
+    Use events and metadata to convert time-stamps to frame numbers
+
+    Parameters
+    ----------
+    t: ndarray
+        times [seconds since the epoch] to map to frame numbers
+    events: ndarray
+        TODO - if events-related type fixing goes through, use events helpers to accept list here as well
+    mdh: PYME.IO.MetaDataHandler
+        Metadata handler with 'Camera.CycleTime' and 'StartTime' entries
+
+    Returns
+    -------
+    fr: ndarray
+        array of frame numbers corresponding to `t` input
+    """
+    cycTime = mdh.getEntry('Camera.CycleTime')
+    startTime = mdh.getEntry('StartTime')
+
+    #se = array([('0', 'start', startTime)], dtype=events.dtype)
+    se = np.empty(1, dtype=events.dtype)
+    se['EventName'] = 'start'
+    se['EventDescr'] = '0'
+    se['Time'] = startTime
+
+    #sf = array([('%d' % iinfo(int32).max, 'end', startTime + 60*60*24*7)], dtype=events.dtype)
+    sf = np.empty(1, dtype=events.dtype)
+    sf['EventName'] = 'end'
+    sf['EventDescr'] = '%d' % np.iinfo(np.int32).max
+    sf['Time'] = startTime + 60*60*24*7
+
+    #get events corresponding to aquisition starts
+    startEvents = np.hstack((se, events[events['EventName'] == b'StartAq'], sf))
+    
+    ### hack to fix timing where there are long protocol init tasks (pre pr #948)
+    protocol_task_events = events[(events['EventName'] == b'ProtocolTask')]
+    try:
+        last_init_event_idx = -1
+        for j, s in enumerate(protocol_task_events['EventDescr']):
+            try:
+                fnum = int(s.decode('ascii').split(',')[0])
+                if fnum == -1:
+                    last_init_event_idx = j
+            except ValueError:
+                pass
+        
+        #print(last_init_event_idx, protocol_task_events[last_init_event_idx])
+        
+        if last_init_event_idx > -1:
+            fake_start_ev = np.empty(1, dtype=events.dtype)
+        
+            fake_start_ev['EventName'] = 'fake_start'
+            fake_start_ev['EventDescr'] = '0'
+            fake_start_ev['Time'] = protocol_task_events[last_init_event_idx]['Time']
+            
+            startEvents = np.hstack([startEvents, fake_start_ev])
+            
+            startEvents = startEvents[np.argsort(startEvents['Time'])]
+    except IndexError:
+        pass
+
+    #print(startEvents)
+
+    sfr = np.array([int(e['EventDescr'].decode('ascii')) for e in startEvents])
+
+    si = startEvents['Time'].searchsorted(t, side='right')
+    
+    #print t    
+    #print((si, startEvents, sfr))
+    
+    #try:
+    #    if len(si) > 1:
+    #        si = si[-1]
+    #except:
+    #    pass
+    
+    #fr = np.zeros_like(t)
+    
+    
+    fr = sfr[si-1] + ((t - startEvents['Time'][si-1]) / cycTime).astype(int)
+    
+    if np.isscalar(fr):
+        if si < len(sfr):
+            return np.minimum(fr, sfr[si])
+    else:
+        M = (si < len(sfr))
+        fr[M] = np.minimum(fr[M], sfr[si[M]])
+
+        return fr
+
+def frames_to_times(fr, events, mdh):
+    """
+    Use events and metadata to convert frame numbers to seconds
+
+    2024/11/1 - This used to return the start time of the subsequent frame (i.e. approx but not 
+    exactly the end time of the frame). Changed to return the start time of the current frame, 
+    which should be more accurate with camera restarts
+
+    Parameters
+    ----------
+    fr: ndarray
+        frame numbers to map to time (in seconds since the epoch), e.g. localization data_souce['t']
+    events: ndarray
+        TODO - if events-related type fixing goes through, use events helpers to accept list here as well
+    mdh: PYME.IO.MetaDataHandler
+        Metadata handler with 'Camera.CycleTime' and 'StartTime' entries
+
+    Returns
+    -------
+    t: ndarray
+        times [seconds since the epoch] to map to frame numbers
+    """
+    cycTime = mdh.getEntry('Camera.CycleTime')
+    startTime = mdh.getEntry('StartTime')
+
+    #se = array([('0', 'start', startTime)], dtype=events.dtype)
+    se = np.empty(1, dtype=events.dtype)
+    se['EventName'] = 'start'
+    se['EventDescr'] = '-1'
+    se['Time'] = startTime
+
+    #get events corresponding to aquisition starts
+    startEvents = np.hstack((se, events[events['EventName'] == b'StartAq']))
+    #print(events)
+    #print(startEvents)
+
+    sfr = np.array([int(e['EventDescr'].decode()) for e in startEvents])
+
+    si = sfr.searchsorted(fr, side = 'left')
+    return startEvents['Time'][si-1] + (fr - (sfr[si-1]+1)) * cycTime
+    
+
+class piecewiseMap:
+    def __init__(self, y0, xvals, yvals, secsPerFrame=1, xIsSecs=True):
+        self.y0 = y0
+        self.xvals = xvals  
+        self.yvals = yvals
+
+    def __call__(self, xp):
+        xp = xp.astype('d') #fast to float in case we get passed an int
+        yp = 0 * xp
+
+        inds = self.xvals.searchsorted(xp, side='right')
+        #print(xp, inds)
+        yp  = self.yvals[np.maximum(inds-1, 0)]
+        yp[inds == 0] = self.y0
+
+        return yp
+
+def GeneratePMFromProtocolEvents(events, metadata, x0, y0, id='setPos', idPos = 1, dataPos=2):
+    x = []
+    y = []
+
+    secsPerFrame = metadata.getEntry('Camera.CycleTime')
+
+    for e in events[events['EventName'] == b'ProtocolTask']:
+        #if e['EventName'] == eventName:
+        ed = e['EventDescr'].decode('ascii').split(', ')
+        if ed[idPos] == id:
+            x.append(e['Time'])
+            y.append(float(ed[dataPos]))
+            
+    x = np.array(x)
+    y = np.array(y)
+    
+    I = np.argsort(x)
+    
+    x = x[I]
+    y = y[I]
+
+    return piecewiseMap(y0, times_to_frames(x, events, metadata), y, secsPerFrame, xIsSecs=False)
+
+
+def GeneratePMFromEventList(events, metadata, x0, y0, eventName=b'ProtocolFocus', dataPos=1):
+    """
+    Parameters
+    ----------
+    events:
+    metadata:
+    x0: why?
+    y0:
+    eventName:
+    dataPos: int
+        position in comma-separated event['EventDesc'] str of the float which makes 'y' for this mapping
+
+    Returns
+    -------
+    map: piecewiseMap
+    """
+    x = []
+    y = []
+
+    secsPerFrame = metadata.getEntry('Camera.CycleTime')
+
+    for e in events[events['EventName'] == eventName]:
+        #if e['EventName'] == eventName:
+        #print(e)
+        x.append(e['Time'])
+        y.append(float(e['EventDescr'].decode('ascii').split(', ')[dataPos]))
+        
+    x = np.array(x)
+    y = np.array(y)
+        
+    I = np.argsort(x)
+    
+    x = x[I]
+    y = y[I]
+
+    #print array(x) - metadata.getEntry('StartTime'), timeToFrames(array(x), events, metadata)
+
+    return piecewiseMap(y0, times_to_frames(x, events, metadata), y, secsPerFrame, xIsSecs=False)
+
+def bool_map_between_events(events, metadata, trigger_high, trigger_low, default=False):
+    """
+    generate a TTL output mapping [input time in units of frames] using events to trigger high/low
+
+    Parameters
+    ----------
+    events: list or structured ndarray
+        acquisition events
+    metadata: PYME.IO.MetaDataHandler.MDHandlerBase
+        metadata with 'Camera.CycleTime' and 'StartTime' entries
+    trigger_high: bytes
+        name of event to set output mapping high
+    trigger_low: bytes
+        name of event to set output mapping low
+    default: bool
+        start mapping low (False) or high (True) at t=0
+
+    Returns
+    -------
+    bool_map: piecewiseMap
+        callable mapping object
+    """
+    t, y = [], []
+
+    fps = metadata.getEntry('Camera.CycleTime')
+
+    for event in events:
+        if event['EventName'] == trigger_high:
+            t.append(event['Time'])
+            y.append(True)
+        elif event['EventName'] == trigger_low:
+            t.append(event['Time'])
+            y.append(False)
+
+    t = np.asarray(t)
+    y = np.asarray(y)
+    I = np.argsort(t)
+
+    return piecewiseMap(default, times_to_frames(t[I], events, metadata), y[I], fps, xIsSecs=False)
+
+def GenerateBacklashCorrPMFromEventList(events, metadata, x0, y0, eventName=b'ProtocolFocus', dataPos=1, backlash=0, in_frames= True):
+    x = []
+    y = []
+
+    for e in events[events['EventName'] == eventName]:
+        #if e['EventName'] == eventName:
+        x.append(e['Time'])
+        y.append(float(e['EventDescr'].decode('ascii').split(', ')[dataPos]))
+
+    x = np.array(x)
+    y = np.array(y)
+
+    dy = np.diff(np.hstack(([y0], y)))
+
+    for i in range(1, len(dy)):
+        if dy[i] == 0:
+            dy[i] = dy[i-1]
+
+    y += backlash*(dy < 0)
+
+    if in_frames:
+        return piecewiseMap(y0, times_to_frames(x, events, metadata), y)
+    else:
+        return piecewiseMap(y0, x, y)
+

PYME/Analysis/piezo_movement_correction.py

@@ -0,0 +1,153 @@
+import numpy as np
+from PYME.Analysis import piecewiseMapping as piecewise_mapping
+
+# TODO - this module has a lot of small functions which do very little - are they needed?
+# TODO - rename to something sensible and move (this is about event parsing, not analysis). Probably best refactored
+# at some point in the future along with some of the other event handling stuff. Maybe to PYME.IO.events??
+
+def flag_piezo_movement(frames, events, metadata):
+    """
+    Flags localizations detected on frames between ProtocolFocus and PiezoOnTarget events.
+
+    Parameters
+    ----------
+    frames: ndarray
+        frame numbers, typically localization data_source['t']
+    events: list or structured ndarray
+        acquisition events
+    metadata: PYME.IO.MetaDataHandler.MDHandlerBase
+        metadata with 'Camera.CycleTime' and 'StartTime' entries
+
+    Returns
+    -------
+    moving: ndarray
+        boolean array where elements correspond to each element in `frames`. False indicates the piezo is stable
+        while True flags elements in `frames` where the piezo doesn't have a well defined position.
+
+    """
+
+    # FIXME - is this actually used anywhere?
+    piezo_moving = map_piezo_moving(events, metadata)
+    return piezo_moving(frames)
+
+def map_piezo_moving(events, metadata):
+    """
+    Generates mapping function to flag whether input frames are between ProtocolFocus and PiezoOnTarget events.
+
+    Parameters
+    ----------
+    events: list or structured ndarray
+        acquisition events
+    metadata: PYME.IO.MetaDataHandler.MDHandlerBase
+        metadata with 'Camera.CycleTime' and 'StartTime' entries
+
+    Returns
+    -------
+    piezo_moving: PYME.Analysis.piecewiseMapping.piecewiseMap
+        callable object returning True for input frame numbers where the piezo is not settled.
+
+    """
+    # FIXME - is this actually used anywhere?
+    return piecewise_mapping.bool_map_between_events(events, metadata, b'ProtocolFocus', b'PiezoOnTarget',
+                                                     default=False)
+
+def map_corrected_focus(events, metadata):
+    """
+    ProtocolFocus event descriptions list the intended focus target. Some piezos have a target tolerance and log their
+    landing position with PiezoOnTarget. PiezoOffsetUpdate events are also accounted for.
+
+    Parameters
+    ----------
+    events: list or structured ndarray
+        acquisition events
+    metadata: PYME.IO.MetaDataHandler.MDHandlerBase
+        metadata with 'Camera.CycleTime' and 'StartTime' entries
+
+    Returns
+    -------
+    focus_mapping: PYME.Analysis.piecewiseMapping.piecewiseMap
+        callable function to return focus positions for each input frame number
+
+    """
+    # FIXME - this is only used below in correct_target_positions - is it needed?
+    normalized_events = spoof_focus_events_from_ontarget(events, metadata)
+    return piecewise_mapping.GeneratePMFromEventList(normalized_events, metadata, metadata['StartTime'],
+                                                              metadata.getOrDefault('Protocol.PiezoStartPos', 0.))
+def correct_target_positions(frames, events, metadata):
+    """
+    ProtocolFocus event descriptions list the intended focus target. Some piezos have a target tolerance and log their
+    landing position with PiezoOnTarget. PiezoOffsetUpdate events are also accounted for.
+
+    Parameters
+    ----------
+    frames: ndarray
+        time array, e.g. data_source['t'], in units of frames
+    events: list or structured ndarray
+        acquisition events
+    metadata: PYME.IO.MetaDataHandler.MDHandlerBase
+        metadata with 'Camera.CycleTime' and 'StartTime' entries
+
+    Returns
+    -------
+    corrected_focus: ndarray
+        focus positions for each element in `frames`
+
+    """
+    focus_mapping = map_corrected_focus(events, metadata)
+    return focus_mapping(frames)
+
+def spoof_focus_events_from_ontarget(events, metadata):
+    """
+    Generates a acquisition event array where events from (offset) piezo's with on-target events are spoofed to
+    look like standard ProtocolFocus events.
+
+    Parameters
+    ----------
+    events: list or structured ndarray
+        acquisition events
+    metadata: PYME.IO.MetaDataHandler.MDHandlerBase
+        metadata with 'Camera.CycleTime' and 'StartTime' entries
+    Returns
+    -------
+    bonus_events: ndarray
+        events with piezo offsets accounted for and PiezoOnTarget events spoofed as ProtocolFocus events
+
+    Notes
+    -----
+    The on-target events are fired from standard piezo classes, not the OffsetPiezo subclasses, so the PiezoOnTarget
+    positions and ProtocolFocus events have an offset between them which we remove in the output normalized events if
+    there are PiezoOffsetUpdate events available to do so.
+
+    """
+    ontarget_times, ontarget_positions = [], []
+    offset_start, first_offset_time = 0, np.finfo(float).max
+    for event in events:
+        if event['EventName'] == b'PiezoOnTarget':
+            ontarget_times.append(float(event['Time']))
+            ontarget_positions.append(float(event['EventDescr']))
+        elif event['EventName'] == b'PiezoOffsetUpdate':
+            if float(event['Time']) < first_offset_time:
+                first_offset_time = float(event['Time'])
+                offset_start = float(event['EventDescr'].decode('ascii').split(', ')[0])
+
+    if len(ontarget_times) == 0:
+        # nothing to do
+        return events
+
+    offset_map = piecewise_mapping.GeneratePMFromEventList(events, metadata, 0, offset_start, eventName=b'PiezoOffsetUpdate',
+                                                           dataPos=0)
+
+    ontarget_times = np.asarray(ontarget_times)
+    ontarget_frames = piecewise_mapping.times_to_frames(ontarget_times, events, metadata).astype(int)
+
+
+    # spoof ProtocolFocus events from PiezoOnTarget events
+    bonus_events = np.empty(len(events) + len(ontarget_times),
+                            dtype=[('EventName', 'S32'), ('Time', '<f8'), ('EventDescr', 'S256')])
+    bonus_events[:len(events)][:] = events[:]
+    bonus_events[len(events):]['EventName'] = b'ProtocolFocus'
+    bonus_events[len(events):]['Time'] = ontarget_times
+    bonus_events[len(events):]['EventDescr'] = [', '.join((str(f), str(p - offset_map(np.asarray([f]))[0]))) for f, p in
+                                                zip(ontarget_frames, ontarget_positions)]
+
+    return bonus_events

PYME/Analysis/points/DeClump/__init__.py

@@ -0,0 +1,78 @@
+#!/usr/bin/python
+
+###############
+# __init__.py
+#
+# Copyright David Baddeley, 2012
+# d.baddeley@auckland.ac.nz
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+################
+from . import deClump
+
+# wrap c functions so we can get nice docstrings.
+#################################
+
+
+def findClumps(t, x, y, delta_x, n_frames=10, link_within_frame=True):
+    """
+    Find repeated localisations of a single fluorophore, connecting localisations which are within `2*delta_x`
+    (i.e. a 95% confidence interval) of a localisation in the previous frame. Handles intermittency
+    (rapid blinking etc ...) through the `n_frames` parameter.
+
+    By making `delta_x` half the maximum movement of a particle from one frame to the next, the code can also be used
+    for sparse particle tracking.
+    
+    Localisations **MUST BE SORTED** in time-order prior to calling findClumps.
+    
+    Parameters
+    ----------
+    t : ndarray (int)
+        frame numbers for localisations
+    x : ndarray (float)
+        x positions of localisations
+    y : ndarray (float)
+        y positions of localisations
+    delta_x: ndarray (float)
+        localisation error (std. dev.) for each localisation
+    n_frames: int
+        number of frames an emitter can be off due to transient blinking and still be linked. 0 = must be on in previous
+        frame, 1 = can have a gap of 1 frame, etc ... The special value of -1 only links within the current frame.
+    link_within_frame: bool
+        whether to link within a frame. If True (default to match old behaviour) close emitters within a frame will be
+        linked.
+
+    Returns
+    -------
+
+    assigned : ndarray (int)
+        array of labels for each linked chunk found
+        
+    
+    Notes
+    -----
+    
+    When events are so dense that multiple emitters in a single frame are within `2*delta_x`, the linking will also be
+    a bit dumb, and might link traces incorrectly. In practice this is only likely to occur in a single-particle
+    tracking scenario where `delta_x` has been inflated to allow for potential emitter movement. In these cases, feature
+    based tracking, which can use other object properties such as event intensity and/or shape to improve linkages
+    is preferred.
+
+    We also assume that `delta_x` is a good proxy for `delta_y` - the actual linkage function used is
+    $(x_{i+1}-x_i)^2 + (y_{i+1} - y_i)^2 < 4 \times delta_x^2$. This is a fair assumption for the majority of
+    localisation data.
+    """
+    
+    return deClump.findClumps(t, x, y, delta_x, n_frames, link_within_frame)

PYME/Analysis/points/DeClump/deClumpGUI.py

@@ -0,0 +1,87 @@
+#!/usr/bin/python
+
+##################
+# deClumpGUI.py
+#
+# Copyright David Baddeley, 2010
+# d.baddeley@auckland.ac.nz
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+##################
+
+import wx
+#import deClump
+#from pylab import *
+#import numpy as np
+
+class deClumpDialog(wx.Dialog):
+    def __init__(self, *args, **kwargs):
+        wx.Dialog.__init__(self, *args, **kwargs)
+
+        vsizer = wx.BoxSizer(wx.VERTICAL)
+
+        hsizer = wx.BoxSizer(wx.HORIZONTAL)
+
+        hsizer.Add(wx.StaticText(self, -1, 'Clump Radius: '), 0, wx.ALL|wx.ALIGN_CENTER_VERTICAL, 5)
+
+        self.tClumpRadMult = wx.TextCtrl(self, -1, '2.0', size=[30,-1])
+        hsizer.Add(self.tClumpRadMult, 0, wx.ALL|wx.ALIGN_CENTER_VERTICAL, 5)
+
+        hsizer.Add(wx.StaticText(self, -1, 'X'), 0, wx.ALL|wx.ALIGN_CENTER_VERTICAL, 5)
+
+        self.cClumpRadVar = wx.Choice(self, -1, choices=['1.0', 'error_x'])
+        self.cClumpRadVar.SetSelection(1)
+        hsizer.Add(self.cClumpRadVar,1, wx.ALL|wx.ALIGN_CENTER_VERTICAL, 5)
+        
+        vsizer.Add(hsizer, 0, wx.ALL, 5)
+        
+        hsizer = wx.BoxSizer(wx.HORIZONTAL)
+        hsizer.Add(wx.StaticText(self, -1, 'Time Window: '), 0, wx.ALL|wx.ALIGN_CENTER_VERTICAL, 5)
+
+        self.tClumpTime = wx.TextCtrl(self, -1, '3')
+        hsizer.Add(self.tClumpTime,1, wx.ALL|wx.ALIGN_CENTER_VERTICAL, 5)
+
+        vsizer.Add(hsizer, 0, wx.ALL, 5)
+
+        btSizer = wx.StdDialogButtonSizer()
+
+        btn = wx.Button(self, wx.ID_OK)
+        btn.SetDefault()
+
+        btSizer.AddButton(btn)
+
+        btn = wx.Button(self, wx.ID_CANCEL)
+
+        btSizer.AddButton(btn)
+
+        btSizer.Realize()
+
+        vsizer.Add(btSizer, 0, wx.ALL, 5)
+
+        self.SetSizerAndFit(vsizer)
+
+    def GetClumpRadiusMultiplier(self):
+        return float(self.tClumpRadMult.GetValue())
+
+    def GetClumpRadiusVariable(self):
+        return self.cClumpRadVar.GetStringSelection()
+
+    def GetClumpTimeWindow(self):
+        return int(self.tClumpTime.GetValue())
+
+
+
+
+