PEARL Procedures rev-distro-2.1.1-1-gf419e92-dirty Igor procedures for the analysis of PEARL data

Namespaces | Functions | Variables
pearl-pshell-import.ipf File Reference
ARPES package

import data from PShell More...

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

Go to the source code of this file.

## 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 = 1
| 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:

- psh5_open_file()
- psh5_close_file()
- psh5_list_scans()
- psh5_list_scan_datasets()
- psh5_load_scan_meta()
- psh5_load_scan_attrs()

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

## ◆ find_attr_folder()

static dfr find_attr_folder | ( | dfref | dataDF | ) |
| static

find the attributes data folder

this is the :attr folder.

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

## ◆ find_scale_wave()

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

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

## ◆ find_scan_folder()

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 1459 of file pearl-pshell-import.ipf.

## ◆ ps_detect_scale()

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 1621 of file pearl-pshell-import.ipf.

## ◆ ps_scale_dataset()

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 1550 of file pearl-pshell-import.ipf.

## ◆ ps_scale_dataset_2()

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 1781 of file pearl-pshell-import.ipf.

## ◆ ps_scale_datasets()

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 1504 of file pearl-pshell-import.ipf.

## ◆ ps_set_dimlabels()

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 1383 of file pearl-pshell-import.ipf.

## ◆ ps_set_dimlabels2()

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 1402 of file pearl-pshell-import.ipf.

## ◆ psh5_close_file()

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 140 of file pearl-pshell-import.ipf.

## ◆ psh5_list_scan_datasets()

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 440 of file pearl-pshell-import.ipf.

## ◆ psh5_list_scan_regions()

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 481 of file pearl-pshell-import.ipf.

## ◆ psh5_list_scans()

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 405 of file pearl-pshell-import.ipf.

## ◆ psh5_load_complete()

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 170 of file pearl-pshell-import.ipf.

## ◆ psh5_load_dataset()

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 706 of file pearl-pshell-import.ipf.

## ◆ psh5_load_dataset_meta()

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 1091 of file pearl-pshell-import.ipf.

## ◆ psh5_load_dataset_reduced()

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 2040 of file pearl-pshell-import.ipf.

## ◆ psh5_load_dataset_slab()

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 1284 of file pearl-pshell-import.ipf.

## ◆ psh5_load_dataset_slabs()

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 1148 of file pearl-pshell-import.ipf.

## ◆ psh5_load_info()

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 2367 of file pearl-pshell-import.ipf.

## ◆ psh5_load_preview()

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 251 of file pearl-pshell-import.ipf.

## ◆ psh5_load_reduced()

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 1911 of file pearl-pshell-import.ipf.

## ◆ psh5_load_scan_attrs()

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 554 of file pearl-pshell-import.ipf.

## ◆ psh5_load_scan_complete()

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 361 of file pearl-pshell-import.ipf.

## ◆ psh5_load_scan_data()

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 514 of file pearl-pshell-import.ipf.

## ◆ psh5_load_scan_info()

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 2414 of file pearl-pshell-import.ipf.

## ◆ psh5_load_scan_meta()

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)
- Iterations (ScanIterations) - if present (XPSSpectrum script)
- Step Size (ScanStepSize) - if present (XPSSpectrum script)
- Step Time (ScanStepTime) - if present (XPSSpectrum script)

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 625 of file pearl-pshell-import.ipf.

## ◆ psh5_load_scan_preview()

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 840 of file pearl-pshell-import.ipf.

## ◆ psh5_load_scan_section()

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 953 of file pearl-pshell-import.ipf.

## ◆ psh5_open_file()

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 110 of file pearl-pshell-import.ipf.

## ◆ reduce_slab_image()

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

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

## ◆ reduce_slab_worker()

static threadsafe variable reduce_slab_worker | ( | funcref | reduction_func | ) |
| static

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

## ◆ select_dataset()

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 778 of file pearl-pshell-import.ipf.

## ◆ twave2list()

static string twave2list | ( | wave | wt,
|  | string | sep
| ) |  |
| static

convert text wave to list.

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

## ◆ wave2list()

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

convert numeric wave to list.

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

## Variable Documentation

## ◆ kAngleDimLabel

const string kAngleDimLabel = "angle"

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

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

## ◆ kDataDimLabel

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 75 of file pearl-pshell-import.ipf.

## ◆ kDetectorSensitivity

const variable kDetectorSensitivity = 1

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

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

## ◆ kEnergyDimLabel

const string kEnergyDimLabel = "energy"

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

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

## ◆ kPreviewDatasets

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

List of preferred datasets to load for preview.

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

## ◆ kScanDimLabel

const string kScanDimLabel = "scan"

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

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

## ◆ kScientaScalingDatasets

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 81 of file pearl-pshell-import.ipf.

## ◆ kTransposedDatasets

const string kTransposedDatasets = "ScientaImage;"

List of datasets that should be transposed upon loading.

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