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
},
)