detectda ======== .. py:module:: detectda Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/detectda/hlpr/index /autoapi/detectda/hypo/index /autoapi/detectda/idpo/index /autoapi/detectda/imgs/index Classes ------- .. autoapisummary:: detectda.ImageSeries detectda.ImageSeriesPickle detectda.ImageSeriesPlus detectda.VacuumSeries Package Contents ---------------- .. py:class:: ImageSeries(video, polygon=None, div=1, n_jobs=None) Bases: :py:obj:`VidPol` Reads in an image series (video), either a single or multiple frames. May optionally specify polygonally region, held constant across frames, in which to select specific generators in persistent homology. :param video: Image series. Index on axis=0 represents the frame index, unless a single image (2d array) is provided. :type video: array_like :param polygon: Polygonal region outside of which positive cells of 0th persistent homology will be excluded. :type polygon: shapely.Polygon, optional, default is ``None`` :param div: In nanoparticle imaging process, pixel intensities are often registered as something close to a(div), so dividing by div and rounding to nearest integer will give pixel intensities that conform more strongly to common parametric assumptions. :type div: positive int/float, optional, default is ``1``. :param n_jobs: The number of jobs to use for the computation. ``None`` means 1 unless in a :obj:`joblib.parallel_backend` context. ``-1`` means using all processors. :type n_jobs: int or None, optional, default is ``None`` .. py:method:: alps_plot(frames) Returns the ALPS plots of up to 4 images in the video taken by ImageSeries. :param frames: Indices for frames in image series. :type frames: int or list :raises TypeError: If type is not int nor list. :raises ValueError: If more than 4 frames are given. :rtype: None. .. py:method:: fit(sigma=None, max_death_pixel_int=True, print_time=True) Fit method for ImageSeries object. Optional Gaussian smoothing with sigma parameter. The argument max_death_pixel_int controls whether or not the maximum death time is the largest pixel value (within an image), or the largest finite death time (within an image). .. py:method:: get_alps() Get ALPS statistic of each image frame from fitted object. .. py:method:: get_degp_totp(p=1, inf=False) Get degree-p total persistence of each image frame from fitted object. .. py:method:: get_pers_entr(neg=True) Get persistent entropy of each image frame from fitted object. For hypothesis testing purposes, the default is negative of the entropy .. py:method:: plot_im(frame, plot_poly=True, plot_pts=True, smooth=True, thr=None, **kwargs) Plot an individual frame in the video, with or without the polygonal region superimposed .. py:class:: ImageSeriesPickle(file_path, div=1, n_jobs=None) Bases: :py:obj:`ImageSeries` Creates ImageSeries object from .pkl file. Designed for use with output of identify_polygon script. .. py:class:: ImageSeriesPlus(video, polygon=None, div=1, n_jobs=None, im_list=False) Bases: :py:obj:`VidPol` Reads in an image series (video), either a single or multiple frames. May optionally specify polygonal region, held constant across frames, in which to select specific generators in persistent homology. Similar to ImageSeries, but with enhanced functionality for utilizing BOTH 0- and 1-dimensional persistent homology. :param video: Image series. Index on axis=0 represents the frame index, unless a single image (2d array) is provided. :type video: array_like :param polygon: Polygonal region outside of which positive cells of 0th persistent homology will be excluded. :type polygon: shapely.Polygon, optional, default is ``None`` :param div: In nanoparticle imaging process, pixel intensities are often registered as something close to a(div), so dividing by div and rounding to nearest integer will give pixel intensities that conform more strongly to common parametric assumptions. :type div: positive int/float, optional, default is ``1``. :param n_jobs: The number of jobs to use for the computation. ``None`` means 1 unless in a :obj:`joblib.parallel_backend` context. ``-1`` means using all processors. :type n_jobs: int or None, optional, default is ``None`` :param im_list: Bool indicating whether or not a list of numpy arrays is given (True) rather than a 3d numpy array. :type im_list: bool, default is ``False`` .. py:method:: convert_to_df() Creates pandas DataFrames (self.dfs) from persistence information calculated from detectda algorithm. :rtype: None. .. py:method:: fit(sigma=None, print_time=True, verbose=0) Fit method for ImageSeriesPlus object. Optional Gaussian smoothing with sigma parameter. .. py:method:: get_lifetimes() Creates persistence lifetimes (self.lifetimes) for each persistence diagram in image series. :rtype: None. .. py:method:: get_midlife_coords() Creates persistence midlife coordinates (self.midlife_coords) for each persistence diagram in image series. :rtype: None. .. py:method:: get_pers_im(bts, lts, dim, bandwidth=1) Create persistence images from cubical persistent homology for each image in the detectda object, for homology dimension dim. The resulting dimension of the persistence image vectorizations is bts x lts. :param bts: birth-time resolution (higher = finer) :type bts: int :param lts: lifetime resolution (higher = finer). :type lts: int :param bandwidth: Positive number corresponding to Gaussian kernel bandwidth (i.e. variance) :type bandwidth: float :param dim: Integer 0 or 1 corresponds to thresholding only based on dimension 0 and 1 persistence features. :type dim: int :rtype: None. .. py:method:: get_pers_mag() Creates persistence magnitudes (self.pers_mag) for each persistence diagram in image series. :rtype: None. .. py:method:: get_pers_stats() Get persistence statistics for each image, according to `Topological approaches to skin disease analysis`, along with persistent entropy and ALPS statistics, constituting an embedding into 36-dimensional Euclidean space. .. py:method:: pd_threshold(minq=0.05, maxq=0.95, dim='both', num=50) Calculates binary images for all frames in video based on best persistence-preserving threshold as described in Chung and Day (2018). :param minq: Minimum pixel quantile threshold to consider. :type minq: float :param maxq: Maximum pixel quantile threshold to consider. :type maxq: float :param dim: Integer 0 or 1 corresponds to thresholding only based on dimension 0 and 1 persistence features. The default is "both", corresponding to both dimensions 0 and 1. :type dim: str or int, optional :param num: Number of quantile thresholds to choose. :type num: int, optional :raises HomologyError: Error raised due to lack of sufficient homology to perform PD thresholding. :returns: **ims_t** -- Binary, thresholded images. :rtype: list of ndarray. .. py:method:: plot_im(frame, dim=0, plot_poly=True, plot_pts=True, smooth=True, thr=None, **kwargs) Plot an individual frame in the video, with or without the polygonal region superimposed .. py:method:: plot_pi_sig(frame, betas_feat='pos', smooth=True, **kwargs) :param frame: Frame which you would like to plot. Should lie in self.indices. :type frame: int :param betas_feat: Whether to plot positive, negative betas, or both. The default is 'pos'. :type betas_feat: str, optional :param smooth: Whether or not to smooth the image. The default is True. :type smooth: bool, optional :param \*\*kwargs: Additional parameters for plotting. :type \*\*kwargs: dict :rtype: None. .. py:method:: proc_pers_im(betas, quantiles, indices) :param betas: Simulated values of beta, such as those contained in self.post_beta after running fit and transform methods in bclr class. :type betas: array-like of shape (n_samples, n_features) :param quantiles: Quantiles which must be greater (resp. less) than 0 for positive and negative coefficients. :type quantiles: array-like of shape (2,) :param indices: Which frames to consider for processing. :type indices: array-like of shape (n_indices,) :rtype: None. .. py:class:: VacuumSeries(vacuum_video, observed_ImageSeries, parametric=True, div=1, n_jobs=None) Bases: :py:obj:`detectda.imgs.ImageSeries` Functionality to generate vacuum region videos for multiple hypothesis testing. .. py:method:: adjust_alpha(alpha, conservative=False) Adjust p-values based on a different alpha value. :param alpha: Statistical significance level. :type alpha: float :param conservative: Whether to use Benjamini-Yekutieli. The default is False. :type conservative: bool, optional :rtype: None. .. py:method:: fit(convert_to_int=False) Fits the Poisson mle for the vacuum region if parametric==True Else, it fits the empirical probability mass function. .. py:method:: gen_images(n) Generate and return a random image according to estimated null distribution .. py:method:: kolm_dist() Check how far the empirical distribution of vacuum values is from Poisson with parameter equal to mle, in terms of the Kolmogorov distance Uses the DKW inequality with the tight constant = 2 for Poisson testing. .. py:method:: plot_hypo() Plots hypothesis testing sequence. .. py:method:: transform(n, func='pers_entr', seed=0, alpha=0.05, conservative=False) Collects p-values and rejections for based off n Monte Carlo simulations...