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

Data Structures | Namespaces | Functions | Variables
pearl-matrix-import.ipf File Reference

data file import for omicron matrix (STM) files More...

Go to the source code of this file.

## Data Structures
struct | errorCode
| from matrixfilereader help More...

## Namespaces
| PearlMatrixImport
| data file import for omicron matrix (STM) files

## Functions
static variable | init_package ()
| initialize the package data folder. More...
static variable | check_package_folder ()
| check that the package data folder exists More...
static variable | AfterFileOpenHook (variable refNum, string file, string pathName, string type, string creator, variable kind)
| initialize the package and reload preferences after an experiment is loaded. More...
static variable | BeforeFileOpenHook (variable refNum, string fileName, string path, string type, string creator, variable kind)
| open a matrix file that was dropped into Igor. More...
string | matrix_format_elog_message (wave metadata)
| generate elog message from bricklet metadata More...
variable | matrix_preview_2d (wave data, wave metadata)
static wave | preview_matrix_file (string filename)
| load the preview of a Matrix data file More...
static variable | initStruct (errorCode *errorCode)
| from matrixfilereader help More...
variable | mtrx_load_all ()
| load all data from a Matrix data file. More...
variable | mtrx_parse_filename (string fileName, string *resultFile, variable *runCycle, variable *scanCycle, string *channel)
| parse matrix file names More...
string | mtrx_split_filename (string fileName, string *prefix, string *datepart, string *timepart)
| split a matrix filename and return the first three parts More...
dfr | mtrx_create_folder (string fileName, dfref df_base=defaultValue)
| create or look up a data folder based on a matrix file name. More...
dfr | mtrx_get_cycle_folder (dfref df_base=defaultValue, variable runCycle=defaultValue, variable scanCycle=defaultValue)
| create a data folder for bricklet data. More...
variable | mtrx_file_brickletID (string resultFile, variable runCycle, variable scanCycle, string channel)
| find out bricklet ID of a file More...
variable | mtrx_open_file (string pathName, string fileNameOrPath)
| open a matrix result or data file More...
string | mtrx_load_preview (string destName, string pathName, string fileName, string traces=defaultValue)
| load a preview image from a Matrix data file. More...
string | mtrx_load_file (string pathName, string fileName, string traces=defaultValue)
| load all data from a Matrix data file. More...
variable | mtrx_scale_dataset (wave data)
string | mtrx_load_info (string APathName, string AFileName)
| load descriptive info from a Matrix data file. More...
variable | subtract_line_bg (wave img)
| remove linear background line-by-line More...

## Variables
static const string | package_name = "pearl_matrix_import"
static const string | package_path = "root:packages:pearl_matrix_import:"
static const string | ks_filematch_mtrx = "*_mtrx"

## Detailed Description

data file import for omicron matrix (STM) files

the matrix file import requires the matrix file reader XOP by thomas braun (http://www.igorexchange.com/project/matrixFileReader) which in turn requires an installation of vernissage by omicron nanotechnology.

Warning
  EXPERIMENTAL the matrix import module and its interface may change radically in future revisions!

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

Copyright
  2016 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-matrix-import.ipf.

## Function Documentation

## ◆ AfterFileOpenHook()

static variable AfterFileOpenHook | ( | variable | refNum,
|  | string | file,
|  | string | pathName,
|  | string | type,
|  | string | creator,
|  | variable | kind
| ) |  |
| static

initialize the package and reload preferences after an experiment is loaded.

Definition at line 85 of file pearl-matrix-import.ipf.

## ◆ BeforeFileOpenHook()

static variable BeforeFileOpenHook | ( | variable | refNum,
|  | string | fileName,
|  | string | path,
|  | string | type,
|  | string | creator,
|  | variable | kind
| ) |  |
| static

open a matrix file that was dropped into Igor.

preliminary implementation. this should rather load the entire file and display a preview. graph windows should be reused by subsequent loads. also decide on a data saving location.

Definition at line 102 of file pearl-matrix-import.ipf.

## ◆ check_package_folder()

static variable check_package_folder | ( |  | ) |
| static

check that the package data folder exists

initialize the package if the folder does not exist.

Definition at line 72 of file pearl-matrix-import.ipf.

## ◆ init_package()

static variable init_package | ( |  | ) |
| static

initialize the package data folder.

Definition at line 45 of file pearl-matrix-import.ipf.

## ◆ initStruct()

static variable initStruct | ( | errorCode * | errorCode | ) |
| static

from matrixfilereader help

Definition at line 212 of file pearl-matrix-import.ipf.

## ◆ matrix_format_elog_message()

string matrix_format_elog_message | ( | wave | metadata | ) |

generate elog message from bricklet metadata

Parameters

  metadata | two-column text wave

Definition at line 120 of file pearl-matrix-import.ipf.

## ◆ matrix_preview_2d()

variable matrix_preview_2d | ( | wave | data,
|  | wave | metadata
| ) |  |

Definition at line 145 of file pearl-matrix-import.ipf.

## ◆ mtrx_create_folder()

dfr mtrx_create_folder | ( | string | fileName,
|  | dfref | df_base = `defaultValue`
| ) |  |

create or look up a data folder based on a matrix file name.

the name of the folder is mtrx_date_time, where date and time are parsed from the file name. for this to work, the file name must consist of at least three parts that are separated by dash or underscore. the second (third) part contains the date (time). date and time are copied as strings.

if the data folder exists, a reference to the existing folder is returned.

Parameters

  fileName | name of the result or data file.
  df_base | (optional) base data folder. default: current folder.

Returns
  reference of the newly created or existing data folder.

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

## ◆ mtrx_file_brickletID()

variable mtrx_file_brickletID | ( | string | resultFile,
|  | variable | runCycle,
|  | variable | scanCycle,
|  | string | channel
| ) |  |

find out bricklet ID of a file

Warning
  EXPERIMENTAL the code of this function is inefficient. the function may be removed in a later version.

Parameters

  resultFile | base name of result file without chain link number and extension. as returned by mtrx_parse_filename.
  runCycle | requested run cycle. 0 = first available.
  scanCycle | requested scan cycle. 0 = first available.
  channel | channel name. for example: "I", "Z", "Aux(V)", etc. empty string: first available.

Returns
  bricklet ID, or -1 if an error occurred.

Definition at line 461 of file pearl-matrix-import.ipf.

## ◆ mtrx_get_cycle_folder()

dfr mtrx_get_cycle_folder | ( | dfref | df_base = `defaultValue`,
|  | variable | runCycle = `defaultValue`,
|  | variable | scanCycle = `defaultValue`
| ) |  |

create a data folder for bricklet data.

the name of the folder is, for example "r23s2" where the first (second) number is the run (scan) cycle. run cycle and scan cycle numbers are taken from the open matrix file unless overridden by optional arguments.

if the data folder exists, a reference to the existing folder is returned. if one of the run or scan cycle numbers is lower than 1, the base folder is returned.

Parameters

  df_base | (optional) base data folder. default: current folder.
  runCycle | (optional) run cycle number. must be >= 1. default: from last mtrx_open_file call.
  scanCycle | (optional) scan cycle number. must be >= 1. default: from last mtrx_open_file call.

Returns
  reference of the newly created or existing data folder.

Definition at line 405 of file pearl-matrix-import.ipf.

## ◆ mtrx_load_all()

variable mtrx_load_all | ( |  | ) |

load all data from a Matrix data file.

Definition at line 231 of file pearl-matrix-import.ipf.

## ◆ mtrx_load_file()

string mtrx_load_file | ( | string | pathName,
|  | string | fileName,
|  | string | traces = `defaultValue`
| ) |  |

load all data from a Matrix data file.

the data wave is loaded into a sub-subfolder the current data folder. the relative path has the format ":mtrx_{date}_{time}:r{run_cycle}s{scan_cycle}", where the parameters {date}, {time}, {run_cycle} and {scan_cycle} are copied from the file name. the file name must be formatted according to the specifications set out below.

Parameters

  pathName | igor symbolic path name. can be empty if the path is specified in FileName or a dialog box should be displayed
  fileName | if empty a dialog box shows up the file name must adhere to the format "{prefix}-{date}-{time}-{anything}--{run_cycle}_{scan_cycle}.{extension}". the first three seperators can alternatively be underscores. it may be necessary to change the configuration of the Matrix application.
  traces | (currently not used) semicolon-separated list of preferred traces. the items of the list are match strings for the Igor StringMatch function. only matching traces are loaded from the file. default: "*Up;*Down;*ReUp;*ReDown;"

Returns
  semicolon-separated list of loaded waves including partial path from current data folder.

Definition at line 767 of file pearl-matrix-import.ipf.

## ◆ mtrx_load_info()

string mtrx_load_info | ( | string | APathName,
|  | string | AFileName
| ) |  |

load descriptive info from a Matrix 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 863 of file pearl-matrix-import.ipf.

## ◆ mtrx_load_preview()

string mtrx_load_preview | ( | string | destName,
|  | string | pathName,
|  | string | fileName,
|  | string | traces = `defaultValue`
| ) |  |

load a preview image from a Matrix data file.

the data wave is loaded into the current data folder.

Parameters

  destName | destination wave name. the wave is created in the current data folder.
  pathName | igor symbolic path name. can be empty if the path is specified in FileName or a dialog box should be displayed
  fileName | if empty a dialog box shows up the file name must adhere to the format "{prefix}-{date}-{time}-{anything}--{run_cycle}_{scan_cycle}.{extension}". the first three seperators can alternatively be underscores. it may be necessary to change the configuration of the Matrix application.
  traces | (currently not used) semicolon-separated list of preferred traces. the items of the list are match strings for the Igor StringMatch function. only the first matching trace is loaded from the file. default: "*Up;*Down;*ReUp;*ReDown;"

Returns
  semicolon-separated list of loaded waves including partial path from current data folder.

Definition at line 682 of file pearl-matrix-import.ipf.

## ◆ mtrx_open_file()

variable mtrx_open_file | ( | string | pathName,
|  | string | fileNameOrPath
| ) |  |

open a matrix result or data file

this function opens a matrix result file (.mtrx) or data file (.*_mtrx).

if a data file is selected, the function locates the corresponding result file, opens it, and looks up the bricklet ID of the data file. if a result file is selected, the function opens it but does not look up bricklet IDs.

the result file remains open and can be accessed using the mtrx_ functions or MFR_ operations. once a result file is open, you can easily access any bricklets linked to it, i.e., any run cycle, scan cycle, and channel.

the function stores information about the opened file in a global package data folder. if the same result file is opened again later, the information is reused and the file not read again. this may cause problems if the file has been modified in the meantime, or if the cached data become corrupt for some reason. the function detects if a data file is not linked in the open result file, and updates the cache. in other situations it may be necessary to force a reload.

Todo:
  fix possible cache issues, add an option to override the cache.

Parameters

  pathName | igor path name or empty string.
  fileName | file name, with or without path, or empty string.

Returns
  file type
  - 0 result file (logbook)
  - 1 result data file (bricklet)
  - -1 error, no data loaded
  - -2 matrixfilereader.xop not installed

Definition at line 545 of file pearl-matrix-import.ipf.

## ◆ mtrx_parse_filename()

variable mtrx_parse_filename | ( | string | fileName,
|  | string * | resultFile,
|  | variable * | runCycle,
|  | variable * | scanCycle,
|  | string * | channel
| ) |  |

parse matrix file names

parse matrix file names for result name, run cycle, scan cycle, and channel.

Parameters

  fileName | matrix result or data file name (without path).
  resultFile | (out) base name of the result file. append "_%04u.mtrx" to get the actual result file. we do not know the chain link number at this stage.
  runCycle | (out) run cycle number. necessary to look up the bricklet ID.
  scanCycle | (out) scan cycle number. necessary to look up the bricklet ID.
  channel | (out) channel name.

Returns
  file type
  - 0 result file (logbook)
  - 1 result data file (bricklet)
  result file names look like: default_2015Apr20-124353_STM-STM_AtomManipulation_0001.mtrx, default_2015Apr20-124353_STM-STM_AtomManipulation_0002.mtrx, etc. the function returns the first part up to the experiment name ("AtomManipulation" in the examples). all other return values set to defaults and must not be regarded.

result data files look like: default_2015Apr20-124353_STM-STM_AtomManipulation–136_1.Aux1(V)_mtrx, default_2015Apr20-124353_STM-STM_AtomManipulation–136_1.I(V)_mtrx, default_2015Apr20-124353_STM-STM_AtomManipulation–14_1.I_mtrx, default_2015Apr20-124353_STM-STM_AtomManipulation–14_1.Z_mtrx, etc. the function returns all results as described in the parameter list.

Definition at line 294 of file pearl-matrix-import.ipf.

## ◆ mtrx_scale_dataset()

variable mtrx_scale_dataset | ( | wave | data | ) |

Definition at line 829 of file pearl-matrix-import.ipf.

## ◆ mtrx_split_filename()

string mtrx_split_filename | ( | string | fileName,
|  | string * | prefix,
|  | string * | datepart,
|  | string * | timepart
| ) |  |

split a matrix filename and return the first three parts

we assume that the second (third) part contains the date (time). the parts are separated by dash or underscore.

Definition at line 332 of file pearl-matrix-import.ipf.

## ◆ preview_matrix_file()

static wave preview_matrix_file | ( | string | filename | ) |
| static

load the preview of a Matrix data file

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.

Parameters

  filename | name of a file in the directory specified by the pearl_explorer_filepath path object.

Returns
  wave reference of the preview image

Definition at line 170 of file pearl-matrix-import.ipf.

## ◆ subtract_line_bg()

variable subtract_line_bg | ( | wave | img | ) |

remove linear background line-by-line

Definition at line 886 of file pearl-matrix-import.ipf.

## Variable Documentation

## ◆ ks_filematch_mtrx

const string ks_filematch_mtrx = "*_mtrx"
| static

Definition at line 40 of file pearl-matrix-import.ipf.

## ◆ package_name

const string package_name = "pearl_matrix_import"
| static

Definition at line 37 of file pearl-matrix-import.ipf.

## ◆ package_path

const string package_path = "root:packages:pearl_matrix_import:"
| static

Definition at line 38 of file pearl-matrix-import.ipf.