User API¶
The qpimage API is built upon the hdf5 file format using
h5py. That means that each instance of
qpimage.QPImage
generates an hdf5 file,
either on disk or in memory, depending on the preferences of the user. This
approach has the advantage that phase and amplitude data can be cached on disk,
including all parameters that were used for background correction, which
allows to transparently recapture any steps that were performed on a
specific data set at a later time point.
Basic usage¶
A typical use case of qpimage is
qpi = qpimage.QPImage(data=phase_ndarray, which_data="phase")
# perform phase-tilt background correction
qpi.compute_bg(which_data="phase", # correct phase image
fit_offset="fit", # use bg offset from tilt fit
fit_profile="tilt", # perform 2D tilt fit
border_px=5, # use 5 px border around image
)
# save the background-corrected phase to a text file
numpy.savetxt("out.txt", qpi.pha)
which creates an instance of QPImage containing otherwise experimentally obtained phase data, performs a phase-tilt background correction and then saves the corrected phase data to the text file “out.txt”. In this case, all data are stored in memory.
Storing QPImage data on disk¶
To cache the QPImage data on disk, use the with
statement in combination with the h5file
keyword argument
with qpimage.QPImage(data=phase_ndarray, which_data="phase", h5file="/path/to/file.h5") as qpi:
qpi.compute_bg(which_data="phase",
fit_offset="fit",
fit_profile="tilt",
border_px=5,
)
where all data is stored in /path/to/file.h5
. This will create an hdf5
file on disk that, at a later time point, can be used to create an instance
of QPImage:
# open previously cached data for reading
qpi = qpimage.QPImage(h5file="/path/to/file.h5", h5mode="r")
# or open cached data for writing (e.g. for changing the background)
with qpimage.QPImage(h5file="/path/to/file.h5", h5mode="a") as qpi:
# do something here
The default value of h5mode
is “a”, which means that data
will be overridden. In the hdf5 file, the following data is stored:
- all data for reproducing the background-corrected phase
(
qpi.pha
) and amplitude (qpi.amp
) (and thus fieldqpi.field
), including- the experimental phase data
- the experimental background data
- the parameters for reproducing the result of
qpi.compute_bg
- all measurement specific meta data, given by the keyword argument
meta_data
Dealing with measurement series¶
Qpimage also comes with a QPSeries
class for handling multiple instances of QPImage in one hdf5 file.
For instance, to combine two QPImages in one series file, one could
use:
paths = ["file_a.h5", "file_b.h5", "file_c.h5"]
with qpimage.QPSeries(h5file="/path/to/series_file.h5", h5mode="w") as qps:
for ii, pp in enumerate(paths):
qpi = qpimage.QPImage(h5file="/path/to/file.h5", h5mode="r")
qps.add_qpimage(qpi=qpi, identifier="my_name_{}".frmat(ii))
Note that the function add_qpimage accepts the optional keyword argument “identifier” (overriding the identifier of the QPImage) which can also be used for indexing later:
with qpimage.QPSeries(h5file="/path/to/series_file.h5", h5mode="r") as qps:
# these two are equivalent
qpi = qps[0]
qpi = qps["my_name_0"]
Notes¶
- Even though the hdf5 data is stored as gzip-compressed single precision
floating point values, using qpimage hdf5 files
may result in file sizes that are considerably
larger compared to when only the output of e.g.
qpi.pha
is stored using e.g.numpy.save()
. - Units in qpimage follow the international system of units (SI).
qpimage.QPSeries
provides a convenient way to manage multipleqpimage.QPImage
, optionally storing them in a single hdf5 file.