import data from PShell More...

#include <HDF5 Browser>
#include "pearl-gui-tools"
#include "pearl-area-import"

Namespaces
	PearlPShellImport
	import data from PShell

Functions
variable	psh5_open_file (string ANickName, string APathName, string AFileName)
	open a HDF5 file created by the PShell data acquisition program and prepare the data folder. More...

variable	psh5_close_file (variable fileID)
	close a HDF5 file opened by psh5_open_file. More...

string	psh5_load_complete (string ANickName, string APathName, string AFileName, variable load_data=defaultValue, variable load_attr=defaultValue)
	load everything from a PShell data file. More...

string	psh5_load_preview (string APathName, string AFileName, variable load_data=defaultValue, variable load_attr=defaultValue, string pref_scans=defaultValue, string pref_datasets=defaultValue)
	load a preview image from a PShell data file. More...

string	psh5_load_scan_complete (variable fileID, string scanpath, variable load_data=defaultValue, variable load_attr=defaultValue)
	load all data of a selected scan from a PShell data file. More...

string	psh5_list_scans (variable fileID)
	list scan groups of a PShell data file. More...

string	psh5_list_scan_datasets (variable fileID, string scanpath, variable include_regions=defaultValue)
	list datasets of a PShell scan group. More...

string	psh5_list_scan_regions (variable fileID, string scanpath)
	list regions of a PShell scan group. More...

string	psh5_load_scan_data (variable fileID, string scanpath)
	load all datasets of a PShell scan group. More...

string	psh5_load_scan_attrs (variable fileID, string scanpath, variable attr_sets=defaultValue)
	load attributes of a PShell scan group. More...

string	psh5_load_scan_meta (variable fileID, string scanpath)
	load metadata of a PShell scan group. More...

string	psh5_load_dataset (variable fileID, string scanpath, string datasetname, variable set_scale=defaultValue)
	load a dataset from an open PShell HDF5 file. More...

static string	select_dataset (string file_datasets, string pref_datasets)
	select the preferred dataset from a list of available datasets. More...

string	psh5_load_scan_preview (variable fileID, string scanpath, variable set_scale=defaultValue, string pref_datasets=defaultValue)
	load a preview dataset from an open PShell HDF5 file. More...

string	psh5_load_scan_section (variable fileID, string scanpath, variable dim, variable set_scale=defaultValue, string pref_datasets=defaultValue)
	load a longitudinal section of a scan from an open PShell HDF5 file. More...

variable	psh5_load_dataset_meta (variable fileID, string datapath, string datasetname, wave datawave)
	load metadata of a PShell dataset. More...

string	psh5_load_dataset_slabs (variable fileID, string datapath, string datasetname, variable progress=defaultValue)
	load a dataset slab-wise from the open PShell HDF5 file. More...

string	psh5_load_dataset_slab (variable fileID, string datapath, string datasetname, variable dim2start, variable dim2count, variable dim3start, variable dim3count)
	load a single image from the open PShell data file. More...

variable	ps_set_dimlabels (wave data)
	set dimension labels according to the axis type More...

variable	ps_set_dimlabels2 (wave data, string name)
	set dimension labels according to the axis type More...

static dfr	find_scan_folder (dfref dataDF)
	find the scan folder More...

static dfr	find_attr_folder (dfref dataDF)
	find the attributes data folder More...

variable	ps_scale_datasets ()
	set the dimension scales of loaded PShell Scienta datasets according to attributes. More...

variable	ps_scale_dataset (wave data)
	set the dimension scales of a loaded PShell Scienta dataset according to attributes. More...

static wave	find_scale_wave (string name, dfref dataDF, dfref scanDF, dfref attrDF)

variable	ps_detect_scale (wave ax, wave lo, wave hi, wave un)
	detect the dimension scales from attributes. More...

variable	ps_scale_dataset_2 (wave data, wave ax, wave lo, wave hi, wave un)
	set the dimension scales of a dataset. More...

string	psh5_load_reduced (string ANickName, string APathName, string AFileName, funcref reduction_func, string reduction_param, variable progress=defaultValue, variable nthreads=defaultValue)
	load and reduce the ScientaImage dataset of the first scan of a PShell data file. More...

string	psh5_load_dataset_reduced (variable fileID, string scanpath, string datasetname, funcref reduction_func, string reduction_param, variable progress=defaultValue, variable nthreads=defaultValue)
	load a reduced dataset from the open PShell HDF5 file. More...

static threadsafe variable	reduce_slab_worker (funcref reduction_func)

static threadsafe wave	reduce_slab_image (wave slabdata, wave image, funcref reduction_func, string reduction_param)

string	psh5_load_info (string APathName, string AFileName)
	load descriptive info from a PShell data file. More...

string	psh5_load_scan_info (variable fileID, string scanpath)
	load descriptive info from a PShell scan. More...

static string	twave2list (wave wt, string sep)
	convert text wave to list. More...

static string	wave2list (wave w, string format, string sep)
	convert numeric wave to list. More...

Variables
const string	kEnergyDimLabel = "energy"
	Dimension label for the energy dispersive dimension of multi-dimensional datasets. More...

const string	kAngleDimLabel = "angle"
	Dimension label for the angle dispersive dimension of multi-dimensional datasets. More...

const string	kScanDimLabel = "scan"
	Dimension label for the scan dimension of multi-dimensional datasets. More...

const string	kDataDimLabel = "data"
	Dimension label for the data dimension. More...

const string	kPreviewDatasets = "ScientaImage;ScientaSpectrum;ImageAngleDistribution;ImageEnergyDistribution;Counts;SampleCurrent;"
	List of preferred datasets to load for preview. More...

const string	kScientaScalingDatasets = "LensMode;ScientaChannelBegin;ScientaChannelEnd;ScientaSliceBegin;ScientaSliceEnd;"
	List of datasets that must be loaded to determine the axis scaling of a Scienta image. More...

const string	kTransposedDatasets = "ScientaImage;"
	List of datasets that should be transposed upon loading. More...

const variable	kDetectorSensitivity = 4
	multiply scienta detector intensity by this value to get actual counts. More...

Detailed Description

import data from PShell

HDF5 file import from the PShell data acquisition program. the main import functions are:

psh5_load_complete() load all scans and datasets from a file.
psh5_load_reduced() load the ScientaImage dataset of the first scan and reduce its dimensionality.
psh5_load_scan_complete() load all datasets of a selected scan.
psh5_load_scan_preview() load a preview of a selected scan.
psh5_load_dataset() load a selected dataset.
psh5_load_dataset_reduced() load a selected dataset and reduce its dimensionality.

the following helper functions are also needed:

Author: matthias muntwiler, matth.nosp@m.ias..nosp@m.muntw.nosp@m.iler.nosp@m.@psi..nosp@m.ch

Copyright: 2013-18 Paul Scherrer Institut
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Definition in file pearl-pshell-import.ipf.

Function Documentation

static dfr find_attr_folder ( dfref dataDF )

static

find the attributes data folder

this is the :attr folder.

Definition at line 1458 of file pearl-pshell-import.ipf.

static wave find_scale_wave	(	string	name,
		dfref	dataDF,
		dfref	scanDF,
		dfref	attrDF
	)

static

Definition at line 1546 of file pearl-pshell-import.ipf.

static dfr find_scan_folder ( dfref dataDF )

static

find the scan folder

the scan folder is the one that contains the :attr folder the data and scan folders may refer to the same folder.

Definition at line 1441 of file pearl-pshell-import.ipf.

variable ps_detect_scale	(	wave	ax,
		wave	lo,
		wave	hi,
		wave	un
	)

detect the dimension scales from attributes.

the function checks the data , scan and attributes folders for scan parameters. the results are written to the provided waves. the function is normally called by ps_scale_datasets() but can also be used independently.

the current datafolder must be the data or the scan folder. the data folder contains the waves that are to be scaled. the scan folder contains the scan positions and the :attr folder.

the provided waves are redimensioned by the function, and dimension labels are set. the scale parameters can then be extracted by keyword, e.g.,

lo[%energy] analyser energy dimension.
lo[%angle] analyser angle dimension.
lo[%scan] scan dimension.
lo[%data] data dimension.

the function tries to read the following waves, in the data, scan, and attributes folders, where the first folder in the list takes precedence. it may fall back to more or less reasonable default values if no data is not found.

LensMode
ScientaChannelBegin
ScientaChannelEnd
ScientaSliceBegin
ScientaSliceEnd
ScanWritables
wave referenced by ScanWritables[0]

Parameters

ax	text wave to receive the axis labels.
lo	wave to receive the lower limits.
hi	wave to receive the upper limits.
un	text wave to receive the unit labels.

Returns: the function results are written to the lo, hi, un, and ax waves.

Version: this function supports regions from version 1.03. check that you're in the correct data folder!

Definition at line 1603 of file pearl-pshell-import.ipf.

variable ps_scale_dataset ( wave data )

set the dimension scales of a loaded PShell Scienta dataset according to attributes.

the current datafolder must contain the :attr folder. the data wave can be in the current folder or a sub-folder.

the dimension labels of the dataset waves must have been set correctly, e.g. by ps_set_dimlabels(). this is implicitly done by the high-level load functions.

the function is useful if a single dataset is loaded and scaled. if multiple datasets are loaded, ps_scale_datasets() is slightly more efficient.

Parameters

data	data wave to be scaled. dimension labels (index -1) must be set correctly, cf. ps_set_dimlabels().

Version: this function supports regions from version 1.03.

Definition at line 1532 of file pearl-pshell-import.ipf.

variable ps_scale_dataset_2	(	wave	data,
		wave	ax,
		wave	lo,
		wave	hi,
		wave	un
	)

set the dimension scales of a dataset.

the function is normally called by ps_scale_datasets() but can also be used independently. the limits and units must be given as function arguments with proper dimension labels.

the provided limit and unit waves must have dimension labels matching the -1 index dimension labels of the data wave, such as set by the ps_detect_scale() function. the scale parameters are extracted by keyword, e.g.,

lo[%energy] analyser energy dimension.
lo[%angle] analyser angle dimension.
lo[%scan] scan dimension.
lo[%data] data dimension.

if the data dimension labels and units are at their defaults ("value" and "arb.", respectively), the function tries to read them from the existing wave note ("AxisLabelD" and "AxisUnitD"), or based on the wave name if the name is one of the known measurement variables: "ScientaImage", "ImageAngleDistribution", "ScientaAngleDistribution", "ScientaSpectrum", "ImageEnergyDistribution", "ScientaEnergyDistribution", "SampleCurrent", "RefCurrent", "AuxCurrent", "MachineCurrent".

Parameters

data	data wave to be scaled. dimension labels (index -1) must be set to match the limit waves.
ax	axis labels. the axis labels are written to the wave note in the format `AxisLabel%s=%s` where `X`, `Y`, `Z`, `D` is substituted for the first place holder and the label for the second one.
lo	lower limits. the lower limits are applied using the SetScale operation.
hi	upper limits. the upper limits are applied using the SetScale operation.
un	unit labels. the unit labels are applied using the SetScale operation.

Version: this function supports regions from version 1.03.

Definition at line 1763 of file pearl-pshell-import.ipf.

variable ps_scale_datasets ( )

set the dimension scales of loaded PShell Scienta datasets according to attributes.

datasets listed in the ScanReadables waves are scaled according to the attribute waves in the data, scan, and attributes folders, whichever is found first.

the current datafolder must contain the ScanReadables wave and the :attr folder. the ScanReadables text wave contains names of the waves to scale. wave names can include a relative path to a sub-folder. the path separator is "/".

the dimension labels of the dataset waves must have been set correctly, e.g. by ps_set_dimlabels(). this is implicitly done by the high-level load functions.

Version: this function supports regions from version 1.03. check that you're in the correct data folder!

Definition at line 1486 of file pearl-pshell-import.ipf.

variable ps_set_dimlabels ( wave data )

set dimension labels according to the axis type

this function asserts a particular ordering of dimensions types based on the name of the wave for ScientaImage, ScientaSpectrum, ImageAngleDistribution, ImageEnergyDistribution. all other waves must be one-dimensional, and the dimension must be the scan dimension.

dimension labels are required by scaling functions.

Parameters

data	data wave as loaded from PShell file

Returns

0 all labels set successfully.
1 unidentified data source.
2 wave does not contain data.

Definition at line 1365 of file pearl-pshell-import.ipf.

variable ps_set_dimlabels2	(	wave	data,
		string	name
	)

set dimension labels according to the axis type

same as ps_set_dimlabels() except that the dimension labels are set according to a separate name argument instead of the wave name.

Parameters

data	data wave as loaded from PShell file.
name	original name of the dataset in the PShell file.

Returns

0 all labels set successfully.
1 unidentified data source.
2 wave does not contain data.

Definition at line 1384 of file pearl-pshell-import.ipf.

variable psh5_close_file ( variable fileID )

close a HDF5 file opened by psh5_open_file.

this function just closes the HDF5 file. no change is made to the loaded data.

Parameters

fileID ID of open HDF5 file from psh5_open_file().

Definition at line 139 of file pearl-pshell-import.ipf.

string psh5_list_scan_datasets	(	variable	fileID,
		string	scanpath,
		variable	include_regions = `defaultValue`
	)

list datasets of a PShell scan group.

the function returns a list of all datasets of the selected scan. this does not include datasets from the attributes sub-group.

Note: in a future version, an option may be introduced to filter datasets by function (Readable and/or Writable).

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
scanpath	path to the scan group in the HDF5 file, e.g. "/scan 1".

Returns: semicolon-separated list of dataset paths.

Version: since version 1.03 this function returns paths relative to scanpath.

Definition at line 439 of file pearl-pshell-import.ipf.

string psh5_list_scan_regions	(	variable	fileID,
		string	scanpath
	)

list regions of a PShell scan group.

the function returns a list of all region groups of the selected scan.

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
scanpath	path to the scan group in the HDF5 file, e.g. "/scan 1".

Returns: semicolon-separated list of datagroup paths.

Definition at line 480 of file pearl-pshell-import.ipf.

string psh5_list_scans ( variable fileID )

list scan groups of a PShell data file.

the function returns a list of all top-level groups whose name starts with "scan".

Parameters

fileID ID of open HDF5 file from psh5_open_file().

Returns: semicolon-separated list of group paths.

Definition at line 404 of file pearl-pshell-import.ipf.

string psh5_load_complete	(	string	ANickName,
		string	APathName,
		string	AFileName,
		variable	load_data = `defaultValue`,
		variable	load_attr = `defaultValue`
	)

load everything from a PShell data file.

Parameters

ANickName	destination folder name (top level under root)
APathName	igor symbolic path name. can be empty if the path is specified in FileName or a dialog box should be displayed
AFileName	if empty a dialog box shows up
load_data	select whether datasets (positioners and detectors) are loaded. 1 (default) load data. 0 do not load data.
load_attr	select whether attributes (auxiliary device readbacks) are loaded. for proper wave scaling, the attributes must be loaded. 1 (default) load attributes. 0 do not load attributes.

Returns: complete path of the loaded file if successful. empty string otherwise.; global string s_filepath in new data folder contains the full file path on disk.; global string s_scanpaths in new data folder contains a list of scan groups inside the file.

Definition at line 169 of file pearl-pshell-import.ipf.

string psh5_load_dataset	(	variable	fileID,
		string	scanpath,
		string	datasetname,
		variable	set_scale = `defaultValue`
	)

load a dataset from an open PShell HDF5 file.

if the dataset has a maximum of two dimensions, the function loads it at once. if it has more than two dimension, the function calls psh5_load_dataset_slabs() to load the data slab by slab.

the metadata (HDF5 attributes) are loaded into the wave note, cf. psh5_load_dataset_meta().
dimension labels are set according the dataset name, cf. ps_set_dimlabels().
wave scaling is set if the necessary scan attributes have been loaded and the set_scale option is selected (default). the attributes must be loaded by psh5_load_scan_meta() and psh5_load_scan_attrs() (attr_sets=2).

the dataset is loaded into the current data folder unless datasetname contains a region specifier. in the latter case, the dataset is loaded into sub-folder with the name of the region. the function returns from the original data folder.

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
scanpath	path to the scan group in the HDF5 file, e.g. "/scan 1".
datasetname	name of the dataset. the name of the loaded wave is a cleaned up version of the dataset name. the name can include the region name as a relative path, e.g. "region1/ScientaSpectrum". in this case, the dataset is loaded into a sub-folder named "region1".
set_scale	by default, the function tries to set the wave scaling if the attributes have been loaded. if multiple datasets are loaded from a file, it is more efficient to set the scaling of all loaded datasets at the end by calling ps_scale_datasets(). 1 (default) set the wave scaling. 0 do not set the wave scaling.

Returns: name of loaded wave if successful. empty string otherwise.

Version: this function supports regions as of version 1.03.

Definition at line 688 of file pearl-pshell-import.ipf.

variable psh5_load_dataset_meta	(	variable	fileID,
		string	datapath,
		string	datasetname,
		wave	datawave
	)

load metadata of a PShell dataset.

"metadata" are the HDF5 attributes attached to the scan dataset.

data is added to the wave note.

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
datapath	path to the containing group in the HDF5 file. path separator is the slash "/".
datasetname	name of the dataset. may include relative path.
datawave	metadata is added to the wave note of this wave.

Returns: 0 if successful, non-zero if an error occurred.

Definition at line 1073 of file pearl-pshell-import.ipf.

string psh5_load_dataset_reduced	(	variable	fileID,
		string	scanpath,
		string	datasetname,
		funcref	reduction_func,
		string	reduction_param,
		variable	progress = `defaultValue`,
		variable	nthreads = `defaultValue`
	)

load a reduced dataset from the open PShell HDF5 file.

the function loads the dataset image by image using the hyperslab option and applies a custom reduction function to each image. the results from the reduction function are written to the ReducedData1, ReducedData2, etc. waves. the raw data are discarded.

by default, the reduction function is called in separate threads to reduce the total loading time. (see the global variable psh5_perf_secs which reports the total run time of the function.) the effect varies depending on the balance between file loading (image size) and data processing (complexity of the reduction function). for debugging the reduction function, multi-threading can be disabled.

if the reduction function requires the image waves to be scaled properly, the attributes must have been loaded by psh5_load_scan_attrs() before. in this case, the scales of the result waves are also set by the function. otherwise, the results can also be scaled by ps_scale_dataset() later.

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
scanpath	path to scan group in the HDF5 file.
datasetname	name of the dataset. this must currently be "ScientaImage", other data is not supported. the name of the loaded wave is a cleaned up version of the dataset name. the name can include the region name as a relative path, e.g. "region1/ScientaImage". in this case, the dataset is loaded into a sub-folder named "region1".
reduction_func	custom data reduction function. this can be any user-defined function which has the same parameters as adh5_default_reduction. some reduction functions are predefined in the PearlScientaPreprocess module.
reduction_param	parameter string for the reduction function.
progress	progress window. 1 (default) show progress window 0 do not show progress window
nthreads	-1 (default) use as many threads as there are processor cores (in addition to main thread). 0 use main thread only (for debugging and profiling). >= 1 use a fixed number of (additional) threads.

Returns: semicolon-separated list of the loaded dataset ReducedData1, ReducedData2, etc. if successful. auxiliary waves, scan positions, attributes are loaded but not listed in the string. empty string if an error occurred. error messages are printed to the history.

Version: this function supports regions as of version 1.03.

Definition at line 2022 of file pearl-pshell-import.ipf.

string psh5_load_dataset_slab	(	variable	fileID,
		string	datapath,
		string	datasetname,
		variable	dim2start,
		variable	dim2count,
		variable	dim3start,
		variable	dim3count
	)

load a single image from the open PShell data file.

the function can average over a region in the extra dimensions.

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
datapath	path to the containing group in the HDF5 file. path separator is the slash "/".
dataset	name of the dataset. also defines the name of the loaded wave.
dim2start	2nd dimension coordinate of the first image set to 0 if dimension may not be present
dim2count	number of subsequent images to average set to 1 if dimension may not be present
dim3start	3rd dimension coordinate of the first image set to 0 if dimension may not be present
dim3count	number of subsequent images to average set to 1 if dimension may not be present

Returns: name of loaded wave if successful. empty string otherwise.

Definition at line 1266 of file pearl-pshell-import.ipf.

string psh5_load_dataset_slabs	(	variable	fileID,
		string	datapath,
		string	datasetname,
		variable	progress = `defaultValue`
	)

load a dataset slab-wise from the open PShell HDF5 file.

the function loads the dataset image by image using the hyperslab option.

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
datapath	path to the containing group in the HDF5 file. path separator is the slash "/".
dataset	name of the dataset. also defines the name of the loaded wave.
progress	select whether a progress window is displayed during the process. 1 (default) show progress window. 0 do not show progress window.

Returns: name of loaded wave if successful. empty string otherwise.

Definition at line 1130 of file pearl-pshell-import.ipf.

string psh5_load_info	(	string	APathName,
		string	AFileName
	)

load descriptive info from a PShell data file.

the info string lists the following information for each scan contained in the file:

path of the scan group inside the file.
number of scan positions.
dataset names of scan positioners.
dataset names of detectors.

Parameters

APathName	igor symbolic path name. can be empty if the path is specified in AFileName or a dialog box should be displayed
AFileName	if empty a dialog box shows up

Returns: newline terminated string.

Definition at line 2349 of file pearl-pshell-import.ipf.

string psh5_load_preview	(	string	APathName,
		string	AFileName,
		variable	load_data = `defaultValue`,
		variable	load_attr = `defaultValue`,
		string	pref_scans = `defaultValue`,
		string	pref_datasets = `defaultValue`
	)

load a preview image from a PShell data file.

the data wave is loaded into the current data folder. attributes are loaded into the attr subfolder. existing waves in attr are deleted.

Parameters

APathName	igor symbolic path name. can be empty if the path is specified in FileName or a dialog box should be displayed
AFileName	if empty a dialog box shows up
load_data	1 (default): load data; 0: do not load data
load_attr	1 (default): load attributes; 0: do not load attributes note: for correct scaling of the image, the attributes need to be loaded
pref_scans	semicolon-separated list of preferred scans. the items of the list are match strings for the Igor StringMatch function. the first matching scan (i.e. top-level HDF5 group with a matching name) is loaded from the file. if no match is found, the first scan is loaded.
pref_datasets	semicolon-separated list of preferred datasets. the items of the list are match strings for the Igor StringMatch function. the first matching dataset is loaded from the file. if no match is found, the first dataset listed in the file is loaded.

Returns: name of loaded preview wave.

Definition at line 250 of file pearl-pshell-import.ipf.

string psh5_load_reduced	(	string	ANickName,
		string	APathName,
		string	AFileName,
		funcref	reduction_func,
		string	reduction_param,
		variable	progress = `defaultValue`,
		variable	nthreads = `defaultValue`
	)

load and reduce the ScientaImage dataset of the first scan of a PShell data file.

the resulting dataset is reduced in one image dimension by a user-defined reduction function, e.g. by region-of-interest integration, curve fitting, etc. cf. adh5_default_reduction for further details.

the function loads the dataset image by image using the hyperslab option and applies a custom reduction function to each image. the results from the reduction function are composed into one result wave. the raw data are discarded.

if the data is from the electron analyser driver and some special attributes are included, the function will set the scales of the image dimensions.

by default, the reduction function is called in separate threads to reduce the total loading time. (see the global variable psh5_perf_secs which reports the total run time of the function.) the effect varies depending on the balance between file loading (image size) and data processing (complexity of the reduction function). for debugging the reduction function, multi-threading can be disabled.

Parameters

ANickName	destination folder name (top level under root).
APathName	igor symbolic path name. can be empty if the path is specified in FileName or a dialog box should be displayed.
AFileName	if empty a dialog box shows up.
reduction_func	custom data reduction function. this can be any user-defined function which has the same parameters as adh5_default_reduction. some reduction functions are predefined in the PearlScientaPreprocess module.
reduction_param	parameter string for the reduction function.
progress	progress window. 1 (default) show progress window 0 do not show progress window
nthreads	-1 (default) use as many threads as there are processor cores (in addition to main thread). 0 use main thread only (for debugging and profiling). >= 1 use a fixed number of (additional) threads.

Returns: semicolon-separated list of the loaded dataset ReducedData1, ReducedData2, etc. if successful. auxiliary waves, scan positions, attributes are loaded but not listed in the string. empty string if an error occurred. error messages are printed to the history.; global string s_filepath in new data folder contains the full file path on disk.; global string s_scanpaths in new data folder contains a list of scan groups inside the file.

Definition at line 1893 of file pearl-pshell-import.ipf.

string psh5_load_scan_attrs	(	variable	fileID,
		string	scanpath,
		variable	attr_sets = `defaultValue`
	)

load attributes of a PShell scan group.

"attributes" are the auxiliary data inside the attrs group. do not confuse with HDF5 attributes! HDF5 attributes are loaded by the psh5_load_scan_meta() function.

data is loaded into the current data folder. this should normally be the :attr folder inside the respective scan folder.

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
scanpath	path to the scan group in the HDF5 file, e.g. "/scan 1".
attr_sets	specify the attribute sets to be loaded. this value can be an arithmetic OR of the following constants. by default, all attributes are loaded. 1 all datasets that are present in the file. 2 datasets relevant for wave scaling of Scienta data.

Returns: semicolon-separated list of the loaded waves.

Definition at line 553 of file pearl-pshell-import.ipf.

string psh5_load_scan_complete	(	variable	fileID,
		string	scanpath,
		variable	load_data = `defaultValue`,
		variable	load_attr = `defaultValue`
	)

load all data of a selected scan from a PShell data file.

data is loaded into the current data folder. attribute datasets are loaded into sub-folder attr. region datasets are loaded into region sub-folders. existing data, if present, is overwritten.

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
scanpath	path to the scan group in the HDF5 file, e.g. "/scan 1".
load_data	select whether datasets (positioners and detectors) are loaded. 1 (default) load data. 0 do not load data.
load_attr	select whether attributes (auxiliary device readbacks) are loaded. for proper wave scaling, the attributes must be loaded. 1 (default) load attributes. 0 do not load attributes.

Returns: semicolon-separated list of the loaded data waves (excluding attributes).

Definition at line 360 of file pearl-pshell-import.ipf.

string psh5_load_scan_data	(	variable	fileID,
		string	scanpath
	)

load all datasets of a PShell scan group.

data is loaded into the current data folder. region datasets are loaded into the respective region sub-folders.

this function does not scale the datasets. call ps_scale_datasets() separately.

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
scanpath	path to the scan group in the HDF5 file, e.g. "/scan 1".

Returns: semicolon-separated list of the loaded waves.

Definition at line 513 of file pearl-pshell-import.ipf.

string psh5_load_scan_info	(	variable	fileID,
		string	scanpath
	)

load descriptive info from a PShell scan.

the info string contains up to three lines which are made up of the following information:

number of scan positions.
dataset names of scan positioners.
dataset names of detectors (without region names).
region names

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
scanpath	path to scan group in the HDF5 file.

Returns: newline terminated string.

Definition at line 2396 of file pearl-pshell-import.ipf.

string psh5_load_scan_meta	(	variable	fileID,
		string	scanpath
	)

load metadata of a PShell scan group.

metadata are the HDF5 attributes attached to the scan group. the following attributes are loaded. the respective wave names under Igor are given in parentheses.

Dimensions (ScanDimensions)
Writables (ScanWritables)
Readables (ScanReadables)
Steps (ScanSteps)

if they are missing in the file, ScanDimensions and ScanReadables are set to default values assuming the file contains a single spectrum.

data is loaded into the current data folder.

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
scanpath	path to the scan group in the HDF5 file, e.g. "/scan 1".

Returns: semicolon-separated list of the loaded waves.

Definition at line 621 of file pearl-pshell-import.ipf.

string psh5_load_scan_preview	(	variable	fileID,
		string	scanpath,
		variable	set_scale = `defaultValue`,
		string	pref_datasets = `defaultValue`
	)

load a preview dataset from an open PShell HDF5 file.

if the dataset has a maximum of two dimensions, the function loads it at once. if it has more than two dimension, the function selects and loads one two-dimensional slab.

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
scanpath	path to the scan group in the HDF5 file, e.g. "/scan 1".
set_scale	by default, the function tries to set the wave scaling if the attributes have been loaded. if multiple datasets are loaded from a file, it is more efficient to set the scaling of all loaded datasets at the end by calling ps_scale_datasets(). 1 (default) set the wave scaling. 0 do not set the wave scaling.
pref_datasets	semicolon-separated list of preferred datasets. the items of the list are match strings for the Igor StringMatch function. the first matching dataset is loaded from the file. if no match is found, the first dataset listed in the file is loaded. if empty, a hard-coded default preference list is used.

Returns: name of loaded wave if successful. empty string otherwise.

Definition at line 822 of file pearl-pshell-import.ipf.

string psh5_load_scan_section	(	variable	fileID,
		string	scanpath,
		variable	dim,
		variable	set_scale = `defaultValue`,
		string	pref_datasets = `defaultValue`
	)

load a longitudinal section of a scan from an open PShell HDF5 file.

the dataset must have three dimensions.

Parameters

fileID	ID of open HDF5 file from psh5_open_file().
scanpath	path to the scan group in the HDF5 file, e.g. "/scan 1".
dim	reserved, must be 0.
set_scale	by default, the function tries to set the wave scaling if the attributes have been loaded. if multiple datasets are loaded from a file, it is more efficient to set the scaling of all loaded datasets at the end by calling ps_scale_datasets(). 1 (default) set the wave scaling. 0 do not set the wave scaling.
pref_datasets	semicolon-separated list of preferred datasets. the items of the list are match strings for the Igor StringMatch function. the first matching dataset is loaded from the file. if no match is found, the first dataset listed in the file is loaded. if empty, a hard-coded default preference list is used.

Returns: name of loaded wave if successful. empty string otherwise.

Warning: EXPERIMENTAL: this function is under development.

Definition at line 935 of file pearl-pshell-import.ipf.

variable psh5_open_file	(	string	ANickName,
		string	APathName,
		string	AFileName
	)

open a HDF5 file created by the PShell data acquisition program and prepare the data folder.

the function opens a specified or interactively selected HDF5 file, creates a data folder $ANickName under root, and changes to the new data folder.

the file must be closed by psh5_close_file() after use.

Parameters

ANickName	destination folder name (top level under root).
APathName	igor symbolic path name. can be empty if the path is specified in FileName or a dialog box should be displayed
AFileName	if empty a dialog box shows up

Returns: ID of open HDF5 file from HDF5OpenFile. zero if an error occurred.; global string s_filepath in new data folder contains the full file path on disk.; global string s_scanpaths in new data folder contains a list of scan groups inside the file.

Definition at line 109 of file pearl-pshell-import.ipf.

static threadsafe wave reduce_slab_image	(	wave	slabdata,
		wave	image,
		funcref	reduction_func,
		string	reduction_param
	)

static

Definition at line 2323 of file pearl-pshell-import.ipf.

static threadsafe variable reduce_slab_worker ( funcref reduction_func )

static

Definition at line 2284 of file pearl-pshell-import.ipf.

static string select_dataset	(	string	file_datasets,
		string	pref_datasets
	)

static

select the preferred dataset from a list of available datasets.

Parameters

file_datasets	semicolon-separated list of datasets that are available in the file. the items may include a path separated by slashes "/". only the last component of the path is checked.
pref_datasets	semicolon-separated list of preferred datasets. the items of the list are match strings for the Igor StringMatch function. the first matching dataset is loaded from the file. if no match is found, the first file dataset is selected.

Returns: selected dataset.

Definition at line 760 of file pearl-pshell-import.ipf.

static string twave2list	(	wave	wt,
		string	sep
	)

static

convert text wave to list.

Definition at line 2455 of file pearl-pshell-import.ipf.

static string wave2list	(	wave	w,
		string	format,
		string	sep
	)

static

convert numeric wave to list.

Definition at line 2472 of file pearl-pshell-import.ipf.

Variable Documentation

const string kAngleDimLabel = "angle"

Dimension label for the angle dispersive dimension of multi-dimensional datasets.

Definition at line 67 of file pearl-pshell-import.ipf.

const string kDataDimLabel = "data"

Dimension label for the data dimension.

This label may be used to store the parameters for the setscale d operation.

Definition at line 74 of file pearl-pshell-import.ipf.

const variable kDetectorSensitivity = 4

multiply scienta detector intensity by this value to get actual counts.

Definition at line 86 of file pearl-pshell-import.ipf.

const string kEnergyDimLabel = "energy"

Dimension label for the energy dispersive dimension of multi-dimensional datasets.

Definition at line 64 of file pearl-pshell-import.ipf.

const string kPreviewDatasets = "ScientaImage;ScientaSpectrum;ImageAngleDistribution;ImageEnergyDistribution;Counts;SampleCurrent;"

List of preferred datasets to load for preview.

Definition at line 77 of file pearl-pshell-import.ipf.

const string kScanDimLabel = "scan"

Dimension label for the scan dimension of multi-dimensional datasets.

Definition at line 70 of file pearl-pshell-import.ipf.

const string kScientaScalingDatasets = "LensMode;ScientaChannelBegin;ScientaChannelEnd;ScientaSliceBegin;ScientaSliceEnd;"

List of datasets that must be loaded to determine the axis scaling of a Scienta image.

Definition at line 80 of file pearl-pshell-import.ipf.

const string kTransposedDatasets = "ScientaImage;"

List of datasets that should be transposed upon loading.

Definition at line 83 of file pearl-pshell-import.ipf.

Namespaces

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation