File MIES_Utilities_WaveHandling.ipf

utility functions for wave handling

Functions

variable EnsureLargeEnoughWave(wave wv, variable indexShouldExist = defaultValue, variable dimension = defaultValue, variable initialValue = defaultValue, variable checkFreeMemory = defaultValue)

Redimension the wave to at least the given size.

The redimensioning is only done if it is required.

Can be used to fill a wave one at a time with the minimum number of redimensions. In the following example NOTE_INDEX is the index of the next free row and the total number of rows filled with data.

Make/FREE/N=(MINIMUM_WAVE_SIZE) data
SetNumberInWaveNote(data, NOTE_INDEX, 0)
// ...
for(...)
    index = GetNumberFromWaveNote(data, NOTE_INDEX)
    // ...
    EnsureLargeEnoughWave(data, dimension = ROWS, indexShouldExist = index)
    data[index] = ...
    // ...
    SetNumberInWaveNote(data, NOTE_INDEX, ++index)
endfor

Parameters:

  • wv – wave to redimension

  • indexShouldExist – [optional, default is implementation defined] the minimum size of the wave. The actual size of the wave after the function returns might be larger.

  • dimension – [optional, defaults to ROWS] dimension to resize, all other dimensions are left untouched.

  • initialValue – [optional, defaults to zero] initialValue of the new wave points

  • checkFreeMemory – [optional, defaults to false] check if the free memory is enough for increasing the size

Returns:

0 on success, (only for checkFreeMemory = True) 1 if increasing the wave’s size would fail due to out of memory

variable EnsureSmallEnoughWave(wave wv, variable maximumSize = defaultValue)

Resize the number of rows to maximumSize if it is larger than that.

Parameters:

  • wv – wave to redimension

  • maximumSize – maximum number of the rows, defaults to MAXIMUM_SIZE

wave GetWaveDimensions(wave wv)

Return a wave with MAX_DIMENSION_COUNT entries with the size of each dimension.

static variable GetWaveSizeImplementation(wave wv)

Returns the size of the wave in bytes.

variable GetSizeOfType(wave wv)

Return the size in bytes of a given type.

Inspired by http://www.igorexchange.com/node/1845

variable GetWaveSize(WaveOrNull wv, variable recursive = defaultValue)

Returns the size of the wave in bytes.

variable GetLockState(wave wv)

Return the lock state of the passed wave.

variable GetNumberFromWaveNote(wave wv, string key)

Returns the numeric value of key found in the wave note, returns NaN if it could not be found.

The expected wave note format is: key1:val1;key2:val2; UTF_NOINSTRUMENTATION

variable SetNumberInWaveNote(wave wv, string key, variable val, string format = defaultValue)

Updates the numeric value of key found in the wave note to val

The expected wave note format is: key1:val1;key2:val2;

Parameters:

  • wv – wave

  • key – key of the Key/Value pair

  • val – value of the Key/Value pair

  • format – [optional] printf compatible format string to set the conversion to string for val

string GetStringFromWaveNote(wave wv, string key, string keySep = defaultValue, string listSep = defaultValue, variable recursive = defaultValue)

Return the string value of key found in the wave note default expected wave note format: key1:val1;key2:str2; counterpart of AddEntryIntoWaveNoteAsList when supplied with keySep = “=”.

Parameters:

  • wv – wave reference where the WaveNote is taken from

  • key – search for the value at key:value;

  • keySep – [optional, defaults to DEFAULT_KEY_SEP] separation character for (key, value) pairs

  • listSep – [optional, defaults to DEFAULT_LIST_SEP] list separation character

  • recursive – [optional, defaults to false] checks all wave notes in referenced waves from wave reference waves

Returns:

the value on success. An empty string is returned if it could not be found

variable SetStringInWaveNote(wave wv, string key, string str, variable recursive = defaultValue, string keySep = defaultValue, string listSep = defaultValue)

Update the string value of key found in the wave note to str

The expected wave note format is: key1:val1;key2:str2;

variable AddEntryIntoWaveNoteAsList(wave wv, string key, variable var = defaultValue, string str = defaultValue, variable appendCR = defaultValue, variable replaceEntry = defaultValue, string format = defaultValue)

Structured writing of numerical values with names into wave notes.

The general layout is key1 = var;key2 = str; and the note is never prefixed with a carriage return (“\r”).

Parameters:

  • wv – wave to add the wave note to

  • key – string identifier

  • var – variable to output

  • str – string to output

  • appendCR – 0 (default) or 1, should a carriage return (“\r”) be appended to the note

  • replaceEntry – 0 (default) or 1, should existing keys named key be replaced (does only work reliable in wave note lists without carriage returns).

  • format – [optional, defaults to g] format string used for converting var to str

variable HasEntryInWaveNoteList(wave wv, string key, string value)

Checks if key = value; can be found in the wave note.

Ignores spaces around the equal (“=”) sign.

See also

AddEntryIntoWaveNoteAsList()

string UniqueWaveName(dfref dfr, string baseName)

Returns a wave name not used in the given datafolder.

Basically a datafolder aware version of UniqueName for datafolders

Parameters:

  • dfr – datafolder reference where the new datafolder should be created

  • baseName – first part of the wave name

wave DuplicateSubRange(wave wv, variable first, variable last)

Return a new wave from the subrange of the given 1D wave.

variable GetRowWithSameContent(WaveText refWave, WaveText sourceWave, variable row)

Search the row in refWave which has the same contents as the given row in the sourceWave.

wave GetColfromWavewithDimLabel(wave wv, string dimLabel)

Returns the column from a multidimensional wave using the dimlabel.

wave MakeWaveFree(WaveOrNull wv)

Turn a persistent wave into a free wave.

variable SetDimensionLabels(wave wv, string list, variable dim, variable startPos = defaultValue)

Sets the dimension labels of a wave.

Parameters:

  • wv – Wave to add dim labels

  • list – List of dimension labels, semicolon separated.

  • dim – Wave dimension, see, WaveDimensions

  • startPos – [optional, defaults to 0] First dimLabel index

wave DeepCopyWaveRefWave(WaveRefWave src, variable dimension = defaultValue, variable index = defaultValue, wave indexWave = defaultValue)

Return a wave with deep copies of all referenced waves.

The deep copied waves will be free waves. Does allow invalid wave references in src.

Parameters:

  • src – wave reference wave

  • dimension – [optional] copy only a single dimension, requires index or indexWave as well

  • index – [optional] specifies the index into dimension, index is not checked

  • indexWave – [optional] specifies the indizes into dimension, allows for differing indizes per src entry, indices are not checked

variable ReduceWaveDimensionality(WaveOrNull wv, variable minDimension = defaultValue)

Shrinks a waves dimensionality if higher dimensions have size 1.

Parameters:

  • wv – Wave that should be shrinked

  • minDimension – [optional, default COLS] shrinks a wave only up to this dimension, e.g. with minDimension = LAYERS a wave of size (1,1,1,1) is shrinked to (1,1,1,0).

variable RemoveAllDimLabels(WaveOrNull wv)

Remove the dimlabels of all dimensions with data.

Due to no better solutions the dim labels are actually overwritten with an empty string

variable WaveModCountWrapper(wave wv)

Return the modification count of the (permanent) wave.

Returns NaN when running in a preemptive thread

UTF_NOINSTRUMENTATION

wave MergeTwoWaves(wave wv1, wave wv2)

Merge two floating point waves labnotebook waves.

The result will hold the finite row entry of either wv1 or wv2.

variable ChangeWaveLock(WaveRefWave wv, variable val)

Adapt the wave lock status on the wave and its contained waves.

variable DeleteWavePoint(wave wv, variable dim, variable index = defaultValue, wave indices = defaultValue)

Deletes one row, column, layer or chunk from a wave Advantages over DeletePoints: Keeps the dimensionality of the wave when deleting the last row, column, layer or chunk in a wave Implements range check Advantages over DeletePoints + KillWaves: The wave reference stays valid.

Parameters:

  • wv – wave where the row, column, layer or chunk should be deleted

  • dim – dimension 0 - rows, 1 - column, 2 - layer, 3 - chunk

  • index – [optional, default n/a] index where one point in the given dimension is deleted

  • indices – [optional, default n/a] 1d numerical wave with indices of points to delete

variable RemoveTextWaveEntry1D(WaveText w, string entry, variable options = defaultValue, variable all = defaultValue)

Removes found entry from a text wave.

Parameters:

  • w – text wave

  • entry – element content to compare

  • options – [optional, defaults to “whole wave element”] FindValue/TXOP options

  • all – [optional, defaults to false] removes all entries

Returns:

0 if at least one entry was found, 1 otherwise

std::tuple<WaveText, WaveText> SplitTextWaveBySuffix(WaveText source, string suffix)

Splits a 1d text wave into two waves. The first contains elements with a suffix, the second elements without.

Parameters:

  • source – [in] 1d text wave

  • suffix – [in] string suffix to distinguish elements

Returns:

two 1d text waves, the first contains all elements with the suffix, the second all elements without

wave WaveRef(WaveOrNull w, variable row = defaultValue, variable col = defaultValue, variable layer = defaultValue, variable chunk = defaultValue)

Helper function to be able to index waves stored in wave reference waves in wave assignment statements.

The case where wv contains wave references is also covered by the optional parameters. While returned regular waves can be indexed within the assignment as shown in the first example, this does not work for wave reference waves. Thus, the parameters allow to index through the function call.

Example for source containing regular waves:

Make/FREE data1 = p Make/FREE data2 = p^2 Make/FREE/WAVE source = {data1, data2}

Make/FREE dest dest[] = WaveRef(source[0])[p] + WaveRef(source[1])[p] // note the direct indexing [p] following WaveRef(…) here

Example for source containing wave ref waves:

Make/FREE data1 = p Make/FREE/WAVE interm = {data1, data1} Make/FREE/WAVE source = {interm, interm}

Make/FREE/WAVE/N=2 dest dest[] = WaveRef(source[p], row = 0) // direct indexing does not work here, so we index through the optional function parameter

row, col, layer, chunk are evaluated in this order until one argument is not given.

UTF_NOINSTRUMENTATION

Parameters:

  • w – input wave ref wave

  • row – [optional, default = n/a] when param set returns wv[row] typed

  • col – [optional, default = n/a] when param row and this set returns wv[row][col] typed

  • layer – [optional, default = n/a] when param row, col and this set returns wv[row][col][layer] typed

  • chunk – [optional, default = n/a] when param row, col, layer and this set returns wv[row][layer][chunk] typed

Returns:

untyped waveref of wv or typed wave ref of wv when indexed

string WaveText(WaveOrNull w, variable row = defaultValue, variable col = defaultValue, variable layer = defaultValue, variable chunk = defaultValue)

Compensate IP not having a way to dynamically extract a string from an untyped, i.e. numeric, wave.

UTF_NOINSTRUMENTATION

wave SelectWave(variable condition, WaveOrNull waveIfFalse, WaveOrNull waveIfTrue)

Helper function for multithread statements where ? : does not work with wave references.

The order of arguments is modelled after SelectString/SelectNumber.

wave RemoveUnusedRows(wave wv)

Remove unused rows from the passed wave and return a copy of it.

If the wave is empty with index being zero, we return a wave with one point so that we:

  • can store something non-empty

  • preserve the dimension labels (this can get lost for empty waves when duplication/saving)

See also

EnsureLargeEnoughWave()

wave DuplicateWaveToFree(wave w)

Duplicates the input wave to a free wave and returns the free wave reference.

wave ZapNaNs(wave data)

Removes all NaNs from the input wave.

variable ChangeFreeWaveName(wave wv, string name)

Give the free wave wv the name name

wave ZapNullRefs(WaveRefWave input)
wave SplitWavesToDimension(WaveRefWave input, variable sdim = defaultValue)

Split multidimensional waves inside input to the given dimension.

Parameters:

  • input – wave reference wave

  • sdim – [optional, defaults to 1] dimensionality to split to

variable FindFirstNaNIndex(wave wv)

Returns the first row index that is NaN from the floating point wave wv, NaN if no index is NaN.

variable SetDimensionLabelsFromWaveContents(wave wv, string prefix = defaultValue, string suffix = defaultValue, variable strict = defaultValue)

Sets the DimLabels for elements of a 1d numerical or text wave based on the content of the wave For numerical waves the wave element is treated as integer For textual waves the elements must translate to a valid DimLabel.

Parameters:

  • wv – input wave

  • prefix – [optional: default “” for numerical waves and NUM_ for textual waves] prefix of the dimlabel For numerical waves it is recommended to provide an own prefix.

  • suffix – [optional: default “”] suffix of the dimlabel

  • strict – [optional: default 0] When this flag is set then each constructed DimLabels for text wave elements are checked if it results in a valid DimLabel, it is also checked if duplicate Dimlabels would be created.

wave ConvertFreeWaveToPermanent(wave freeWave, dfref dfr, string wName)

Converts a free wave to a permanent wave with Overwrite.

Parameters:

  • freeWave – [in] wave that should be converted to a permanent wave

  • dfr – [in] data folder where permanent wave is stored

  • wName – [in] name of permanent wave that is created

Returns:

wave reference to the permanent wave

wave MoveFreeWaveToPermanent(wave freeWave, dfref dfr, string wvName)
variable DuplicateWaveAndKeepTargetRef(WaveOrNull source, WaveOrNull target)

Duplicate a source wave to a target wave and keep the target wave reference intact. Use with free/local waves. For global waves use “Duplicate/O source, target”.

Parameters:

  • source – source wave

  • target – target wave

variable SearchForDuplicates(wave wv)

Detects duplicate values in a 1d wave.

Returns:

one if duplicates could be found, zero otherwise

wave FindNeighbourDuplicates(wave wv)

Return the indizes of elements which need to be dropped so that no two neighbouring points are equal/both NaN.

wave MoveWaveWithOverwrite(wave dest, wave src, variable recursive = defaultValue)

Move the source wave to the location of the given destination wave. The destination wave must be a permanent wave.

Workaround for MoveWave having no /O flag.

Parameters:

  • dest – permanent wave

  • src – wave (free or permanent)

  • recursive – [optional, defaults to false] Overwrite referenced waves in dest with the ones from src (wave reference waves only with matching sizes)

Returns:

new wave reference to dest wave

variable ZeroWave(wave wv)

Zero the wave using differentiation and integration.

Overwrites the input wave Preserves the WaveNote and adds the entry NOTE_KEY_ZEROED

2D waves are zeroed along each row

Returns:

0 if nothing was done, 1 if zeroed

variable ZeroWaveImpl(wave wv)

Zeroes a wave in place.

variable GetDecimatedWaveSize(variable numRows, variable decimationFactor, variable method)

Return the size of the decimated wave.

Query that to create the output wave before calling DecimateWithMethod().

Parameters:

  • numRows – number of rows in the input wave

  • decimationFactor – decimation factor, must be an integer and larger than 1

  • method – one of DecimationMethods

string GetLastNonEmptyEntry(WaveText wv, string colLabel, variable endRow)

Searches the column colLabel in wv for an non-empty entry with a row number smaller or equal to endRow.

Return an empty string if nothing could be found.

Parameters:

  • wv – text wave to search in

  • colLabel – column label from wv

  • endRow – maximum row index to consider