siffreadermodule API

WARNING! This is autogenerated with sphinx and is using the C++ docstrings compiled to the extension module, NOT the much more clear stub file! Your IDE will likely use the stubs which contain better and more Pythonic type hints.

siffreader C extension module Reads and interprets .siff and ScanImage .tiffs Can be used in one of two ways: either directly callingfunctions from siffreader (siffreader.get_frames(*args, **kwargs)or instantiating a siffreader.SiffIO object (preferred).

CLASSES: SiffIO: siffreadermodule.SiffIO(filename : str = None) FUNCTIONS: suppress_warnings():

Suppresses module-specific warnings.

report_warnings():

Allows module-specific warnings.

debug(debugbool):

Enable or disable siffreadermodule debugging log.sifftotiff(sourcepath : str, savepath : str = None): Converts a .siff file (in sourcepath) to a .tiff file (saved in savepath), discarding arrival time information, if relevant.

class siffreadermodule.SiffIO

SiffIO – Work in progress

close() → None

–

Closes the open file (if there is one).

debug

Determines whether or not the SiffIO object will store a debug log.

filename

Retrieves filename from C++ object.

flim_map(params: FLIMParams, framelist: list[list[int]] = None, confidence_metric: string = 'chi_sq') → list[tuple[np.ndarray]]

–

Takes in a FLIMParams object and a list of lists of frames. Returns a list of tuples, each with 3 elements. Written to be (far) more memory efficient than using 3d numpy arrays. Input arguments:

params (FLIMParams): A fitted FLIMParams object giving the relevant info for the fluorophore. framelist (list of lists of ints): Formatted as in pool_frames, the length of this list ishow many frames to return. Each sublist is the list of frames to pool together. confidence_metric (string): A string determining what the final element of the tuple will contain. Options:

‘log_p’ : log likelihood of the pixel distribution (computes fast, iteratively). ‘chi_sq’ : chi-squared statistic of the data (computes slower, has some nicer properties). ‘None’ : No confidence measure. Much faster.

registration (optional, dict): a registration dictionary whose keys are the frame number (ints!) and whose values are rigid translations.Returns: (flimmap, intensity, chi_sq)

flimmap: list of np.ndarrays containing the empirical lifetime for each pixel (UNITS OF HISTOGRAM BINS). intensity: list of np.ndarrays containing the number of photons used to compute the lifetime in each pixel. confidence: list of np.ndarrays reporting the confidence metric for each pixel under the assumption in FLIMParams. discard_bins (optional, int): arrival bin (IN UNITS OF BIN) beyond which to discard photons

get_appended_text(frames: List[int] | None = None) → List[str]

get_epoch_both()

SiffIO.get_epoch_both)->np.ndarray[Any, np._uint64] –

Retrieves the timestamps of each frame computed using the system clock. Arguments:

frameslist[int]

A list of the indices of the frames whose timestamps are desired.

Returns:

timestampsnp.ndarray[Any, np._uint64]

A numpy array of timestamps in _epoch_ time (UTC), with the first row being the laser clock and the second row being the system clock.

get_epoch_timestamps_laser() → np.ndarray[Any, np._uint64]

–

Retrieves the timestamps of each frame computed using the number of laser pulses since the start of the experiment. Arguments:

frameslist[int]

A list of the indices of the frames whose timestamps are desired.

Returns:

timestampsnp.ndarray[Any, np._uint64]

A numpy array of timestamps in _epoch_ time (UTC).

get_epoch_timestamps_system() → np.ndarray[Any, np._uint64]

–

Retrieves the timestamps of each frame computed using the system clock. Arguments:

frameslist[int]

A list of the indices of the frames whose timestamps are desired.

Returns:

timestampsnp.ndarray[Any, np._uint64]

A numpy array of timestamps in _epoch_ time (UTC).

get_experiment_timestamps() → np.ndarray[Any, np._float]

–

Retrieves the timestamps of each frame computed using the number of laser pulses since the start of the experiment. Arguments:

frameslist[int]

A list of the indices of the frames whose timestamps are desired.

Returns:

timestampsnp.ndarray[Any, np._float]

A numpy array of timestamps in _experiment_ time (seconds since start).

get_file_header() → dict

–

Retrieves non-varying file data, e.g. ScanImage variable values at the onset. Returns as a dict, with keywords corresponding to ScanImage variables and values their corresponding measurements.

get_frame_metadata()

SiffIO.get_metadata(frames : list[int] = [])->dict –

Get the framewise metadata, e.g. dimensions, timestamps.

Arguments:

frameslist[int]

a list of the indices of the frames whose metadata is to be extract. TODO: Make this timepoint-specific instead of frames?

get_frames(frames: list[int] = [], flim: bool = False, registration: dict = {}) → list[np.ndarray]

–

Reads an opened .siff or .tiff file and returns a PyObject corresponding to a (time by z by y by x by tau) array.

Arguments:

frameslist[int]

A list of the indices of the frames to extract. NOTE: Frames will be returned in the order they are listed! TODO: Make this timepoint-specific

rettypetype

Format of returned data. Can be list or numpy.ndarray. If list, returns a list of single frame numpy arrays. If an ndarray, returns a full (time by color by z by x by y by tau) array, or otherwise as specified. (NOT YET IMPLEMENTED)

flimbool = False

return a tau axis containing arrival time (irrelevant if file is not a .siff) registration : dict = None A registration dictionary whose keys are the frame number (ints!) and whose values are rigid translations.

get_histogram(frames: list[int] = None) → np.ndarray

–

Retrieves only the photon arrival times from the frames in the list frames. Arguments:

frames (optional, LIST):

A list of the indices of the frames whose arrival times are desired.

if NONE, collects from ALL frames.Returns:

HISTOGRAM (ndarray): 1 dimensional numpy.ndarray

num_frames() → int

–

Reports number of frames in opened file.

open(filename: str) → None

–

Opens a file in C++ to be read and return numpy arrays.

Arguments:

filenamestr

Absolute path to the file to open.

pool_frames(pool_lists: list[list[int]], type: type = list, flim: bool = False, registration: dict = None) → list[np.ndarray]

–

Reads an opened .siff or .tiff file and returns a PyObject corresponding to frames pooled according to the pool_lists argument. Each element of the returned list corresponds to one element of the pool_lists: the pooled version of the indices contained IN that element. Arguments:

pool_list (LIST (of lists, TODO make accept array-like)): a list of the indices of the frames to extract.e.g. [[4,5,6], [0,1,2], [0,8,4]]. Order of sublists does not matter for pooling.NOTE: Frames will be returned in the order they are listed! TODO: Make this timepoint-specific type (optional, TYPE): format of returned data. Can be list or numpy.ndarray.If list, returns a list of single frame numpy arrays. If an ndarray, returns a full (time by color by z by x by y by tau) array,or otherwise as specified. (NOT YET IMPLEMENTED) flim (optional, BOOL): return a tau axis containing arrival time (irrelevant if file is not a .siff) registration (optional, dict): a registration dictionary whose keys are the frame number (ints!) and whose values are rigid translations. discard_bins (optional, int): arrival bin (IN UNITS OF BIN) beyond which to discard photons

status

Checks the status of the SiffIO’s SiffReader

sum_roi(mask: np.ndarray, frames: list[int] = None, registration: dict = None) → np.ndarray:

–

Requires a numpy array mask of dtype bool. Sums all the photons within the ROI for each of the frames requestedin the list frames. If frames is None, sums for all frames. Returns a 1d numpy array of dtype uint64 with lengthequal to the number of frames requested. Input arguments:

frameslist[int]

A list of the integer indices of the frames to sum within the ROI.

registrationdict

A registration_dict object whose keys are ints and whose values are tuples correspondingto a rigid shift in the y and x directions of the image.Returns:

summednp.ndarray

1d numpy array with length equal to the length of the number of frames requested.

sum_roi_flim(mask : np.ndarray, params : `siffpy.core.flim.flimparams.FLIMParams, frames : list[int] = None, registration : dict = None) → np.ndarray

–

Requires a numpy array mask of dtype bool and a FLIMParams object. Sums all the photons within the provided ROI for each frame requested to compute an empirical lifetime for the ROI. If frames is None, computes the sum for all frames. Returns a 1d numpy array of dtype float with length equal to the number of frames requested. NOTE: the empirical lifetime is in units of TIME BINS. Arguments:

mask: np.ndarray of dtype bool params : siffpy.core.flim.flimparams.FLIMParams frames : list[int] registration : dict

Returns:

summednp.ndarray

1d numpy array with length equal to the number of frames requested. Empirical lifetime measured in units of time bins of the arrival time measuring device (e.g. MultiHarp).

sum_rois(masks: List[np.ndarray] | np.ndarray, frames: list[int] = None, registration: dict = None) → np.ndarray

–

Requires a numpy array mask of dtype bool. Sums all the photons within the ROI for each of the frames requestedin the list frames. If frames is None, sums for all frames. Returns a 2d numpy array of dtype uint64 with dimensions`(len(frames), masks.shape[0])`. Input arguments:

masksUnion[List[np.ndarray],np.ndarray]

A list of numpy arrays of dtype bool, each corresponding to a different ROI.

frameslist[int]

A list of the integer indices of the frames to sum within the ROI.

registrationdict

A registration_dict object whose keys are ints and whose values are tuples correspondingto a rigid shift in the y and x directions of the image.Returns:

summednp.ndarray

2d numpy array with dimensions (masks.shape[0], len(frames)).

sum_rois_flim(masks : Union[List[np.ndarray],np.ndarray], params : `siffpy.core.flim.flimparams.FLIMParams, frames : list[int] = None, registration : dict = None) → np.ndarray

–

Requires a numpy array mask of dtype bool and a FLIMParams object. Sums all the photons within the provided ROI for each frame requested to compute an empirical lifetime for the ROI. If frames is None, computes the sum for all frames. Returns a 2d numpy array of dtype float with dimensions`(len(frames), masks.shape[0])`. NOTE: the empirical lifetime is in units of TIME BINS. Arguments:

masks: Union[List[np.ndarray],np.ndarray] params : siffpy.core.flim.flimparams.FLIMParams frames : list[int] registration : dict

Returns:

summednp.ndarray

2d numpy array with dimensions (masks.shape[0], len(frames)). Empirical lifetime measured in units of time bins of the arrival time measuring device (e.g. MultiHarp).