def load(filenames=None,
record_by=None,
signal_type=None,
signal_origin=None,
stack=False,
stack_axis=None,
new_axis_name="stack_element",
mmap=False,
mmap_dir=None,
**kwds):
"""
Load potentially multiple supported file into an hyperspy structure
Supported formats: HDF5, msa, Gatan dm3, Ripple (rpl+raw)
FEI ser and emi and hdf5, tif and a number of image formats.
Any extra keyword is passed to the corresponsing reader. For
available options see their individual documentation.
Parameters
----------
filenames : None, str or list of strings
The filename to be loaded. If None, a window will open to select
a file to load. If a valid filename is passed in that single
file is loaded. If multiple file names are passed in
a list, a list of objects or a single object containing the data
of the individual files stacked are returned. This behaviour is
controlled by the `stack` parameter (see bellow). Multiple
files can be loaded by using simple shell-style wildcards,
e.g. 'my_file*.msa' loads all the files that starts
by 'my_file' and has the '.msa' extension.
record_by : {None, 'spectrum', 'image', ""}
The value provided may determine the Signal subclass assigned to the
data.
If None, the value is read or guessed from the file. Any other value
overrides the value stored in the file if any.
If "spectrum" load the data in a Spectrum (sub)class.
If "image" load the data in an Image (sub)class.
If "" (empty string) load the data in a Signal class.
signal_type : {None, "EELS", "EDS_TEM", "EDS_SEM", "", str}
The acronym that identifies the signal type.
The value provided may determine the Signal subclass assigned to the
data.
If None the value is read/guessed from the file. Any other value
overrides the value stored in the file if any.
For electron energy-loss spectroscopy use "EELS".
For energy dispersive x-rays use "EDS_TEM"
if acquired from an electron-transparent sample — as it is usually
the case in a transmission electron microscope (TEM) —,
"EDS_SEM" if acquired from a non electron-transparent sample
— as it is usually the case in a scanning electron microscope (SEM) —.
If "" (empty string) the value is not read from the file and is
considered undefined.
signal_origin : {None, "experiment", "simulation", ""}
Defines the origin of the signal.
The value provided may determine the Signal subclass assigned to the
data.
If None the value is read/guessed from the file. Any other value
overrides the value stored in the file if any.
Use "experiment" if loading experimental data.
Use "simulation" if loading simulated data.
If "" (empty string) the value is not read from the file and is
considered undefined.
stack : bool
If True and multiple filenames are passed in, stacking all
the data into a single object is attempted. All files must match
in shape. It is possible to store the data in a memory mapped
temporary file instead of in memory setting mmap_mode. The title is set
to the name of the folder containing the files.
stack_axis : {None, int, str}
If None, the signals are stacked over a new axis. The data must
have the same dimensions. Otherwise the
signals are stacked over the axis given by its integer index or
its name. The data must have the same shape, except in the dimension
corresponding to `axis`.
new_axis_name : string
The name of the new axis when `axis` is None.
If an axis with this name already
exists it automatically append '-i', where `i` are integers,
until it finds a name that is not yet in use.
mmap: bool
If True and stack is True, then the data is stored
in a memory-mapped temporary file.The memory-mapped data is
stored on disk, and not directly loaded into memory.
Memory mapping is especially useful for accessing small
fragments of large files without reading the entire file into
memory.
mmap_dir : string
If mmap_dir is not None, and stack and mmap are True, the memory
mapped file will be created in the given directory,
otherwise the default directory is used.
Returns
-------
Signal instance or list of signal instances
Examples
--------
Loading a single file providing the signal type:
>>> d = load('file.dm3', signal_type='EDS_TEM')
Loading a single file and overriding its default record_by:
>>> d = load('file.dm3', record_by='Image')
Loading multiple files:
>>> d = load('file1.dm3','file2.dm3')
Loading multiple files matching the pattern:
>>>d = load('file*.dm3')
"""
kwds['record_by'] = record_by
kwds['signal_type'] = signal_type
kwds['signal_origin'] = signal_origin
if filenames is None:
if hyperspy.defaults_parser.preferences.General.interactive is True:
from hyperspy.gui.tools import Load
load_ui = Load()
load_ui.edit_traits()
if load_ui.filename:
filenames = load_ui.filename
else:
raise ValueError("No file provided to reader and "
"interactive mode is disabled")
if filenames is None:
raise ValueError("No file provided to reader")
if isinstance(filenames, basestring):
filenames = natsorted(
[f for f in glob.glob(filenames) if os.path.isfile(f)])
if not filenames:
raise ValueError('No file name matches this pattern')
elif not isinstance(filenames, (list, tuple)):
raise ValueError(
'The filenames parameter must be a list, tuple, string or None')
if not filenames:
raise ValueError('No file provided to reader.')
return None
else:
if len(filenames) > 1:
messages.information('Loading individual files')
if stack is True:
signal = []
for i, filename in enumerate(filenames):
obj = load_single_file(filename, **kwds)
signal.append(obj)
signal = hyperspy.utils.stack(signal,
axis=stack_axis,
new_axis_name=new_axis_name,
mmap=mmap,
mmap_dir=mmap_dir)
signal.mapped_parameters.title = \
os.path.split(
os.path.split(
os.path.abspath(filenames[0])
)[0]
)[1]
messages.information('Individual files loaded correctly')
signal._print_summary()
objects = [
signal,
]
else:
objects = [
load_single_file(filename, **kwds) for filename in filenames
]
if hyperspy.defaults_parser.preferences.General.plot_on_load:
for obj in objects:
obj.plot()
if len(objects) == 1:
objects = objects[0]
return objects
def load(filenames=None,
signal_type=None,
stack=False,
stack_axis=None,
new_axis_name="stack_element",
lazy=None,
**kwds):
"""
Load potentially multiple supported file into an hyperspy structure
Supported formats: HDF5, msa, Gatan dm3, Ripple (rpl+raw), Bruker bcf,
FEI ser and emi, hdf5, SEMPER unf, EMD, EDAX spd/spc, tif, and a number
of image formats.
Any extra keyword is passed to the corresponding reader. For
available options see their individual documentation.
Parameters
----------
filenames : None, str or list of strings
The filename to be loaded. If None, a window will open to select
a file to load. If a valid filename is passed in that single
file is loaded. If multiple file names are passed in
a list, a list of objects or a single object containing the data
of the individual files stacked are returned. This behaviour is
controlled by the `stack` parameter (see bellow). Multiple
files can be loaded by using simple shell-style wildcards,
e.g. 'my_file*.msa' loads all the files that starts
by 'my_file' and has the '.msa' extension.
signal_type : {None, "EELS", "EDS_SEM", "EDS_TEM", "", str}
The acronym that identifies the signal type.
The value provided may determine the Signal subclass assigned to the
data.
If None the value is read/guessed from the file. Any other value
overrides the value stored in the file if any.
For electron energy-loss spectroscopy use "EELS".
For energy dispersive x-rays use "EDS_TEM"
if acquired from an electron-transparent sample — as it is usually
the case in a transmission electron microscope (TEM) —,
"EDS_SEM" if acquired from a non electron-transparent sample
— as it is usually the case in a scanning electron microscope (SEM) —.
If "" (empty string) the value is not read from the file and is
considered undefined.
stack : bool
If True and multiple filenames are passed in, stacking all
the data into a single object is attempted. All files must match
in shape. If each file contains multiple (N) signals, N stacks will be
created, with the requirement that each file contains the same number
of signals.
stack_axis : {None, int, str}
If None, the signals are stacked over a new axis. The data must
have the same dimensions. Otherwise the
signals are stacked over the axis given by its integer index or
its name. The data must have the same shape, except in the dimension
corresponding to `axis`.
new_axis_name : string
The name of the new axis when `axis` is None.
If an axis with this name already
exists it automatically append '-i', where `i` are integers,
until it finds a name that is not yet in use.
lazy : {None, bool}
Open the data lazily - i.e. without actually reading the data from the
disk until required. Allows opening arbitrary-sized datasets.
If None, default from preferences is used.
print_info: bool
For SEMPER unf- and EMD (Berkley)-files, if True (default is False)
additional information read during loading is printed for a quick
overview.
Returns
-------
Signal instance or list of signal instances
Examples
--------
Loading a single file providing the signal type:
>>> d = hs.load('file.dm3', signal_type="EDS_TEM")
Loading multiple files:
>>> d = hs.load('file1.dm3','file2.dm3')
Loading multiple files matching the pattern:
>>> d = hs.load('file*.dm3')
Loading (potentially larger than the available memory) files lazily and
stacking:
>>> s = hs.load('file*.blo', lazy=True, stack=True)
"""
deprecated = ['mmap_dir', 'load_to_memory']
warn_str = "'{}' argument is deprecated, please use 'lazy' instead"
for k in deprecated:
if k in kwds:
lazy = True
warnings.warn(warn_str.format(k), VisibleDeprecationWarning)
del kwds[k]
if lazy is None:
lazy = preferences.General.lazy
kwds['signal_type'] = signal_type
if filenames is None:
if preferences.General.interactive is True:
from hyperspy.gui.tools import Load
load_ui = Load()
load_ui.edit_traits()
if load_ui.filename:
filenames = load_ui.filename
else:
raise ValueError("No file provided to reader and "
"interactive mode is disabled")
if filenames is None:
raise ValueError("No file provided to reader")
if isinstance(filenames, str):
filenames = natsorted([f for f in glob.glob(filenames)
if os.path.isfile(f)])
if not filenames:
raise ValueError('No file name matches this pattern')
elif not isinstance(filenames, (list, tuple)):
raise ValueError(
'The filenames parameter must be a list, tuple, string or None')
if not filenames:
raise ValueError('No file provided to reader.')
else:
if len(filenames) > 1:
_logger.info('Loading individual files')
if stack is True:
# We are loading a stack!
# Note that while each file might contain several signals, all
# files are required to contain the same number of signals. We
# therefore use the first file to determine the number of signals.
for i, filename in enumerate(filenames):
obj = load_single_file(filename, lazy=lazy,
**kwds)
if i == 0:
# First iteration, determine number of signals, if several:
if isinstance(obj, (list, tuple)):
n = len(obj)
else:
n = 1
# Initialize signal 2D list:
signals = [[] for j in range(n)]
else:
# Check that number of signals per file doesn't change
# for other files:
if isinstance(obj, (list, tuple)):
if n != len(obj):
raise ValueError(
"The number of sub-signals per file does not "
"match:\n" +
(f_error_fmt % (1, n, filenames[0])) +
(f_error_fmt % (i, len(obj), filename)))
elif n != 1:
raise ValueError(
"The number of sub-signals per file does not "
"match:\n" +
(f_error_fmt % (1, n, filenames[0])) +
(f_error_fmt % (i, len(obj), filename)))
# Append loaded signals to 2D list:
if n == 1:
signals[0].append(obj)
elif n > 1:
for j in range(n):
signals[j].append(obj[j])
# Next, merge the signals in the `stack_axis` direction:
# When each file had N signals, we create N stacks!
objects = []
for i in range(n):
signal = signals[i] # Sublist, with len = len(filenames)
signal = stack_method(
signal, axis=stack_axis, new_axis_name=new_axis_name,
lazy=lazy)
signal.metadata.General.title = os.path.split(
os.path.split(os.path.abspath(filenames[0]))[0])[1]
_logger.info('Individual files loaded correctly')
_logger.info(signal._summary())
objects.append(signal)
else:
# No stack, so simply we load all signals in all files separately
objects = [load_single_file(filename, lazy=lazy,
**kwds)
for filename in filenames]
if preferences.Plot.plot_on_load:
for obj in objects:
obj.plot()
if len(objects) == 1:
objects = objects[0]
return objects
