LiberTEM Context API
See Python API for introduction and complete examples.
Context
- class libertem.api.Context(executor: Optional[JobExecutor] = None, plot_class=None)[source]
Context is the main entry point of the LiberTEM API. It contains methods for loading datasets, creating analyses on them and running them. In the background, instantiating a Context creates a suitable executor and spins up a local Dask cluster unless the executor is passed to the constructor.
Changed in version 0.7.0: Removed deprecated methods
create_mask_job
,create_pick_job
- Parameters
executor (JobExecutor or None) – If None, create a local dask.distributed cluster and client using
make_local()
with optimal configuration for LiberTEM. It uses all cores and compatible GPUs on the local system, but is not set as default Dask scheduler to not interfere with other uses of Dask.plot_class (libertem.viz.base.Live2DPlot) –
Default plot class for live plotting. Defaults to
libertem.viz.mpl.MPLLive2DPlot
.New in version 0.7.0.
- plot_class
Default plot class for live plotting. Defaults to
libertem.viz.mpl.MPLLive2DPlot
.New in version 0.7.0.
Examples
>>> ctx = libertem.api.Context()
>>> # Create a Context using an inline executor for debugging >>> from libertem.executor.inline import InlineJobExecutor >>> debug_ctx = libertem.api.Context(executor=InlineJobExecutor())
- create_com_analysis(dataset: DataSet, cx: Optional[int] = None, cy: Optional[int] = None, mask_radius: Optional[float] = None, flip_y: bool = False, mask_radius_inner: Optional[float] = None, scan_rotation: float = 0.0) COMAnalysis [source]
Create a center-of-mass (first moment) analysis, possibly masked.
- Parameters
dataset – the dataset to work on
cx – reference center x value
cy – reference center y value
mask_radius – mask out intensity outside of mask_radius from (cy, cx)
mask_radius_inner –
mask out intensity except for the ring between mask_radius_inner and mask_radius, centered around (cy, cx)
New in version 0.8.0.
flip_y (bool) –
Flip the Y coordinate. Some detectors, namely Quantum Detectors Merlin, may have pixel (0, 0) at the lower left corner. This has to be corrected to get the sign of the y shift as well as curl and divergence right.
New in version 0.6.0.
scan_rotation (float) –
Scan rotation in degrees. The optics of an electron microscope can rotate the image. Furthermore, scan generators may allow scanning in arbitrary directions. This means that the x and y coordinates of the detector image are usually not parallel to the x and y scan coordinates. For interpretation of center of mass shifts, however, the shift vector in detector coordinates has to be put in relation to the position on the sample. The
scan_rotation
parameter can be used to rotate the detector coordinates to match the scan coordinate system. A positive value rotates the displacement vector clock-wise. That means if the detector seems rotated to the right relative to the scan, this value should be negative to counteract this rotation.New in version 0.6.0.
- Returns
COMAnalysis – When run by the Context, this Analysis generates a
libertem.analysis.com.COMResultSet
.- Return type
- create_disk_analysis(dataset: DataSet, cx: Optional[int] = None, cy: Optional[int] = None, r: Optional[int] = None) DiskMaskAnalysis [source]
Create an Analysis that integrates over a disk (i.e. filled circle).
- Parameters
dataset – the dataset to work on
cx – center x value
cy – center y value
r – radius of the disk
- Returns
DiskMaskAnalysis – When run by the Context, this Analysis generates a
libertem.analysis.masks.SingleMaskResultSet
.- Return type
- create_mask_analysis(factories: Union[Callable[[], Union[ndarray, coo_matrix, dok_matrix]], Iterable[Callable[[], Union[ndarray, coo_matrix, dok_matrix]]]], dataset: DataSet, use_sparse: Optional[bool] = None, mask_count: Optional[int] = None, mask_dtype: Optional[dtype] = None, dtype: Optional[dtype] = None) MasksAnalysis [source]
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
ApplyMasksUDF
and differs in the way the result is returned. WithApplyMasksUDF
, 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 returning 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 – When run by the Context, this Analysis generates a
libertem.analysis.masks.MasksResultSet
.- Return type
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)
- create_pick_analysis(dataset: DataSet, x: int, y: Optional[int] = None, z: Optional[int] = None) PickFrameAnalysis [source]
Create an Analysis that picks a single frame / signal element from (z, y, x). The number of parameters must match number of navigation dimensions in the dataset, for example if you have a 4D dataset with two signal dimensions and two navigation dimensions, you need to specify x and y.
- Parameters
dataset – The dataset to work on
x – x coordinate
y – y coordinate
z – z coordinate
- Returns
PickFrameAnalysis – When run by the Context, this Analysis generates a
libertem.analysis.raw.PickResultSet
.- Return type
Examples
>>> dataset = ctx.load( ... filetype="memory", ... data=np.zeros([16, 16, 16, 16, 16], dtype=np.float32), ... sig_dims=2 ... ) >>> analysis = ctx.create_pick_analysis(dataset=dataset, x=9, y=8, z=7) >>> result = ctx.run(analysis) >>> assert result.intensity.raw_data.shape == tuple(dataset.shape.sig)
- create_point_analysis(dataset: DataSet, x: Optional[int] = None, y: Optional[int] = None) PointMaskAnalysis [source]
Create an Analysis that selects the pixel with coords (y, x) from each frame
- Returns
PointMaskAnalysis – When run by the Context, this Analysis generates a
libertem.analysis.masks.SingleMaskResultSet
.- Return type
- create_radial_fourier_analysis(dataset: DataSet, cx: Optional[float] = None, cy: Optional[float] = None, ri: Optional[float] = None, ro: Optional[float] = None, n_bins: Optional[int] = None, max_order: Optional[int] = None, use_sparse: Optional[bool] = None) RadialFourierAnalysis [source]
Create an Analysis that calculates the Fourier transform of rings around the center.
See Radial Fourier Series for details on the method!
- Parameters
dataset – the dataset to work on
cx – center x value
cy – center y value
ri – inner radius
ro – outer radius
n_bins – number of bins
max_order – maximum order of calculated Fourier component
- Returns
RadialFourierAnalysis – When run by the Context, this Analysis generates a
libertem.analysis.radialfourier.RadialFourierResultSet
.- Return type
- create_ring_analysis(dataset: DataSet, cx: Optional[int] = None, cy: Optional[int] = None, ri: Optional[int] = None, ro: Optional[int] = None) RingMaskAnalysis [source]
Create an Analysis that integrates over a ring.
- Parameters
dataset – the dataset to work on
cx – center x value
cy – center y value
ri – inner radius
ro – outer radius
- Returns
RingMaskAnalysis – When run by the Context, this Analysis generates a
libertem.analysis.masks.SingleMaskResultSet
.- Return type
- create_sum_analysis(dataset) SumAnalysis [source]
Create an Analysis that sums all signal elements along the navigation dimension, preserving the signal dimension.
- Parameters
dataset – the dataset to work on
- Returns
SumAnalysis – When run by the Context, this Analysis generates a
libertem.analysis.sum.SumResultSet
.- Return type
- display(dataset: DataSet, udf: UDF, roi: Optional[Union[ndarray, SparseArray, spmatrix, Tuple[int], Iterable[Tuple[Tuple[int], bool]]]] = None)[source]
Show information about the UDF in combination with the given DataSet.
- load(filetype: str, *args, io_backend=None, **kwargs) DataSet [source]
Load a
DataSet
. As it doesn’t load the whole data into RAM at once, you can load and process datasets that are bigger than your available RAM. Using fast storage (i.e. SSD) is advisable.Changed in version 0.5.0: Added support for filetype=”auto”
Changed in version 0.6.0: Added support for specifying the I/O backend
- Parameters
filetype (str) – one of: hdf5, raw, mib, blo, k2is, ser, frms6, empad, memory, dm, seq, mrc, tvips, dask, npy; or use “auto” to automatically determine filetype and parameters
io_backend (IOBackend or None) – Use a different I/O backend for this data set
args – passed on to the DataSet implementation
kwargs – passed on to the DataSet implementation
- Returns
DataSet – The loaded dataset
- Return type
Note
Additional parameters are passed to the concrete
DataSet
implementation.Note
See Data Set API for format-specific documentation.
Examples
Load a data set from a given path, automatically determinig the type:
>>> ds = ctx.load("auto", path="...")
To configure an alternative I/O backend, in this case configuring the mmap backend to enable readahead hints:
>>> from libertem.io.dataset.base import MMapBackend >>> io_backend = MMapBackend(enable_readahead_hints=True) >>> ds = ctx.load("auto", path="...", io_backend=io_backend)
- classmethod make_with(executor_spec: Union[Literal['synchronous'], Literal['inline'], Literal['threads'], Literal['dask-integration'], Literal['dask-make-default'], Literal['delayed'], Literal['pipelined']], *args, **kwargs) Context [source]
Create a Context with a specific kind of executor.
New in version 0.9.0.
This simplifies creating a
Context
for a number of common executor choices. See Executors for general information on executors.- Parameters
executor_spec –
A string identifier for executor variants:
- ”synchronous”, “inline”:
Use a single-process, single-threaded
InlineJobExecutor
- ”threads”:
Use a multi-threaded
ConcurrentJobExecutor
- ”dask-integration”:
Use a JobExecutor that is compatible with the currently active Dask scheduler. See
get_dask_integration_executor()
for more information.- ”dask-make-default”:
Create a local
dask.distributed
cluster and client usingmake_local()
, similar to the default behaviour ofContext()
called with no arguments. However, the Client will be set as the default Dask scheduler and will persist after the LiberTEM Context closes, which is suitable for downstream computation usingdask.distributed
.- ”delayed”:
Create a
DelayedJobExecutor
which performs computation using dask.delayed. This functionality is highly experimental at this time, see Create Dask arrays with UDFs for more information.- ”pipelined”:
Create a
PipelinedExecutor
, which is suitable for multi-process streaming live processing using LiberTEM-live.
*args – Passed to
Context
.**kwargs – Passed to
Context
.
- Return type
Instance of
Context
using a new instance of the specified executor.
- map(dataset: DataSet, f, roi: Optional[Union[ndarray, SparseArray, spmatrix, Tuple[int], Iterable[Tuple[Tuple[int], bool]]]] = None, progress: bool = False, corrections: CorrectionSet = None, backends=None) BufferWrapper [source]
Create an
AutoUDF
with functionf()
and run it ondataset
Changed in version 0.5.0: Added the
progress
parameterChanged in version 0.6.0: Added the
corrections
andbackends
parameter- Parameters
dataset – The dataset to work on
f – Function that accepts a frame as the only parameter. It should return a strongly reduced output compared to the size of a frame.
roi (numpy.ndarray, sparse array or coordinate tuple(s), optional) – Region of interest as bool mask over the navigation axes of the dataset. See Regions of interest.
progress (bool) – Show progress bar
corrections – Corrections to apply while running the function. If none are given, the corrections that are part of the
DataSet
are used, if there are any. See also Corrections.backends (None or iterable containing 'numpy', 'cupy' and/or 'cuda') – Restrict the back-end to a subset of the capabilities of the UDF. This can be useful for testing hybrid UDFs.
- Returns
BufferWrapper – The result of the UDF. Access the underlying numpy array using the
data
property. Shape and dtype is inferred automatically fromf
.- Return type
- run(job: Analysis, roi: Optional[Union[ndarray, SparseArray, spmatrix, Tuple[int], Iterable[Tuple[Tuple[int], bool]]]] = None, progress: bool = False, corrections: Optional[CorrectionSet] = None) Union[ndarray, AnalysisResultSet] [source]
Run the given
Analysis
and return the result data.Changed in version 0.5.0: Added the
progress
parameterChanged in version 0.6.0: Added the
corrections
parameterChanged in version 0.7.0: Removed deprecated Job support, now only UDF-based analyses are supported
- Parameters
job – the analysis to run
roi (numpy.ndarray, sparse array or coordinate tuple(s), optional) – Boolean mask of the navigation dimension. See Regions of interest.
progress (bool) – Show progress bar
corrections – Corrections to apply, i.e. dark frame substraction, applying a gain map, …
- Returns
result – Running an Analysis returns a
libertem.analysis.base.AnalysisResultSet
. See the matchingcreate_*_analysis
function for documentation of the specificAnalysisResultSet
subclass ornumpy.ndarray
that is being returned.- Return type
- run_udf(dataset: DataSet, udf: Union[UDF, Iterable[UDF]], roi: Optional[Union[ndarray, SparseArray, spmatrix, Tuple[int], Iterable[Tuple[Tuple[int], bool]]]] = None, corrections: Optional[CorrectionSet] = None, progress: bool = False, backends=None, plots=None, sync=True) Union[Mapping[str, BufferWrapper], List[Mapping[str, BufferWrapper]], Coroutine[None, None, Mapping[str, BufferWrapper]], Coroutine[None, None, List[Mapping[str, BufferWrapper]]]] [source]
Run
udf
ondataset
, restricted to the region of interestroi
.Changed in version 0.5.0: Added the
progress
parameterChanged in version 0.6.0: Added the
corrections
andbackends
parameterChanged in version 0.7.0: Added the
plots
andsync
parameters, and the ability to run multiple UDFs on the same data in a single pass.- Parameters
dataset – The dataset to work on
udf – UDF instance you want to run, or a list of UDF instances
roi (numpy.ndarray, sparse array or coordinate tuple(s), optional) – Region of interest as bool mask over the navigation axes of the dataset. See Regions of interest.
progress (bool) – Show progress bar
corrections – Corrections to apply while running the UDF. If none are given, the corrections that are part of the
DataSet
are used, if there are any. See also Corrections.backends (None or iterable containing 'numpy', 'cupy' and/or 'cuda') – Restrict the back-end to a subset of the capabilities of the UDF. This can be useful for testing hybrid UDFs.
plots (None or True or List[List[Union[str, Tuple[str, Callable]]]] or List[LivePlot]) –
None
: don’t plot anything (default)True
: plot all 2D UDF result buffersList[List[...]]
: plot the named UDF buffers. Pass a list of names or (name, callable) tuples for each UDF you want to plot. If the callable is specified, it is applied to the UDF buffer before plotting.List[LivePlot]
:LivePlot
instance for each channel you want to plot
New in version 0.7.0.
sync (bool) –
By default, run_udf is a synchronous method. If sync is set to False, it is awaitable instead.
New in version 0.7.0.
- Returns
Return value of the UDF containing the result buffers of type
libertem.common.buffers.BufferWrapper
. Note that aBufferWrapper
can be used like anumpy.ndarray
in many cases because it implements__array__()
. You can access the underlying numpy array using thedata
property.If a list of UDFs was passed in, the returned type is a Tuple[dict[str,BufferWrapper]].
- Return type
Examples
Run the
SumUDF
on a data set:>>> from libertem.udf.sum import SumUDF >>> result = ctx.run_udf(dataset=dataset, udf=SumUDF()) >>> np.array(result["intensity"]).shape (32, 32) >>> # intensity is the name of the result buffer, defined in the SumUDF
Running a UDF on a subset of data:
>>> from libertem.udf.sumsigudf import SumSigUDF >>> roi = np.zeros(dataset.shape.nav, dtype=bool) >>> roi[0, 0] = True >>> result = ctx.run_udf(dataset=dataset, udf=SumSigUDF(), roi=roi) >>> # to get the full navigation-shaped results, with NaNs where the `roi` was False: >>> np.array(result["intensity"]).shape (16, 16) >>> # to only get the selected results as a flat array: >>> result["intensity"].raw_data.shape (1,)
- run_udf_iter(dataset: DataSet, udf: Union[UDF, Iterable[UDF]], roi: Optional[Union[ndarray, SparseArray, spmatrix, Tuple[int], Iterable[Tuple[Tuple[int], bool]]]] = None, corrections: CorrectionSet = None, progress: bool = False, backends=None, plots=None, sync=True) Union[Generator[UDFResults, None, None], AsyncGenerator[UDFResults, None]] [source]
Run
udf
ondataset
, restricted to the region of interestroi
. Yields partial results after each merge operation.New in version 0.7.0.
- Parameters
dataset – The dataset to work on
udf – UDF instance you want to run, or a list of UDF instances
roi (numpy.ndarray, sparse array or coordinate tuple(s), optional) – Region of interest as bool mask over the navigation axes of the dataset. See Regions of interest.
progress (bool) – Show progress bar
corrections – Corrections to apply while running the UDF. If none are given, the corrections that are part of the
DataSet
are used, if there are any. See also Corrections.backends (None or iterable containing 'numpy', 'cupy' and/or 'cuda') – Restrict the back-end to a subset of the capabilities of the UDF. This can be useful for testing hybrid UDFs.
plots (None or True or List[List[Union[str, Tuple[str, Callable]]]] or List[LivePlot]) –
None
: don’t plot anything (default)True
: plot all 2D UDF result buffersList[List[...]]
: plot the named UDF buffers. Pass a list of names or (name, callable) tuples for each UDF you want to plot. If the callable is specified, it is applied to the UDF buffer before plotting.List[LivePlot]
:LivePlot
instance for each channel you want to plot
sync (bool) – By default, run_udf_iter is a synchronous method. If sync is set to False, an async generator will be returned instead.
- Returns
Generator of
UDFResults
container objects. Their attributebuffers
is the list of result buffer dictionaries for the UDFs. Attributedamage
is aBufferWrapper
ofkind='nav'
,dtype=bool
indicating the positions in nav space that have been processed already.- Return type
Generator[UDFResults]
Examples
Run the
SumUDF
on a data set:>>> from libertem.udf.sum import SumUDF >>> for result in ctx.run_udf_iter(dataset=dataset, udf=SumUDF()): ... assert np.array(result.buffers[0]["intensity"]).shape == (32, 32) >>> np.array(result.buffers[0]["intensity"]).shape (32, 32) >>> # intensity is the name of the result buffer, defined in the SumUDF
Analysis API
- class libertem.analysis.base.Analysis(dataset: DataSet, parameters: Dict)[source]
Abstract base class for Analysis classes.
An Analysis is the interface between a UDF and the Web API, and handles visualization of partial and full results.
Passing an instance of an
Analysis
sub-class tolibertem.api.Context.run()
will generate anAnalysisResultSet
. The content of this result set is governed by the specific implementation of theAnalysis
sub-class.New in version 0.3.0.
Changed in version 0.7.0: Removed deprecated methods
get_results
andget_job
- get_roi() Optional[ndarray] [source]
Get the region of interest the UDF should be run on. For example, the parameters could describe some geometry, which this method should convert to a boolean array. See also:
libertem.analysis.getroi.get_roi()
- Returns
region of interest for which we want to run our analysis
- Return type
numpy.ndarray or None
- get_udf() UDF [source]
Set TYPE=’UDF’ on the class and implement this method to run a UDF from this analysis
- get_udf_results(udf_results: Dict[str, BufferWrapper], roi: Optional[ndarray], damage: nt.ArrayLike) AnalysisResultSet [source]
Convert UDF results to a
AnalysisResultSet
, including visualizations.- Parameters
udf_results – raw results from the UDF
roi (numpy.ndarray or None) – Boolean array of the navigation dimension
- Returns
one or more annotated results
- Return type
list of AnalysisResult
- need_rerun(old_params: Dict, new_params: Dict) bool [source]
Determine if the analysis needs to be re-run on the data. If not, we can just call get_udf_results again, for example if the parameters only change the visualization.
- Parameters
old_params (Dict) –
new_params (Dict) –
- Returns
True iff the parameter change needs to cause a re-run on the data
- Return type
- class libertem.analysis.base.AnalysisResult(raw_data: ndarray, visualized: ndarray, title: str, desc: str, key: str, include_in_download: bool = True)[source]
This class represents a single 2D image result from an Analysis.
Instances of this class are contained in an
AnalysisResultSet
.- raw_data
The raw numerical data of this result
- Type
- visualized
Visualized result as
numpy.ndarray
with RGB or RGBA values- Type
- key
Key to identify the result in an
AnalysisResultSet
- Type
- class libertem.analysis.base.AnalysisResultSet(results: Union[List[AnalysisResult], Callable[[], List[AnalysisResult]]], raw_results=None)[source]
Base class for Analysis result sets.
libertem.api.Context.run()
returns an instance of this class or a subclass. Many of the subclasses are just introduced to document the Analysis-specific results (keys) of the result set and don’t introduce new functionality.The contents of an
AnalysisResultSet
can be addressed in four different ways:As a container class with the
AnalysisResult.key
properties as attributes of typeAnalysisResult
.As a list of
AnalysisResult
objects.As an iterator of
AnalysisResult
objects (since 0.3).As a dictionary of
AnalysisResult
objects with theAnalysisResult.key
properties as keys.
This allows to implement generic result handling code for an Analysis, for example GUI display, as well as specific code for particular Analysis subclasses.
- raw_results
Raw results from the underlying numerical processing, if available, otherwise None.
Examples
>>> mask_shape = tuple(dataset.shape.sig) >>> def m0(): ... return np.ones(shape=mask_shape) >>> def m1(): ... result = np.zeros(shape=mask_shape) ... result[0,0] = 1 ... return result >>> analysis = ctx.create_mask_analysis( ... dataset=dataset, factories=[m0, m1] ... ) >>> result = ctx.run(analysis) >>> # As an object with attributes >>> print(result.mask_0.title) mask 0 >>> print(result.mask_1.title) mask 1 >>> # As a list >>> print(result[0].title) mask 0 >>> # As an iterator >>> # New since 0.3.0 >>> for m in result: ... print(m.title) mask 0 mask 1 >>> # As a dictionary >>> print(result['mask_1'].title) mask 1
- class libertem.analysis.masks.MasksResultSet(results: Union[List[AnalysisResult], Callable[[], List[AnalysisResult]]], raw_results=None)[source]
Running a
MasksAnalysis
vialibertem.api.Context.run()
on a dataset returns an instance of this class.If any of the masks or the dataset contain complex numbers, the regular mask results attributes carry the absolute value of the results, and additional attributes with real part, imaginary part, phase and full complex result are available.
New in version 0.3.0.
- mask_0, mask_1, ..., mask_<n>
For dataset and masks containing only real numbers: Results of the element-wise multiplication and sum of each individual mask with each detector frame. Each mask result has the shape of the navigation dimension. These keys contain the absolute value of the result if dataset or masks contain complex numbers.
- mask_0, mask_0_real, mask_0_imag, mask_0_angle, mask_0_complex, mask_1, mask_1_real, ..., mask_<n>, ..., mask_<n>_complex
If masks or dataset contain complex numbers: Absolute, real part, imaginary part, phase angle, complex result of the element-wise multiplication and sum of each individual mask with each detector frame. Each mask result has the shape of the navigation dimension.
- class libertem.analysis.masks.SingleMaskResultSet(results: Union[List[AnalysisResult], Callable[[], List[AnalysisResult]]], raw_results=None)[source]
A number of Analyses that are based on applying a single mask create an instance of this class as a result when executed via
libertem.api.Context.run()
.If the dataset contains complex numbers, the regular result attribute carries the absolute value of the result, and additional attributes with real part, imaginary part, phase and full complex result are available.
New in version 0.3.0.
- intensity
Sum of the selected region for each detector frame, with shape of the navigation dimension. Absolute of the result if the dataset or mask contains complex numbers.
- intensity_log
Log-scaled sum of the selected region for each detector frame, with shape of the navigation dimension. Absolute of the result if the dataset or mask contains complex numbers.
New in version 0.6.0.
- intensity_real
Real part of the sum of the selected region. This is only available if the dataset or mask contains complex numbers.
- intensity_imag
Imaginary part of the sum of the selected region. This is only available if the dataset contains complex numbers.
- intensity_angle
Phase angle of the sum of the selected region. This is only available if the dataset or mask contains complex numbers.
- intensity_complex
Complex result of the sum of the selected region. This is only available if the dataset or mask contains complex numbers.
- class libertem.analysis.com.COMResultSet(results: Union[List[AnalysisResult], Callable[[], List[AnalysisResult]]], raw_results=None)[source]
Running a
COMAnalysis
vialibertem.api.Context.run()
on a dataset returns an instance of this class.This analysis is usually applied to datasets with real values. If the dataset contains complex numbers, this result contains the keys
x_real
,y_real
,x_imag
,y_imag
instead of the vector field.By default, the shift is given in pixel coordinates, i.e. positive x shift goes to the right and positive y shift goes to the bottom. See also Concepts.
Changed in version 0.6.0: The COM analysis now supports flipping the y axis and rotating the vectors.
New in version 0.3.0.
- field
Center of mass shift relative to the center given to the analysis within the given radius as a vector field with components (x, y). The visualized result uses a cubehelix color wheel.
- magnitude
Magnitude of the center of mass shift.
- divergence
Divergence of the center of mass vector field at a given point
- curl
Curl of the center of mass 2D vector field at a given point.
New in version 0.6.0.
- x
X component of the center of mass shift
- y
Y component of the center of mass shift
- x_real
Real part of the x component of the center of mass shift (complex dataset only)
- y_real
Real part of y component of the center of mass shift (complex dataset only)
- x_imag
Imaginary part of the x component of the center of mass shift (complex dataset only)
- y_imag
Imaginary part of y component of the center of mass shift (complex dataset only)
- libertem.analysis.com.guess_corrections(y_centers: ndarray, x_centers: ndarray, roi: Optional[Union[ndarray, Tuple[slice, ...]]] = None) GuessResult [source]
Guess corrections for center shift,
scan_rotation
andflip_y
from CoM dataThis function can generate a CoM parameter guess for atomic resolution 4D STEM data by using the following assumptions:
The field is purely electrostatic, i.e. the RMS curl should be minimized
There is no net field over the field of view and no descan error, i.e. the mean deflection is zero.
Atomic resolution STEM means that the divergence will be negative at atom columns and consequently the histogram of divergence will have a stronger tail towards negative values than towards positive values.
If any corrections were applied when generating the input data, please note that the corrections should be applied relative to these previous value. In particular, the center corrections returned by this function have to be back-transformed to the uncorrected coordinate system, for example with
apply_correction(..., forward=False)
- Parameters
y_centers (numpy.ndarray) – 2D arrays with y and x component of the center of mass shift for each scan position, as returned by
center_shifts()
orapply_correction()
x_centers (numpy.ndarray) – 2D arrays with y and x component of the center of mass shift for each scan position, as returned by
center_shifts()
orapply_correction()
roi (Optional[numpy.ndarray]) – Selector for values to consider in the statistics, compatible with indexing an array with the shape of y_centers and x_centers. By default, everything except the last row and last column are used since these contain artefacts.
- Returns
GuessResult
- Return type
relative to current values
- class libertem.analysis.sum.SumResultSet(results: Union[List[AnalysisResult], Callable[[], List[AnalysisResult]]], raw_results=None)[source]
Running a
SumAnalysis
vialibertem.api.Context.run()
returns an instance of this class.If the dataset contains complex numbers, the regular result attribute carries the absolute value of the result and additional attributes with real part, imaginary part, phase and full complex result are available.
New in version 0.3.0.
- intensity
Sum of all detector frames along the navigation dimension, preserving the signal dimension. Absolute value of the sum if the dataset contains complex numbers. Log-scaled visualization.
- intensity_lin
Sum of all detector frames along the navigation dimension, preserving the signal dimension. Absolute value of the sum if the dataset contains complex numbers. Lin-scaled visualization.
New in version 0.6.0.
- intensity_real
Real part of the sum of all detector frames along the navigation dimension, preserving the signal dimension. This is only available if the dataset contains complex numbers.
- intensity_imag
Imaginary part of the sum of all detector frames along the navigation dimension, preserving the signal dimension. This is only available if the dataset contains complex numbers.
- intensity_angle
Phase angle of the sum of all detector frames along the navigation dimension, preserving the signal dimension. This is only available if the dataset contains complex numbers.
- intensity_complex
Complex result of the sum of all detector frames along the navigation dimension, preserving the signal dimension. This is only available if the dataset contains complex numbers.
- class libertem.analysis.raw.PickResultSet(results: Union[List[AnalysisResult], Callable[[], List[AnalysisResult]]], raw_results=None)[source]
Running a
PickFrameAnalysis
vialibertem.api.Context.run()
returns an instance of this class.If the dataset contains complex numbers, the regular result attribute carries the absolute value of the result and additional attributes with real part, imaginary part, phase and full complex result are available.
New in version 0.3.0.
Changed in version 0.4.0: Picking now returns data in the native dtype of the dataset with the new UDF back-end.
- intensity
The specified detector frame. Absolute value if the dataset contains complex numbers. Log-scaled visualization.
- intensity_lin
The specified detector frame. Absolute value if the dataset contains complex numbers. Linear visualization.
New in version 0.6.0.
- intensity_real
Real part of the specified detector frame. This is only available if the dataset contains complex numbers.
- intensity_imag
Imaginary part of the specified detector frame. This is only available if the dataset contains complex numbers.
- intensity_angle
Phase angle of the specified detector frame. This is only available if the dataset contains complex numbers.
- intensity_complex
Complex result of the specified detector frame. This is only available if the dataset contains complex numbers.