def create_mask_analysis(self, factories, dataset, use_sparse=None, length=None): """ Create a mask application analysis. Each factory function should, when called, return a numpy array with the same shape as frames in the dataset (so dataset.shape.sig). This is a more high-level method than `create_mask_job` and differs in the way the result is returned. With `create_mask_job`, it is a single numpy array, here we split it up for each mask we apply, make some default visualization available etc. Parameters ---------- factories Function or list of functions that take no arguments and create masks. The returned masks can be numpy arrays, scipy.sparse or sparse https://sparse.pydata.org/ matrices. The mask factories should not reference large objects because they can create significant overheads when they are pickled and unpickled. If a single function is specified, the first dimension is interpreted as the mask index. dataset dataset to work on use_sparse * None (default): Use sparse matrix multiplication if all factory functions return a \ sparse mask, otherwise convert all masks to dense matrices and use dense matrix \ multiplication * True: Convert all masks to sparse matrices. * False: Convert all masks to dense matrices. length Specify the number of masks if a single function is used so that the number of masks can be determined without calling the function. Examples -------- >>> from libertem.api import Context >>> ctx = Context() >>> ds = ctx.load("...") >>> # Use intermediate variables instead of referencing >>> # large complex objects like a dataset within the >>> # factory function >>> shape = dataset.shape.sig >>> job = ctx.create_mask_analysis( ... factories=[lambda: np.ones(shape)], ... dataset=dataset) >>> result = ctx.run(job) >>> result.mask_0.raw_data """ return MasksAnalysis( dataset=dataset, parameters={ "factories": factories, "use_sparse": use_sparse, "length": length }, )
def create_mask_analysis(self, factories: MaskFactoriesType, dataset: DataSet, use_sparse: bool = None, mask_count: int = None, mask_dtype: np.dtype = None, dtype: np.dtype = None) -> MasksAnalysis: """ Create a mask application analysis. Each factory function should, when called, return a numpy array with the same shape as frames in the dataset (so dataset.shape.sig). This is a more high-level interface than :class:`~libertem.udf.masks.ApplyMasksUDF` and differs in the way the result is returned. With :class:`~libertem.udf.masks.ApplyMasksUDF`, it is a single numpy array, here we split it up for each mask we apply, make some default visualization available etc. Parameters ---------- factories : Union[Callable[[], array_like], Iterable[Callable[[], array_like]]] Function or list of functions that take no arguments and create masks. The returned masks can be numpy arrays, scipy.sparse or sparse https://sparse.pydata.org/ matrices. The mask factories should not reference large objects because they can create significant overheads when they are pickled and unpickled. If a single function is specified, the first dimension is interpreted as the mask index. dataset : libertem.io.dataset.base.DataSet dataset to work on use_sparse : bool or None * None (default): Use sparse matrix multiplication if all factory functions return a \ sparse mask, otherwise convert all masks to dense matrices and use dense matrix \ multiplication * True: Convert all masks to sparse matrices. * False: Convert all masks to dense matrices. mask_count : int, optional Specify the number of masks if a single factory function is used so that the number of masks can be determined without calling the factory function. mask_dtype : numpy.dtype, optional Specify the dtype of the masks so that mask dtype can be determined without calling the mask factory functions. This can be used to override the mask dtype in the result dtype determination. As an example, setting this to np.float32 means that masks of type float64 will not switch the calculation and result dtype to float64 or complex128. dtype : numpy.dtype, optional Specify the dtype to do the calculation in. Integer dtypes are possible if the numpy casting rules allow this for source and mask data. Returns ------- MasksAnalysis : libertem.analysis.base.Analysis When run by the Context, this Analysis generates a :class:`libertem.analysis.masks.MasksResultSet`. Examples -------- >>> # Use intermediate variables instead of referencing >>> # large complex objects like a dataset within the >>> # factory function >>> shape = dataset.shape.sig >>> analysis = ctx.create_mask_analysis( ... factories=[lambda: np.ones(shape)], ... dataset=dataset ... ) >>> result = ctx.run(analysis) >>> result.mask_0.raw_data.shape (16, 16) """ return MasksAnalysis( dataset=dataset, parameters={ "factories": factories, "use_sparse": use_sparse, "mask_count": mask_count, "mask_dtype": mask_dtype, "dtype": dtype }, )