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

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.

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.

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.

static variable init_package ( )

static

initialize the package data folder.

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

static variable initStruct ( errorCode *  errorCode )

static

from matrixfilereader help

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

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.

variable matrix_preview_2d	(	wave	data,
		wave	metadata
	)

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

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.

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.

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.

variable mtrx_load_all

(

)

load all data from a Matrix data file.

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

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.

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.

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.

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.

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.

variable mtrx_scale_dataset

(

wave

data

)

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

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.

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.

variable subtract_line_bg

(

wave

img

)

remove linear background line-by-line

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

Variable Documentation

const string ks_filematch_mtrx = "*_mtrx"

static

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

const string package_name = "pearl_matrix_import"

static

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

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

static

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