PEARL Procedures  rev-distro-3.0.0-0-gfa24916-dirty
Igor procedures for the analysis of PEARL data
pearl-data-explorer.ipf File Reference
#include <HierarchicalListWidget>
#include "pearl-area-import"
#include "pearl-area-profiles"
#include "pearl-area-display"
#include "pearl-compat"
#include "pearl-pshell-import"

Go to the source code of this file.

Functions

variable pearl_data_explorer ()
 show the pearl data explorer window More...
 
static variable init_package ()
 
static variable save_prefs ()
 save persistent package data to the preferences file. More...
 
static variable load_prefs ()
 
static variable pearl_file_type (string filename)
 check whether a file can be imported by this module. More...
 
static variable update_filepath ()
 update the file path after path change More...
 
static variable update_filelist ()
 read a list of PEARL files from the file system More...
 
static variable get_file_info (string filename)
 load the internal structure of a file More...
 
static variable attributes_notebook (string filename)
 load attributes More...
 
static variable extract_attributes (dfref attr_df, dfref dest_df=defaultValue, wave attr_filter=defaultValue, variable include_datawaves=defaultValue, variable include_infowaves=defaultValue)
 extract summary from attribute waves More...
 
variable test_attributes_notebook ()
 
static variable create_attributes_notebook (wave attr_names, wave attr_values, string title)
 
static variable notebook_add_attributes (string notebook_name, wave attr_filter, wave attr_names, wave attr_values)
 
static variable set_elog_attributes (dfref file_df, string filename=defaultValue, string graphname=defaultValue)
 send general metadata to ELOG panel - if available More...
 
static variable preview_file (string filename)
 
static wave preview_pshell_file (string filename)
 load the preview of a PShell HDF5 file. More...
 
static wave preview_hdf_file (string filename)
 load the preview of a PEARL HDF5 file. More...
 
static wave preview_itx_file (string filename)
 load the preview of a general ITX file. More...
 
static variable extract_preview_image (wave data, wave preview)
 extract a preview image from a wave of arbitrary dimension More...
 
static variable preview_datafolder ()
 preview data in the current data folder More...
 
static variable preview_setscale_x (wave data, wave preview)
 
static variable display_dataset (dfref file_df, string dataset)
 displays the graph of a loaded dataset in its own window More...
 
static string show_preview_graph (wave data, wave xdata=defaultValue)
 
static string display_preview_trace (wave xtrace, wave ytrace)
 
static variable load_selected_files (string options=defaultValue)
 load the selected files More...
 
static variable load_file (string filename, string options=defaultValue, dfref dest_df=defaultValue, variable quiet=defaultValue)
 load one file More...
 
static variable prompt_hdf_options (string *options)
 
variable prompt_default_process (string *param)
 prototype for prompting for processing function parameters. More...
 
variable prompt_func_params (string func_name, string *func_param)
 
static dfr load_pshell_file (string filename, string options=defaultValue, dfref dest_df=defaultValue, variable quiet=defaultValue)
 load a pshell file More...
 
static dfr load_hdf_file (string filename, string options=defaultValue, dfref dest_df=defaultValue, variable quiet=defaultValue)
 
static dfr load_itx_file (string filename, string options=defaultValue, dfref dest_df=defaultValue, variable quiet=defaultValue)
 
string itx_suggest_foldername (string filename, variable ignoredate=defaultValue, string sourcename=defaultValue, variable unique=defaultValue)
 suggest the name of a data folder based on an igor-text file name More...
 
void PearlDataExplorer ()
 
static variable update_controls ()
 update controls state More...
 
static variable bp_load_prefs (WMButtonAction *ba)
 
static variable bp_save_prefs (WMButtonAction *ba)
 
static string shorten_filepath (string long_path, variable max_len)
 shorten a file path for display More...
 
static variable bp_browse_filepath (WMButtonAction *ba)
 
static variable bp_update_filelist (WMButtonAction *ba)
 
static string pm_reduction_values ()
 items for data reduction popup More...
 
static variable pmp_reduction_func (WMPopupAction *pa)
 
static variable bp_reduction_params (WMButtonAction *ba)
 
static variable bp_load_options (WMButtonAction *ba)
 
static variable selected_file (string file, variable do_preview)
 actions after a file has been selected More...
 
static variable bp_file_next (WMButtonAction *ba)
 
static variable bp_file_prev (WMButtonAction *ba)
 
static variable lbp_filelist (WMListboxAction *lba)
 
static variable bp_attr_notebook (WMButtonAction *ba)
 
static variable hlp_setup ()
 
static variable hl_contents_clear ()
 
static variable hl_contents_update (dfref file_df)
 populate the contents list box with the internal directory of a HDF5 file More...
 
static dfr get_pshell_info (string path_name, string file_name, dfref dest_df=defaultValue)
 
static variable hl_add_objects (string parent_path, string objects)
 populate the contents list box with the given hierarchical paths More...
 
static variable hl_expand_scans ()
 
static variable hl_default_selection ()
 
static variable hlp_contents_open (string HostWindow, string ListControlName, string ContainerPath)
 
static variable hlp_contents_selection (string HostWindow, string ListControlName, string SelectedItem, variable EventCode)
 
static variable goto_dataset_folder (string filename, string datapath)
 open data folder corresponding to a file and data path More...
 
static variable bp_goto_dataset (WMButtonAction *ba)
 "goto DF" button More...
 
static variable bp_display_dataset (WMButtonAction *ba)
 "display dataset" button More...
 
static variable send_to_elog ()
 send file metadata to the ELOG panel More...
 
static variable bp_elog (WMButtonAction *ba)
 

Variables

 version
 
static const string package_path = "root:packages:pearl_explorer:"
 
static const string ks_filematch_adh5 = "*.h5"
 
static const string ks_filematch_pshell = "psh*.h5"
 
static const string ks_filematch_itx = "*.itx"
 

Function Documentation

◆ attributes_notebook()

static variable attributes_notebook ( string  filename)
static

load attributes

Definition at line 301 of file pearl-data-explorer.ipf.

◆ bp_attr_notebook()

static variable bp_attr_notebook ( WMButtonAction *  ba)
static

Definition at line 1914 of file pearl-data-explorer.ipf.

◆ bp_browse_filepath()

static variable bp_browse_filepath ( WMButtonAction *  ba)
static

Definition at line 1673 of file pearl-data-explorer.ipf.

◆ bp_display_dataset()

static variable bp_display_dataset ( WMButtonAction *  ba)
static

"display dataset" button

Definition at line 2263 of file pearl-data-explorer.ipf.

◆ bp_elog()

static variable bp_elog ( WMButtonAction *  ba)
static

Definition at line 2351 of file pearl-data-explorer.ipf.

◆ bp_file_next()

static variable bp_file_next ( WMButtonAction *  ba)
static

Definition at line 1809 of file pearl-data-explorer.ipf.

◆ bp_file_prev()

static variable bp_file_prev ( WMButtonAction *  ba)
static

Definition at line 1840 of file pearl-data-explorer.ipf.

◆ bp_goto_dataset()

static variable bp_goto_dataset ( WMButtonAction *  ba)
static

"goto DF" button

the button selects the data folder of the selected file and dataset. an error message is shown if the data folder doesn't exist.

Definition at line 2231 of file pearl-data-explorer.ipf.

◆ bp_load_options()

static variable bp_load_options ( WMButtonAction *  ba)
static

Definition at line 1757 of file pearl-data-explorer.ipf.

◆ bp_load_prefs()

static variable bp_load_prefs ( WMButtonAction *  ba)
static

Definition at line 1618 of file pearl-data-explorer.ipf.

◆ bp_reduction_params()

static variable bp_reduction_params ( WMButtonAction *  ba)
static

Definition at line 1735 of file pearl-data-explorer.ipf.

◆ bp_save_prefs()

static variable bp_save_prefs ( WMButtonAction *  ba)
static

Definition at line 1633 of file pearl-data-explorer.ipf.

◆ bp_update_filelist()

static variable bp_update_filelist ( WMButtonAction *  ba)
static

Definition at line 1696 of file pearl-data-explorer.ipf.

◆ create_attributes_notebook()

static variable create_attributes_notebook ( wave  attr_names,
wave  attr_values,
string  title 
)
static

Definition at line 480 of file pearl-data-explorer.ipf.

◆ display_dataset()

static variable display_dataset ( dfref  file_df,
string  dataset 
)
static

displays the graph of a loaded dataset in its own window

Definition at line 897 of file pearl-data-explorer.ipf.

◆ display_preview_trace()

static string display_preview_trace ( wave  xtrace,
wave  ytrace 
)
static

Definition at line 978 of file pearl-data-explorer.ipf.

◆ extract_attributes()

static variable extract_attributes ( dfref  attr_df,
dfref  dest_df = defaultValue,
wave  attr_filter = defaultValue,
variable  include_datawaves = defaultValue,
variable  include_infowaves = defaultValue 
)
static

extract summary from attribute waves

by default, all existing attributes are copied. if a text wave attr_filter exists in the pear_explorer folder, only the attributes referenced therein are copied. to set up a filter, duplicate the attr_names wave of a template dataset, and remove unwanted items.

Parameters
attr_dfdata folder which contains the original data, e.g. the attr, diags or snaps folder in pshell files.
dest_dfdestination folder. the output is written to the attr_names and attr_values waves. default = package folder.
attr_filter(text wave) list of attributes allowed in the output. default = use attr_filter of package folder.
include_datawaves
  • 1 (default) include data waves (any numeric wave which has a PV=name note).
  • 0 don't include attributes from data waves.
include_infowaves
  • 1 (default) include attributes from info waves (IN, ID, IV, IU).
  • 0 don't include attributes from info waves.

Definition at line 347 of file pearl-data-explorer.ipf.

◆ extract_preview_image()

static variable extract_preview_image ( wave  data,
wave  preview 
)
static

extract a preview image from a wave of arbitrary dimension

Definition at line 784 of file pearl-data-explorer.ipf.

◆ get_file_info()

static variable get_file_info ( string  filename)
static

load the internal structure of a file

this loads metadata for updating the panels.

for a pshell file, metadata includes:

  • list of all datasets with types and dimensions
  • general group
Returns
0 if successful -1 if no data was loaded because the file was not recognized, -2 if no data is found in file

Definition at line 273 of file pearl-data-explorer.ipf.

◆ get_pshell_info()

static dfr get_pshell_info ( string  path_name,
string  file_name,
dfref  dest_df = defaultValue 
)
static

Definition at line 2001 of file pearl-data-explorer.ipf.

◆ goto_dataset_folder()

static variable goto_dataset_folder ( string  filename,
string  datapath 
)
static

open data folder corresponding to a file and data path

the function tries to find where a given dataset has been loaded and selects the corresponding data folder. the data folder must exist (after previous import from the file), else an error code is returned and the folder selection will be the closest accessible parent folder of the target.

Parameters
filenamefile name (without path). h5 and otf.itx files are supported.
datapathdataset or group path inside the hdf5 file.
Returns
0 if successful, -1 if the file type is unknown -2 if the data path can't be found in the tree.

Definition at line 2175 of file pearl-data-explorer.ipf.

◆ hl_add_objects()

static variable hl_add_objects ( string  parent_path,
string  objects 
)
static

populate the contents list box with the given hierarchical paths

Returns
the number of top-level objects

Definition at line 2029 of file pearl-data-explorer.ipf.

◆ hl_contents_clear()

static variable hl_contents_clear ( )
static

Definition at line 1952 of file pearl-data-explorer.ipf.

◆ hl_contents_update()

static variable hl_contents_update ( dfref  file_df)
static

populate the contents list box with the internal directory of a HDF5 file

Returns
the number of top-level objects

Definition at line 1966 of file pearl-data-explorer.ipf.

◆ hl_default_selection()

static variable hl_default_selection ( )
static

Definition at line 2118 of file pearl-data-explorer.ipf.

◆ hl_expand_scans()

static variable hl_expand_scans ( )
static

Definition at line 2089 of file pearl-data-explorer.ipf.

◆ hlp_contents_open()

static variable hlp_contents_open ( string  HostWindow,
string  ListControlName,
string  ContainerPath 
)
static

Definition at line 2129 of file pearl-data-explorer.ipf.

◆ hlp_contents_selection()

static variable hlp_contents_selection ( string  HostWindow,
string  ListControlName,
string  SelectedItem,
variable  EventCode 
)
static

Definition at line 2139 of file pearl-data-explorer.ipf.

◆ hlp_setup()

static variable hlp_setup ( )
static

Definition at line 1942 of file pearl-data-explorer.ipf.

◆ init_package()

static variable init_package ( )
static

Definition at line 61 of file pearl-data-explorer.ipf.

◆ itx_suggest_foldername()

string itx_suggest_foldername ( string  filename,
variable  ignoredate = defaultValue,
string  sourcename = defaultValue,
variable  unique = defaultValue 
)

suggest the name of a data folder based on an igor-text file name

if the file name follows the naming convention source-date-index.extension, the function tries to generate the nick name as source_date_index. otherwise it's just a cleaned up version of the file name.

igor text is used by the on-the-fly scan tool.

Parameters
filenamefile name, including extension. can also include a folder path (which is ignored). the extension is currently ignored, but may be used in a later version.
ignoredateif non-zero, the nick name will not include the date part. defaults to zero
sourcenamenick name of the data source. the function tries to detect the source from the file name. this option can be used to override auto-detection. allowed values: sscan, otf
uniqueif non-zero, the resulting name is made a unique data folder name in the current data folder. defaults to zero

Definition at line 1427 of file pearl-data-explorer.ipf.

◆ lbp_filelist()

static variable lbp_filelist ( WMListboxAction *  lba)
static

Definition at line 1871 of file pearl-data-explorer.ipf.

◆ load_file()

static variable load_file ( string  filename,
string  options = defaultValue,
dfref  dest_df = defaultValue,
variable  quiet = defaultValue 
)
static

load one file

this can be a PShell, HDF5, or ITX file.

Note
this function may change the current data folder!
Parameters
optionskey:value; list of load options. the recognized keys are: mode, reduction_func and reduction_params. see main text for a description of possible values. by default (options not specified), options are read from `s_hdf_options. if the option string is empty, the user is prompted for options.
dest_dfdestination data folder. default: a new folder derived from file name under root.
quiet
  • 0 (default) print mode and parameters to history.
  • 1 do not print to history.

Definition at line 1064 of file pearl-data-explorer.ipf.

◆ load_hdf_file()

static dfr load_hdf_file ( string  filename,
string  options = defaultValue,
dfref  dest_df = defaultValue,
variable  quiet = defaultValue 
)
static

Definition at line 1298 of file pearl-data-explorer.ipf.

◆ load_itx_file()

static dfr load_itx_file ( string  filename,
string  options = defaultValue,
dfref  dest_df = defaultValue,
variable  quiet = defaultValue 
)
static

Definition at line 1358 of file pearl-data-explorer.ipf.

◆ load_prefs()

static variable load_prefs ( )
static

Definition at line 155 of file pearl-data-explorer.ipf.

◆ load_pshell_file()

static dfr load_pshell_file ( string  filename,
string  options = defaultValue,
dfref  dest_df = defaultValue,
variable  quiet = defaultValue 
)
static

load a pshell file

if options is not specified, the complete file is loaded. if options is an empty string, the package default options are used.

data selection is extracted from the datasets list box.

the file can be loaded in one of the following modes (mode key of the options argument):

  • load_complete load all datasets regardless of selection.
  • load_scan load default datasets of selected scans.
  • load_region load default datasets of selected regions.
  • load_dataset load selected datasets.
  • load_diags load diagnostic datasets of selected scans.

3-dimensional datasets can be loaded with dimension reduction. in this case, the name of the reduction function must be given under the reduction_func key. the reduction parameters are prompted for if a prompt function for the reduction function is found. the default reduction parameters are the most recent parameters s_reduction_params stored in the package data folder.

  • reduction_func:... name of the reduction function.

if a reduction function is specified, default reduction parameters are read from s_reduction_params in the package data folder, and the user is prompted to review/update the parameters.

Parameters
optionskey:value; list of load options. the recognized keys are: mode, reduction_func and reduction_params. see main text for a description of possible values. by default (options not specified), options are read from `s_hdf_options. if the option string is empty, the user is prompted for options.
dest_dfdestination data folder. default: a new folder derived from file name under root.
quiet
  • 0 (default) print mode and parameters to history.
  • 1 do not print to history.
Returns
data folder reference of the loaded data. this is the folder which contains the scan sub-folders.

Definition at line 1188 of file pearl-data-explorer.ipf.

◆ load_selected_files()

static variable load_selected_files ( string  options = defaultValue)
static

load the selected files

load the files that are selected in the data explorer panel. the files are loaded using the load_file() function.

Note
this function may change the current data folder!

Definition at line 1025 of file pearl-data-explorer.ipf.

◆ notebook_add_attributes()

static variable notebook_add_attributes ( string  notebook_name,
wave  attr_filter,
wave  attr_names,
wave  attr_values 
)
static

Definition at line 519 of file pearl-data-explorer.ipf.

◆ pearl_data_explorer()

variable pearl_data_explorer ( )

show the pearl data explorer window

create a pearl data explorer window or bring the existing one to the front. if a new window is created, also initialize all package variables and load package preferences.

Definition at line 47 of file pearl-data-explorer.ipf.

◆ pearl_file_type()

static variable pearl_file_type ( string  filename)
static

check whether a file can be imported by this module.

the file type is determined by the extension of the file name.

Returns
file type
  • 0 not a recognized file type
  • 1 PShell file (HDF5, name starts with psh_)
  • 2 area detector HDF5 file
  • 3 Igor text (itx) file

Definition at line 199 of file pearl-data-explorer.ipf.

◆ PearlDataExplorer()

void PearlDataExplorer ( )

Definition at line 1478 of file pearl-data-explorer.ipf.

◆ pm_reduction_values()

static string pm_reduction_values ( )
static

items for data reduction popup

Definition at line 1712 of file pearl-data-explorer.ipf.

◆ pmp_reduction_func()

static variable pmp_reduction_func ( WMPopupAction *  pa)
static

Definition at line 1719 of file pearl-data-explorer.ipf.

◆ preview_datafolder()

static variable preview_datafolder ( )
static

preview data in the current data folder

used by preview_itx_file

Definition at line 826 of file pearl-data-explorer.ipf.

◆ preview_file()

static variable preview_file ( string  filename)
static

Definition at line 629 of file pearl-data-explorer.ipf.

◆ preview_hdf_file()

static wave preview_hdf_file ( string  filename)
static

load the preview of a PEARL HDF5 file.

the preview is an arbitrary detector image extracted from the file, see adh5_load_preview(). the preview is loaded to the preview_image wave in the pear_explorer data folder.

the s_file_info string is updated with information about the scan dimensions.

Parameters
filenamename of a file in the directory specified by the pearl_explorer_filepath path object.
Returns
wave reference of the preview image

Definition at line 717 of file pearl-data-explorer.ipf.

◆ preview_itx_file()

static wave preview_itx_file ( string  filename)
static

load the preview of a general ITX file.

the function is designed for PEARL OTF and EPICS scan data converted from MDA files. the function picks the first wave whose PV note matches one from the global string s_preview_pvs (see preview_datafolder and init_package).

the preview is loaded to the preview_image wave in the pearl_explorer data folder. the s_file_info string is updated with information about the scan dimensions.

Note
: the ITX files should load their waves into the current data folder (a "free" data folder). some early versions of PEARL ITX data files created a data folder of their own. both ways are allowed, while the first one is preferred. on return, the current data folder must point to either the original free folder or the newly created one.
Parameters
filenamename of a file in the directory specified by the pearl_explorer_filepath path object.
Returns
wave reference of the preview trace. empty wave reference if the function failed.

Definition at line 762 of file pearl-data-explorer.ipf.

◆ preview_pshell_file()

static wave preview_pshell_file ( string  filename)
static

load the preview of a PShell HDF5 file.

the preview is an arbitrary detector image extracted from the file, see adh5_load_preview(). the preview is loaded to the preview_image wave in the pear_explorer data folder.

the s_file_info string is updated with information about the scan dimensions.

Parameters
filenamename of a file in the directory specified by the pearl_explorer_filepath path object.
Returns
wave reference of the preview image

Definition at line 671 of file pearl-data-explorer.ipf.

◆ preview_setscale_x()

static variable preview_setscale_x ( wave  data,
wave  preview 
)
static

Definition at line 866 of file pearl-data-explorer.ipf.

◆ prompt_default_process()

variable prompt_default_process ( string *  param)

prototype for prompting for processing function parameters.

the function should prompt the user for function parameters, and update the param argument if the user clicked OK. returns 0 if the user clicked OK, 1 if the user cancelled.

prompt functions must have the same name as the corresponding reduction function with the prefix "prompt_". be aware of the limited length of function names in Igor.

this function is a prototype. it does nothing but returns OK.

Definition at line 1130 of file pearl-data-explorer.ipf.

◆ prompt_func_params()

variable prompt_func_params ( string  func_name,
string *  func_param 
)

Definition at line 1136 of file pearl-data-explorer.ipf.

◆ prompt_hdf_options()

static variable prompt_hdf_options ( string *  options)
static

Definition at line 1090 of file pearl-data-explorer.ipf.

◆ save_prefs()

static variable save_prefs ( )
static

save persistent package data to the preferences file.

this function is called when the user clicks the corresponding button. the data saved in the file are: data file path, attributes filter

Definition at line 139 of file pearl-data-explorer.ipf.

◆ selected_file()

static variable selected_file ( string  file,
variable  do_preview 
)
static

actions after a file has been selected

  • load metadata
  • load preview if requested
Parameters
filename of selected file
do_previewenable/disable loading of preview data non-zero: load preview, zero: don't load preview

Definition at line 1791 of file pearl-data-explorer.ipf.

◆ send_to_elog()

static variable send_to_elog ( )
static

send file metadata to the ELOG panel

metadate is looked up in the following locations:

  1. data folder if it exists
  2. file info folder inside package folder
  3. package folder if it contains preview data from the selected file (???)

Definition at line 2295 of file pearl-data-explorer.ipf.

◆ set_elog_attributes()

static variable set_elog_attributes ( dfref  file_df,
string  filename = defaultValue,
string  graphname = defaultValue 
)
static

send general metadata to ELOG panel - if available

the following metatdata are sent. they must be present as strings in the specified data folder:

ELOG parameter global string function argument
file s_filepath filename
graph attachment graphname
author authors
p-group pgroup
project proposal
sample sample
Parameters
file_dfdata folder that contains the metadata.
filenameoverride file path read from s_filepath global string variable. if neither is declared, the file name is reset to empty field.
graphnameselect this graph window for attaching. default: do not change the selection.

Definition at line 568 of file pearl-data-explorer.ipf.

◆ shorten_filepath()

static string shorten_filepath ( string  long_path,
variable  max_len 
)
static

shorten a file path for display

Note
the result is not a valid path any more!

Definition at line 1651 of file pearl-data-explorer.ipf.

◆ show_preview_graph()

static string show_preview_graph ( wave  data,
wave  xdata = defaultValue 
)
static

Definition at line 925 of file pearl-data-explorer.ipf.

◆ test_attributes_notebook()

variable test_attributes_notebook ( )

Definition at line 473 of file pearl-data-explorer.ipf.

◆ update_controls()

static variable update_controls ( )
static

update controls state

Definition at line 1557 of file pearl-data-explorer.ipf.

◆ update_filelist()

static variable update_filelist ( )
static

read a list of PEARL files from the file system

wtFiles and wSelectedFiles in the package data folder are updated. only files for which pearl_file_type() returns non-zero are listed.

Definition at line 231 of file pearl-data-explorer.ipf.

◆ update_filepath()

static variable update_filepath ( )
static

update the file path after path change

read the path info from pearl_explorer_filepath and update the path control

Definition at line 218 of file pearl-data-explorer.ipf.

Variable Documentation

◆ ks_filematch_adh5

const string ks_filematch_adh5 = "*.h5"
static

Definition at line 38 of file pearl-data-explorer.ipf.

◆ ks_filematch_itx

const string ks_filematch_itx = "*.itx"
static

Definition at line 40 of file pearl-data-explorer.ipf.

◆ ks_filematch_pshell

const string ks_filematch_pshell = "psh*.h5"
static

Definition at line 39 of file pearl-data-explorer.ipf.

◆ package_path

const string package_path = "root:packages:pearl_explorer:"
static

Definition at line 36 of file pearl-data-explorer.ipf.

◆ version

version
Initial value:
= 1.14
static const string package_name = "pearl_explorer"

Definition at line 6 of file pearl-data-explorer.ipf.

package_name
static const string package_name
package name is used as data folder name
Definition: pearl-anglescan-panel.ipf:48