pysted.utils

This module contains utilitary functions that used across pySTED.

Code written by Benoit Turcotte, benoit.turcotte.4@ulaval.ca, October 2020 For use by FLClab (@CERVO) authorized people

Functions

`action_execution`(action_selected, ...)	Executes the selected action.
`action_execution_2`(action_selected, ...)	Executes the selected action. Handles matching the starting_pixel with the number of pixels for which we can image. Combines this acquisition with the previously computed intensity_map in the case where a full scan was interupted by a flash, for example. :param action_selected: The selected action (for now, either a full confocal scan (at lower resolution) or a full sted scan). :param frame_shape: The shape of the ROI :param starting_pixel: The pixel at which the scan starts :param pxsize: The acquisition pixel size :param datamap: The datamap being imaged :param frozen_datamap: A static version of the datamap roi, NOT SURE WHY THIS IS USED IN THE WAY IT IS :param microscope: The microscope imageing the datamap :param pdt: The pixel dwelltime (either scalar or array of size frame_shape) :param p_ex: The excitation power (either scalar or array of size frame_shape) :param p_sted: The STED power (either scalar or array of size frame_shape) :param intensity_map: The intensity map for the previous acquisition, in case it was interrupted :param bleach: Bool determining whether bleaching occurs or not :param t_stack_idx: The time step at which we are in our experiment :return: acq, the acquisition (photons), bleached, the bleached datamap, datamap, the updated datamap, pixel_list, the pixel_list on which the acquisition was occuring, useful to figure out where the next acquisition should start.
`action_execution_g`(action_selected, ...)	Executes the selected action.
`add_event`(file, start_frame, end_frame, ...)	Function that allows a user to easily store an event in a file, which can later be read with the event_reader func.
`approx_binomial`(n, p[, size])	Sample (64-bit) from a binomial distribution using the normal approximation.
`array_padder`(base, laser[, pad_value])	Function used to pad an array (base) according to the size of the secondary array being iterated over it (laser).
`array_unpadder`(padded_base, laser)	Unpads an array according to the size of the secondary array being iterated over it.
`cart2pol`(x, y)	Convert the polar coordinates corresponding to the given cartesian coordinates.
`complex_quadrature`(func, a, b, args)	Integrate a complex integrand using the Gauss-Kronrod quadrature.
`compute_time_correspondances`(...[, mode])	This function computes how many loop steps will occur and how many pixels can be imaged for each loop step.
`datamap_generator`(shape, sources, molecules)	Function to generate a datamap with randomly located molecules.
`dict_write_func`(file, dictio)	Write a dict to a text file in a good way :)
`event_reader`(file)	Read events from a file containing event dictionaries and return the dicts to a list
`exponential`(x, a)
`flash_generator`(events_curves_path[, seed])	Generates a flash by sampling from statistics built from save light curves
`flash_routine`(synapses, probability, ...)	This function makes 1 step in a flash routine.
`float_to_array_verifier`(float_or_array, shape)	Verify if a given input is a float or an array.
`fwhm`(values)	Compute the full width at half maximum of the Gaussian-shaped values.
`fwhm_donut`(values)	Compute the full width at half maximum of the donut-shaped values.
`generate_fiber_with_synapses`(datamap_shape, ...)	This func allows a user to generate a fiber object and synapses attached to it.
`generate_raster_pixel_list`(n_pixels_to_add, ...)	Generates a pixel list of a raster scan of n_pixels_to_add pixels starting from starting_pixel
`generate_secondary_fibers`(datamap_shape, ...)	This function allows to spawn secondary fibers branching from a main fiber
`generate_synapse_flash_dicts`(synapses_list, ...)	This function is used to generate the dictionnaries needed to keep track of which synapses are flashing and where they are situatied in the flash and such
`generate_synapses_on_fiber`(datamap_shape, ...)	Generates polygon objects (representing synapses) on the main fiber
`generate_synaptic_fibers`(image_shape, ...[, ...])	This function wraps up the generation of fibers with secondary branches and synapses in a stand-alone function
`get_avg_lightcurve`(light_curves)	This function takes as input a list of light curves and processes them so they are rescaled and shifted to align their peaks.
`get_light_curve`(video_path, event)	Use a tif video of Ca2+ flashes along with a ROI (spatial and temporal) to convert the data to an intensity/photon count curve.
`hand_crafted_light_curve`([delay, ...])	Hand crafted light curve that has a more abrupt rise than sampling a light curve from real data.
`inverse`(x[, a])	Evaluate the inverse function \(1 / (a x + 1)\).
`inverse_exponential`(x[, a])	Evaluate the inverse function \(1 / e^{ax}\).
`make_path_sane`(p)	Function to uniformly return a real, absolute filesystem path.
`molecules_survival`(pre_bleach, post_bleach)	Return the ratio of surviving molecules
`molecules_symmetry`(pre_bleach, post_bleach)	Function to compare the ratio of surviving molecules in the upper vs lower half of a datamap.
`mse_calculator`(array1, array2)	Compute the RMS between two arrays.
`pad_values`(laser)	Pad values for the array_padder function
`pinhole`(radius, pixelsize[, n_pixels])	Return a pinhole mask.
`pixel_list_filter`(datamap, pixel_list, ...)	Function to pre-filter a pixel list.
`pixel_sampling`(datamap[, mode])	Function to test different pixel sampling methods, instead of simply imaging pixel by pixel
`pxsize_comp2`(img_pixelsize, data_pixelsize)	Try number 2 for my float comparison function that hopefully will give the right values this time :)
`pxsize_comp_array_maker`(img_pixelsize, ...)	Compare the pixel sizes of the image and the datamap and return the appropriate pixel sizes for the acquisition.
`pxsize_grid`(img_pixelsize, data_pixelsize, ...)	Function which creates a grid of the pixels.
`pxsize_ratio`(img_pixelsize, data_pixelsize)	Computes the ratio between the acquisition pixel size and the datamap pixel size
`rescale`(data, factor)	Rescale the data container (and content) given the ratio between the current container unit size and the new container unit size.
`rescale_data`(data[, to_int, divider])	Function to rescale the data (made for light curves, might be of use elsewhere) between 1 and max-min
`resize`(*images)	Resize images to the shape of the largest (pad with zeros).
`sample_light_curve`(light_curves)	This function allows to sample from a distribution of light curves and handles the smoothing and correcting values.
`sampled_flash_manipulations`(...[, rescale, seed])	Samples a light curve and modifies it to make it more prettier for training (i.e. more like the hand crafted light curves).
`savitzky_golay`(y, window_size, order[, ...])	Smooth (and optionally differentiate) data with a Savitzky-Golay filter. The Savitzky-Golay filter removes high frequency noise from data. It has the advantage of preserving the original shape and features of the signal better than other types of filtering approaches, such as moving averages techniques. Parameters ---------- y : array_like, shape (N,) the values of the time history of the signal. window_size : int the length of the window. Must be an odd integer number. order : int the order of the polynomial used in the filtering. Must be less then window_size - 1. deriv: int the order of the derivative to compute (default = 0 means only smoothing) Return ------- ys : ndarray, shape (N) the smoothed signal (or it's n-th derivative). Notes ----- The Savitzky-Golay is a type of low-pass filter, particularly suited for smoothing noisy data. The main idea behind this approach is to make for each point a least-square fit with a polynomial of high order over a odd-sized window centered at the point. Examples -------- t = np.linspace(-4, 4, 500) y = np.exp( -t2 ) + np.random.normal(0, 0.05, t.shape) ysg = savitzky_golay(y, window_size=31, order=4) import matplotlib.pyplot as plt plt.plot(t, y, label='Noisy signal') plt.plot(t, np.exp(-t2), 'k', lw=1.5, label='Original signal') plt.plot(t, ysg, 'r', label='Filtered signal') plt.legend() plt.show() References ---------- .. [1] A. Savitzky, M. J. E. Golay, Smoothing and Differentiation of Data by Simplified Least Squares Procedures. Analytical Chemistry, 1964, 36 (8), pp 1627-1639. .. [2] Numerical Recipes 3rd Edition: The Art of Scientific Computing W.H. Press, S.A. Teukolsky, W.T. Vetterling, B.P. Flannery Cambridge University Press ISBN-13: 9780521880688 ----------.
`set_starting_pixel`(previous_pixel, image_shape)	Return a value 1 pixel further from the last pixel of an acquisition list in an normal raster scan fashion.
`shift_data`(data[, peak_idx])	Function to shift the data (made for light curves, might be of use elsewhere) so the peak is on idx 5
`smooth_ramp_hand_crafted_light_curve`([...])	Hand crafted light curve that has a more abrupt rise than sampling a light curve from real data.
`smooth_ramp_hand_crafted_light_curve_2`([...])
`stack`(datamap, data)	Compute a new frame consisting in a replication of the given data centered at every positions and multiplied by the factors given in the datamap.
`stack_btmod_definitive`(datamap, data, ...)	Compute a new frame consisting in a replication of the given data centered at every positions and multiplied by the factors given in the datamap.
`symmetry_verifier`(array[, direction, plot])	Verifies if the given array is symmetrical along the vertical or horizontal direction
`time_quantum_to_flash_tstep_correspondance`(...)	Computes the correspondance between the time quantum value (in us) and the flash time steps

pysted.utils.action_execution(action_selected, frame_shape, starting_pixel, pxsize, datamap, frozen_datamap, microscope, pdt, p_ex, p_sted, intensity_map, bleach)

Executes the selected action. Handles matching the starting_pixel with the number of pixels for which we can image. Combines this acquisition with the previously computed intensity_map in the case where a full scan was interupted by a flash, for example.

Parameters:

action_selected – The selected action (for now, either a full confocal scan (at lower resolution) or a full sted scan).
frame_shape – The shape of the ROI
starting_pixel – The pixel at which the scan starts
pxsize – The acquisition pixel size
datamap – The datamap being imaged
frozen_datamap – A static version of the datamap roi, NOT SURE WHY THIS IS USED IN THE WAY IT IS
microscope – The microscope imageing the datamap
pdt – The pixel dwelltime (either scalar or array of size frame_shape)
p_ex – The excitation power (either scalar or array of size frame_shape)
p_sted – The STED power (either scalar or array of size frame_shape)
intensity_map – The intensity map for the previous acquisition, in case it was interrupted
bleach – Bool determining whether bleaching occurs or not

Returns:

acq, the acquisition (photons), bleached, the bleached datamap, datamap, the updated datamap, pixel_list, the pixel_list on which the acquisition was occuring, useful to figure out where the next acquisition should start

pysted.utils.action_execution_2(action_selected, frame_shape, starting_pixel, pxsize, datamap, frozen_datamap, microscope, pdt, p_ex, p_sted, intensity_map, bleach, t_stack_idx)

Executes the selected action. Handles matching the starting_pixel with the number of pixels for which we can image. Combines this acquisition with the previously computed intensity_map in the case where a full scan was interupted by a flash, for example. :param action_selected: The selected action (for now, either a full confocal scan (at lower resolution) or a full

sted scan).

Parameters:

frame_shape – The shape of the ROI
starting_pixel – The pixel at which the scan starts
pxsize – The acquisition pixel size
datamap – The datamap being imaged
frozen_datamap – A static version of the datamap roi, NOT SURE WHY THIS IS USED IN THE WAY IT IS
microscope – The microscope imageing the datamap
pdt – The pixel dwelltime (either scalar or array of size frame_shape)
p_ex – The excitation power (either scalar or array of size frame_shape)
p_sted – The STED power (either scalar or array of size frame_shape)
intensity_map – The intensity map for the previous acquisition, in case it was interrupted
bleach – Bool determining whether bleaching occurs or not
t_stack_idx – The time step at which we are in our experiment

Returns:

acq, the acquisition (photons), bleached, the bleached datamap, datamap, the updated datamap, pixel_list, the pixel_list on which the acquisition was occuring, useful to figure out where the next acquisition should start

pysted.utils.action_execution_g(action_selected, frame_shape, starting_pixel, pxsize, datamap, frozen_datamap, microscope, pdt, p_ex, p_sted, intensity_map, bleach, t_stack_idx)

Executes the selected action.

Handles matching the starting_pixel with the number of pixels for which we can image. Combines this acquisition with the previously computed intensity_map in the case where a full scan was interupted by a flash, for example.

Parameters:

action_selected – The selected action (for now, either a full confocal scan (at lower resolution) or a full sted scan).
frame_shape – The shape of the ROI
starting_pixel – The pixel at which the scan starts
pxsize – The acquisition pixel size
datamap – The datamap being imaged
frozen_datamap – A static version of the datamap roi, NOT SURE WHY THIS IS USED IN THE WAY IT IS
microscope – The microscope imageing the datamap
pdt – The pixel dwelltime (either scalar or array of size frame_shape)
p_ex – The excitation power (either scalar or array of size frame_shape)
p_sted – The STED power (either scalar or array of size frame_shape)
intensity_map – The intensity map for the previous acquisition, in case it was interrupted
bleach – Bool determining whether bleaching occurs or not
t_stack_idx – The time step at which we are in our experiment

Returns:

acq, the acquisition (photons), bleached, the bleached datamap, datamap, the updated datamap, pixel_list, the pixel_list on which the acquisition was occuring, useful to figure out where the next acquisition should start

pysted.utils.add_event(file, start_frame, end_frame, start_row, end_row, start_col, end_col)

Function that allows a user to easily store an event in a file, which can later be read with the event_reader func.

Parameters:

file – File to write the dict to. The goal is to use 1 text file to which we will write all the vents for 1 video.
start_frame – Frame number for the start of the event
start_row – Frame number for the end of the event
start_col – Starting column for the left of the event
end_frame – Ending column for the right of the event
end_row – Starting row for the top of the event
end_col – Ending row for the bottom of the event

pysted.utils.approx_binomial(n, p, size=None)

Sample (64-bit) from a binomial distribution using the normal approximation.

Parameters:

n – The number of trials (int or array of ints).
p – The probability of success (float).
size – The shape of the output (int or tuple of ints, optional).

Returns:

64-bit int or array of 64-bit ints.

pysted.utils.array_padder(base, laser, pad_value=0)

Function used to pad an array (base) according to the size of the secondary array being iterated over it (laser).

Parameters:

base – Base array on which we wish to iterate another array.
laser – Secondary array which will be iterated over the base array. Axes have to be of odd lengths in order for it to have a well defined single pixel center.
pad_value – Value of the padded region.

Returns:

Padded version of the base array, along with the number of added rows and columns

pysted.utils.array_unpadder(padded_base, laser)

Unpads an array according to the size of the secondary array being iterated over it.

Function used to unpad a padded array (padded_base) according to the size of the secondary array being iterated over it (laser).

Parameters:

padded_base – Padded Base array which we wish to unpad.
laser – Secondary array which has been iterated over padded_base. Axes have to be of odd lengths in order for it to have a well defined single pixel center.

Returns:

An unpadded version of the padded_base.

pysted.utils.cart2pol(x, y)

Convert the polar coordinates corresponding to the given cartesian coordinates.

Parameters:

x – The \(x\) cartesian coordinate.
y – The \(y\) cartesian coordinate.

Returns:

A tuple of the angle \(\theta\) and the lenght \(rho\).

pysted.utils.complex_quadrature(func, a, b, args)

Integrate a complex integrand using the Gauss-Kronrod quadrature.

Parameters:

func – The function to integrate.
a – The lower bound of the integration.
b – The upper bound of the integration.
args – Additionals arguments of the function to integrate.

Returns:

The integration result as a complex number.

pysted.utils.compute_time_correspondances(fwhm_step_sec_correspondance, acquisition_time_sec, pixel_dwelltime, mode='flash')

This function computes how many loop steps will occur and how many pixels can be imaged for each loop step. So far this only works for static pixel_dwelltime, need to figure out how to make it work for varying dwell times per pixel or varying dwell times as in RESCue.

Parameters:

fwhm_step_sec_correspondance – a tuple containing how large in time steps the FWHM of the mean flash is at index 0 and how large in seconds we want the FWHM to be at index 1
acquisition_time_sec – How long we want to acquire on the same datamap, in seconds. This will be used to determine how many loops we need to do (float? int?)
pixel_dwelltime – The pixel dwell time used by the microscope (float)

Returns:

The number of pixels that can be imaged per loop and the number of loop iterations

pysted.utils.datamap_generator(shape, sources, molecules, random_state=None)

Function to generate a datamap with randomly located molecules.

Parameters:

shape – A tuple representing the shape of the datamap. If only 1 number is passed, a square datamap will be generated.
sources – Number of molecule sources to be randomly placed on the datamap.
molecules – Average number of molecules contained on each source. The actual number of molecules will be determined by poisson sampling.
random_state – Sets the seed of the random number generator.

Returns:

A datamap containing the randomly placed molecules

pysted.utils.dict_write_func(file, dictio)

Write a dict to a text file in a good way :)

Parameters:

file – path of the file to write to
dictio – the dictionnary we wish to write to a txt file

pysted.utils.event_reader(file)

Read events from a file containing event dictionaries and return the dicts to a list

Parameters:: file – Path to the txt file containing the dict for the events
Returns:: A list containing the dicts of every identified event in a video

pysted.utils.flash_generator(events_curves_path, seed=None)

Generates a flash by sampling from statistics built from save light curves

Parameters:

events_curves_path – Path to the .npy file containing the light curves
seed – Sets the seed for random sampling :)

Returns:

A sampled light curve

pysted.utils.flash_routine(synapses, probability, synapse_flashing_dict, synapse_flash_idx_dict, curves_path, synapse_flash_curve_dict, isolated_synapses_frames, datamap)

This function makes 1 step in a flash routine. It loops through all the synapses in a frame to determine whether they will start flashing (if they aren’t already), or move the flash forward 1 time step if they are flashing, or reset the synapse if its flash is over.

Parameters:

synapses – A list of all the synapses in the datamap
probability – The probability with which a synapse will start flashing
synapse_flashing_dict – The dict listing whether each synapse is flashing or not
synapse_flash_idx_dict – The dict listing where in their flash each synapse is
curves_path – Path to the .npy file of the light curves being sampled
synapse_flash_curve_dict – The dict listing the sampled flash curve for every synapse
isolated_synapses_frames – The dict listing the isolated synapse frames
datamap – The datamap on which the synapses lie

Returns:

The updated dicts and datamap

pysted.utils.float_to_array_verifier(float_or_array, shape)

Verify if a given input is a float or an array.

If it is a float, it will return an array of shape (shape) filled. If it is an array, it will verify if it is of the appropriate shape. If it is neither, it will return an error

Parameters:

float_or_array – Either a float or an array containing floats
shape – The shape we want for our array (tuple)

Returns:

An array of the appropriate shape

pysted.utils.fwhm(values)

Compute the full width at half maximum of the Gaussian-shaped values.

Parameters:: values – An array of values describing a Gaussian shape.
Returns:: The full width at half maximum.

pysted.utils.fwhm_donut(values)

Compute the full width at half maximum of the donut-shaped values.

Parameters:: values – An array of values describing a donut shape.
Returns:: A tuple of the outer and inner width at half maximum.

pysted.utils.generate_fiber_with_synapses(datamap_shape, fibre_min, fibre_max, n_synapses, min_dist, polygon_scale=(5, 10))

This func allows a user to generate a fiber object and synapses attached to it.

Parameters:

datamap_shape – shape of the image to which we will add the fiber and synapses
fibre_min – min position for the fibre to start at
fibre_max – max position for the fibre to start at
n_synapses – number of synapses to put on the fiber
min_dist – min distance we want to have between the synapses. this is to make sure we don’t have overlapping synapses
polygon_scale – values from which the polygon size will be sampled

Returns:

the fiber object and the polygon objects representing the synapses

pysted.utils.generate_raster_pixel_list(n_pixels_to_add, starting_pixel, img)

Generates a pixel list of a raster scan of n_pixels_to_add pixels starting from starting_pixel

Parameters:

n_pixels_to_add – The number of pixels for which we want to image
starting_pixel – The starting point of our raster scan
img – the img in which the raster scan occurs

Returns:

A pixel list for the raster scan starting at starting_pixel

pysted.utils.generate_secondary_fibers(datamap_shape, main_fiber, n_sec, min_dist=10, sec_len=(2, 6), seed=None)

This function allows to spawn secondary fibers branching from a main fiber

Parameters:

datamap_shape – The shape of the datamap in which the main fiber resides
main_fiber – The main fiber object to which we will add secondary fiber branches
n_sec – The interval for the number of secondary branches we wish to spawn (tuple)
min_dist – The min distance between spawned secondary fiber, to ensure they are not all clumped
sec_len – The interval for the length of the secondary fibers (tuple)
seed – Random number generator seed

Returns:

a list containing the secondary fiber objects

pysted.utils.generate_synapse_flash_dicts(synapses_list, roi_shape)

This function is used to generate the dictionnaries needed to keep track of which synapses are flashing and where they are situatied in the flash and such

Parameters:

synapses_list – The list of all the synapses in the frame (flattenened)
roi_shape – The shape of the frame

Returns:

synapse_flashing_dict, a dict corresponding the synapses to whether they are currently flashing or not, synapse_flash_idx_dict, a dict corresponding each flash to where in the light curve they are at, synapse_flash_curve_dict, a dict containing the light curve sampled for the flash of this synapse, isolated_synapses_frames, a dict containing a frame for each synapse in which only it appears and the rest

is 0

pysted.utils.generate_synapses_on_fiber(datamap_shape, main_fiber, n_syn, min_dist, synapse_scale=(5, 10))

Generates polygon objects (representing synapses) on the main fiber

Parameters:

datamap_shape – The shape of the datamap on which the main_fiber lies
main_fiber – Fiber object representing the main branch
n_syn – The interval from which we will sample the number of synapses to spawn (tuple)
min_dist – The minimal distance between 2 synapses, to prevent clumping
synapse_scale – The interval form which we will sample each synapses’ size

Returns:

A list containing all the synapses on the main fiber

pysted.utils.generate_synaptic_fibers(image_shape, main_nodes, n_sec_fibers, n_synapses, min_fiber_dist=3, min_synapse_dist=1, sec_fiber_len=(10, 20), synapse_scale=(5, 5), seed=None)

This function wraps up the generation of fibers with secondary branches and synapses in a stand-alone function

TODO: - Add variable number of synapses, distances, - Add “position identifiers” to the synapses so I can easily make them flash after

Parameters:

image_shape – The shape of the ROI in which we want to spawn stuff
main_nodes –
???
n_sec_fibers – The interval for the number of secondary fibers branching from the main fiber (tuple)
n_synapses – The interval for the number of synapses (tuple)
min_fiber_dist – The minimum distance separating the secondary fibers
min_synapse_dist – The minimum distance separating the synapses
sec_fiber_len – The interval for the lengths of the secondary fibers
synapse_scale – The interval for the size of the synapses
seed – Random number generator seed

Returns:

An array containing the disposition of molecules corresponding to the generated shape and a list containing all the synapses (Polygon objects)

pysted.utils.get_avg_lightcurve(light_curves)

This function takes as input a list of light curves and processes them so they are rescaled and shifted to align their peaks. It then return the avg light curve as well as its standard deviation, so we can sample a light curve for event simulation.

Parameters:: light_curves – list of light curves of Ca2+ flash events
Returns:: the avg light curve and std of the light curve

pysted.utils.get_light_curve(video_path, event)

Use a tif video of Ca2+ flashes along with a ROI (spatial and temporal) to convert the data to an intensity/photon count curve.

Parameters:

video_path – The path to the video file from which we want to extract an event light curve (str)
event – A dictionary containing the start and end info for frames, rows, columns of an event (dict)

Returns:

A vector representing the mean intensity accros the frames of the event

pysted.utils.hand_crafted_light_curve(delay=2, n_decay_steps=10, n_molecules_multiplier=28, end_pad=0)

Hand crafted light curve that has a more abrupt rise than sampling a light curve from real data.

Parameters:

delay – The number of steps before the peak of the light curve.
n_decay_steps – The number of steps for the light curve to return to 1
n_molecules_multiplier – The value of the light curve at it’s peak
end_pad – The number of steps where the curve stays flat at 1 after the end of the exponential decay.

Returns:

The hand crafted light curve, which is flat at 1 until t = delay, where it peaks to n_molecs_multiplier, then decays back to 1 over t = n_decay_steps steps, and stays flat at 1 for end_pad + 1 steps

pysted.utils.inverse(x, a=1)

Evaluate the inverse function \(1 / (a x + 1)\).

Parameters:

x – An integer or array.
a – The scale of x.

Returns:

The result of the function, same shape as x.

pysted.utils.inverse_exponential(x, a=1)

Evaluate the inverse function \(1 / e^{ax}\).

Parameters:

x – An integer or array.
a – The scale of x.

Returns:

The result of the function, same shape as x.

pysted.utils.make_path_sane(p): Function to uniformly return a real, absolute filesystem path.

pysted.utils.molecules_survival(pre_bleach, post_bleach)

Return the ratio of surviving molecules

Parameters:

pre_bleach – The datamap before bleaching it.
post_bleach – The datamap after bleaching it.

Returns:

Ratio of molecules surviving bleach

pysted.utils.molecules_symmetry(pre_bleach, post_bleach)

Function to compare the ratio of surviving molecules in the upper vs lower half of a datamap.

Parameters:

pre_bleach – The datamap before bleaching it.
post_bleach – The datamap after bleaching it.

Returns:

Ratio of molecules surviving bleach, split between upper half and lower half

pysted.utils.mse_calculator(array1, array2)

Compute the RMS between two arrays. Must be of same size

Parameters:

array1 – First array
array2 – Second array

Returns:

Mean squarred error of the 2 arrays

pysted.utils.pad_values(laser)

Pad values for the array_padder function

Return the minimum necessary rows, cols to pad an array with if we want to iterated over all of it with a laser

Parameters:: laser – Array of the shape of the laser which we want to iterated over a datamap.
Returns:: rows_pad, cols_pad, the number of rows and columns we need to pad the array with.

pysted.utils.pinhole(radius, pixelsize, n_pixels=None)

Return a pinhole mask.

Parameters:

radius – The radius of the pinhole (m).
pixelsize – The size of a pixel (m).
n_pixels – The (optional) number of pixels (default: size of the pinhole).

pysted.utils.pixel_list_filter(datamap, pixel_list, img_pixelsize, data_pixelsize, output_empty=False)

Function to pre-filter a pixel list. Depending on the ratio between the data_pixelsize and acquisition pixelsize, a certain number of pixels must be skipped between laser applications.

Parameters:

pixel_list – The list of pixels passed to the acquisition function, which needs to be filtered
img_pixelsize – The acquisition pixelsize (m)
data_pixelsize – The data pixelsize (m)
output_empty – Bool to allow (or not) this function to return an empty pixel list

Returns:

A filtered version of the input pixel_list, from which the pixels which can’t be iterated over due to the pixel sizes have been removed

pysted.utils.pixel_sampling(datamap, mode='all')

Function to test different pixel sampling methods, instead of simply imaging pixel by pixel

Parameters:

datamap – A 2D array of the data to be imaged, used for its shape.
mode – A keyword to determine the order of pixels in the returned list. By default, all pixels are added in a raster scan (left to right, row by row) order.

Returns:

A list containing all the pixels in the order in which we want them to be imaged.

pysted.utils.pxsize_comp2(img_pixelsize, data_pixelsize)

Try number 2 for my float comparison function that hopefully will give the right values this time :)

Parameters:

img_pixelsize – Acquisition pixel size. Has to be a multiple of data_pixelsize (m).
data_pixelsize – Raw data pixelsize (m).

Returns:

Integer values of the pixelsizes which can later be used to compute ratios and stuff :)

pysted.utils.pxsize_comp_array_maker(img_pixelsize, data_pixelsize, datamap)

Compare the pixel sizes of the image and the datamap and return the appropriate pixel sizes for the acquisition.

Function which utilizes the ratio between the image pixelsize and the datamap pixelsize to create an appropriatly sized output datamap for a normal raster scan acquisition with ratio jumps between laser applications. This assures that the laser application is placed in the appropriate acquisition output pixel.

Parameters:

img_pixelsize – The image pixelsize (m)
data_pixelsize – The datamap pixelsize (m)
datamap – The datamap on which the acquisition is made

Returns:

An empty datamap of shape (ceil(datamap.shape[0] / ratio), ceil(datamap.shape[1] / ratio))

pysted.utils.pxsize_grid(img_pixelsize, data_pixelsize, datamap)

Function which creates a grid of the pixels.

This can be iterated on based on the ratio between img_pixelsize and data_pixelsize. Imagine the laser is fixed on a grid and can only make discrete movements, and this grid size is determined by the ratio

Parameters:

img_pixelsize – Size of the minimum distance the laser must do between acquisitions (m). Must be a multiple of data_pixelsize.
data_pixelsize – Size of a pixel of the datamap (m).
datamap – Raw molecule dispotion on which we wish to do an acquisition.

Returns:

A list of the pixels which can be iterated on (?)

pysted.utils.pxsize_ratio(img_pixelsize, data_pixelsize)

Computes the ratio between the acquisition pixel size and the datamap pixel size

Parameters:

img_pixelsize – Minimum distance the laser must move during application. Multiple of data_pixelsize (m).
data_pixelsize – Size of a pixel in the datamap (m).

Returns:

the ratio between pixel sizes

pysted.utils.rescale(data, factor)

Rescale the data container (and content) given the ratio between the current container unit size and the new container unit size.

Example:

>>> data_10nm = numpy.array([[1, 0, 0, 0],
                             [0, 1, 0, 0],
                             [0, 0, 0, 0],
                             [0, 0, 0, 0]])
>>> rescale(data_10nm, 2) # rescale to 20 nm size
numpy.array([[2, 0],
             [0, 0]])

Parameters:

data – A 2D array.
factor – The ratio between the original container units and the new container units.

Returns:

A 2D array.

pysted.utils.rescale_data(data, to_int=True, divider=1)

Function to rescale the data (made for light curves, might be of use elsewhere) between 1 and max-min

Parameters:

data – data to rescale.
to_int – Determines whether the data is truncated to ints after being normalized. Useful for using the fast acquisition function.

Returns:

The data rescaled between 1 and max(data) - min(data)

pysted.utils.resize(*images)

Resize images to the shape of the largest (pad with zeros).

Parameters:: images – Square shaped images.
Returns:: A tuple of copies of the given images resized to the size of the largest input image.

pysted.utils.sample_light_curve(light_curves)

This function allows to sample from a distribution of light curves and handles the smoothing and correcting values.

Parameters:: light_curves – list containing the light curves we wish to do stats and sample from
Returns:: A smoothed curve sampled from the distribution

pysted.utils.sampled_flash_manipulations(events_curves_path, delay, rescale=True, seed=None)

Samples a light curve and modifies it to make it more prettier for training (i.e. more like the hand crafted light curves)

converts the values to ints
add variable delay at the start of the curve to delay the flash
(optional) rescales the values between [1, 28]

Parameters:

events_curves_path – Path to the .npy file containing the light curves
delay – Number of steps where the flash value stays ctw at 1 before the flash starts
rescale – Whether or not the light curve will be rescaled. For now, if true, simply rescales between [1, 28] because this is the value range for
seed – Sets the seed for random sampling :)

pysted.utils.savitzky_golay(y, window_size, order, deriv=0, rate=1)

Smooth (and optionally differentiate) data with a Savitzky-Golay filter. The Savitzky-Golay filter removes high frequency noise from data. It has the advantage of preserving the original shape and features of the signal better than other types of filtering approaches, such as moving averages techniques. Parameters ———- y : array_like, shape (N,)

the values of the time history of the signal.

window_sizeint: the length of the window. Must be an odd integer number.
orderint: the order of the polynomial used in the filtering. Must be less then window_size - 1.
deriv: int: the order of the derivative to compute (default = 0 means only smoothing)

Return

ysndarray, shape (N): the smoothed signal (or it’s n-th derivative).

Notes

The Savitzky-Golay is a type of low-pass filter, particularly suited for smoothing noisy data. The main idea behind this approach is to make for each point a least-square fit with a polynomial of high order over a odd-sized window centered at the point. Examples ——– t = np.linspace(-4, 4, 500) y = np.exp( -t**2 ) + np.random.normal(0, 0.05, t.shape) ysg = savitzky_golay(y, window_size=31, order=4) import matplotlib.pyplot as plt plt.plot(t, y, label=’Noisy signal’) plt.plot(t, np.exp(-t**2), ‘k’, lw=1.5, label=’Original signal’) plt.plot(t, ysg, ‘r’, label=’Filtered signal’) plt.legend() plt.show() References ———- .. [1] A. Savitzky, M. J. E. Golay, Smoothing and Differentiation of

Data by Simplified Least Squares Procedures. Analytical Chemistry, 1964, 36 (8), pp 1627-1639.

pysted.utils.set_starting_pixel(previous_pixel, image_shape, ratio=1)

Return a value 1 pixel further from the last pixel of an acquisition list in an normal raster scan fashion.

Parameters:

previous_pixel – The pixel on which the previous raster scan stopped
image_shape – the shape of the ROI on which the raster scan is occuring

Returns:

The pixel on which the next raster scan should start

pysted.utils.shift_data(data, peak_idx=5)

Function to shift the data (made for light curves, might be of use elsewhere) so the peak is on idx 5

Parameters:

data – data to shift
peak_idx – idx at which we want the peak to be

Returns:

The shifted data

pysted.utils.smooth_ramp_hand_crafted_light_curve(delay=2, n_decay_steps=10, n_molecules_multiplier=None, end_pad=0)

Hand crafted light curve that has a more abrupt rise than sampling a light curve from real data.

Parameters:

delay – The number of steps before the peak of the light curve.
n_decay_steps – The number of steps for the light curve to return to 1
n_molecules_multiplier – The value of the light curve at it’s peak
end_pad – The number of steps where the curve stays flat at 1 after the end of the exponential decay.

Returns:

The hand crafted light curve, which is flat at 1 until t = delay, where it peaks to n_molecs_multiplier, then decays back to 1 over t = n_decay_steps steps, and stays flat at 1 for end_pad + 1 steps

pysted.utils.stack(datamap, data)

Compute a new frame consisting in a replication of the given data centered at every positions and multiplied by the factors given in the datamap.

Example:

>>> datamap = numpy.array([[2, 0, 0, 0],
                           [0, 0, 0, 0],
                           [0, 0, 0, 0],
                           [0, 0, 0, 0]])
>>> data = numpy.array([[1, 2, 1],
                        [2, 3, 2],
                        [1, 2, 1]])
>>> utils.stack(datamap, data)
numpy.array([[6, 4, 0, 0],
             [4, 2, 0, 0],
             [0, 0, 0, 0],
             [0, 0, 0, 0]])

Parameters:

datamap – A 2D array indicating how many data are positioned in every
data – A 2D array containing the data to replicate.

Returns:

A 2D array shaped like datamap.

pysted.utils.stack_btmod_definitive(datamap, data, data_pixelsize, img_pixelsize, pixel_list)

Compute a new frame consisting in a replication of the given data centered at every positions and multiplied by the factors given in the datamap.

Example:

>>> datamap = numpy.array([[2, 0, 0, 0],
                           [0, 0, 0, 0],
                           [0, 0, 0, 0],
                           [0, 0, 0, 0]])
>>> data = numpy.array([[1, 2, 1],
                        [2, 3, 2],
                        [1, 2, 1]])
>>> utils.stack(datamap, data)
numpy.array([[6, 4, 0, 0],
             [4, 2, 0, 0],
             [0, 0, 0, 0],
             [0, 0, 0, 0]])

Parameters:

datamap – A 2D array indicating how many data are positioned in every
data – A 2D array containing the data to replicate.
data_pixelsize – Length of a pixel in the datamap (m)
img_pixelsize – Distance the laser moves in between each application of data. Must be a multiple of the data_pixelsize (m)
pixel_list – List of pixels on which we want to do the acquisition.

Returns:

A 2D array shaped like datamap.

pysted.utils.symmetry_verifier(array, direction='vertical', plot=False)

Verifies if the given array is symmetrical along the vertical or horizontal direction

Parameters:

array – Array to be verified for symmetry
direction – Direction along which to verify the symmetry. Vertical to see upper vs lower half, Horizontal to see left vs right half.
plot – Determines whether or not graphs of array and its symmetry will be displayed.

Returns:

Array(s) displaying the symmetry

pysted.utils.time_quantum_to_flash_tstep_correspondance(fwhm_step_sec_corresnpondance, time_quantum_us)

Computes the correspondance between the time quantum value (in us) and the flash time steps

Parameters:

fwhm_step_sec_corresnpondance – A tuple containing how large in time steps the FWHM of the mean flash is at index 0 and how large in useconds we want the FWHM to be at index 1
time_quantum_us – Value of the time quantum used by the master clock (in us)

Returns:

The number of time quantums per flash time step