3. Log files

The LogFile class provides functionality for reading and writing data from Labber log files.

3.1. Reading data from Labber

Labber log files are accessed using the LogFile class, which contain a number of functions for reading and writing data (see class definition below). A LogFile object is created by passing the path to a Labber log file as the first argument.

3.1.1. Log information

A Labber log file contains both instrument settings and measured data, as well as metadata information from the database such as User, Tags, Project and Comment. The following example will print(basic information about the log file TestLog.hdf5:

import Labber

f = Labber.LogFile('TestLog')
print('Number of entries:', f.getNumberOfEntries())

print('Step channels:')
step_channels = f.getStepChannels()
for channel in step_channels:
    print(channel['name'])

print('Log channels:')
log_channels = f.getLogChannels()
for channel in log_channels:
    print(channel['name'])

print('User:', f.getUser())
print('Tags:', f.getTags())
print('Project:', f.getProject())
print('Comment:', f.getComment())

The LogFile class also contains functions for setting log metadata, see the class definition below.

3.1.2. Log data

A Labber log file contains data from one or multiple channels. The data is organized into log entries, where each entry contains a one-dimensional vector of values for each channel. The entries corresponds to the traces shown in the Labber Log Viewer program. The LogFile class provides a number of functions for accessing the data, as illustrated in the example below:

import Labber

f = Labber.LogFile('TestLog')

# get values of all channels for a specific entry (in this case first entry)
d = f.getEntry(0)
for (channel, value) in d.items():
    print(channel, ":", value)

# get entry as x,y data, let Labber determine which channels to read
(x,y) = f.getTraceXY()

# get data for all entries for a specific channel as a 2D numpy array
data = f.getData('Voltage')

For more information on the various class methods, see the class definition below.

3.2. Creating Labber log files

The API provides functionality for creating Labber log files that can be opened by the Labber Log Browser and Log Viewer programs. This makes it possible to add custom data to the Labber database, such as simulation results or data acquired outside of the Labber Measurement program.

The following lines of Python code will create a log file with sinusoid signals with different frequencies in the Labber database.

import Labber
import numpy as np

# create step data
vTime = np.linspace(0,1,501)
vFreq = np.linspace(1,10,100)
# define step channels
lStep = [dict(name='Time', unit='s', values=vTime),
         dict(name='Frequency', unit='Hz', values=vFreq)]
# define log channels
lLog = [dict(name='Signal', unit='V', vector=False)]

# create log file
f = Labber.createLogFile_ForData('TestSinus', lLog, lStep)

# add log entries
for freq in vFreq:
    data = {'Signal': np.sin(2*np.pi*freq*vTime) }
    f.addEntry(data)

Note that log files created with the function createLogFile_ForData can only be used with the Log Browser and Log Viewer programs. It is not possible to open or run such a file in the Labber Measurement program.

3.3. Function definitions

Labber.createLogFile_ForData(name, log_channels, step_channels=[], use_database=True)

Create a log file for custom data storage in the Log database.

Parameters:
  • name (str) – Name or path of log file.
  • log_channels (list of dict) –

    List of dict describing the log channels. The list corresponds to the log channels in the Measurement dialog. The dictionary is defined by the following keys:

    name
    : str
    Name of channel.
    unit
    : str, optional
    Unit of channel.
    complex
    : bool, optional
    If True, the channel contains complex data. Default is False.
    vector
    : bool, optional
    If True, the channel contains vector data. Default is True.
  • step_channels (list of dict, optional) –

    List of dict describing the step channels. The list corresponds to the Step sequence in the Measurement dialog. If step_values is left undefined, the resulting log file will contain a collection of traces without a uniform pre-definied dimensionality. The dictionary is defined by the following keys:

    name
    : str
    Name of channel.
    values
    : 1D numpy array
    Step values for step channels. The length of the vector defines the dimensionality of the data in the resulting log file.
    unit
    : str, optional
    Unit of channel.
  • use_database (bool, optional) – If True, the log file is put in the central log database, otherwise the path set by the log name. Default is True.
Returns:

log – LogFile object representing the newly created log.

Return type:

LogFile object

Examples

Example 1: Create log without step values or fixed dimensions. Note that entries do not need to have the same length.

>>> import Labber
>>> lLog = [dict(name='x'), dict(name='y')]
>>> l = Labber.createLogFile_ForData('TestLog', lLog)

To add two entries to the log defined above:

>>> x = np.linspace(0,1,501)
>>> data = {'x': x, 'y': np.sin(2*np.pi*5*x) }
>>> l.addEntry(data)
>>> x = np.linspace(-1.2,1.2,201)
>>> data = {'x': x, 'y': x**2 }
>>> l.addEntry(data)

Example 2: Create log file using pre-defined step values. In this example, the data dimensions are defined by the step channels, and all entries need to have the same length as the first step channel. Note the the presence of vector=False for the Signal channel, which notifies that the entry size is defined by the first step channel.

>>> import Labber
>>> vTime = np.linspace(0,1,501)
>>> vFreq = np.linspace(1,10,10)
>>> chTime = dict(name='Time', unit='s', values=vTime)
>>> chFreq = dict(name='Frequency', unit='Hz', values=vFreq)
>>> chSig  = dict(name='Signal', unit='V', vector=False)
>>> f = Labber.createLogFile_ForData('TestData', [chSig], [chTime, chFreq])

To add data to the log defined above:

>>> for freq in vFreq:
>>>     data = {'Signal': np.sin(2*np.pi*freq*vTime)}
>>>     f.addEntry(data)

Example 3: Create log file using pre-defined step values, but allow individual entries to have different lengths. Compared to Example 2 above, the Time channel is defined as a log channel, and we need to provide values for Time for each entry.

>>> import Labber
>>> vFreq = np.linspace(1,10,10)
>>> chFreq = dict(name='Frequency', unit='Hz', values=vFreq)
>>> chTime = dict(name='Time', unit='s')
>>> chSig  = dict(name='Signal', unit='V')
>>> f = Labber.createLogFile_ForData('TestData', [chTime, chSig], [chFreq])

To add data to the log defined above:

>>> vTime = np.linspace(0,1,501)
>>> for freq in vFreq:
>>>     data = {'Time': vTime, 'Signal': np.sin(2*np.pi*freq*vTime)}
>>>     f.addEntry(data)

3.4. LogFile class

class Labber.LogFile(file_name, instrument_units=False)

Bases: object

The class handles reading and writing data to and from Labber log files.

Parameters:
  • file_name (str) – Labber hdf5 file with log data.
  • instrument_units (bool, optional) – If True, data from the log file is returned in instrument units instead of physical units. Default is False.
addEntry(data)

Add one entry to log file.

Parameters:data (dict) –

Dictionary with data. The keys should match the channel names, and the values should be 1D numpy arrays.

For scalar channels, the length of the array must match the size of the innermost step loop.

If the log contains channels with both scalar and vector data, the dict value for channels that contain vector data should be an iterable with numpy arrays or trace dicts.

getComment(log=-1)

Get comment from log file.

Parameters:log (int, optional) – Log number within the log file. Default is -1 (last log)
Returns:comment – String with comment
Return type:str
getData(name=None, entry=None, inner=None, log=-1)

Retrieve data from the log file and return it as a numpy array.

Parameters:
  • name (str, optional) – Name or index of the channel with data. If None, data for the first log channel will be returned.
  • entry (int or iterable, optional) – Entry number within log to retrieve. If None, all elements will be returned.
  • inner (int or iterable, optional) – Index of the inner-most loop values to retrieve. If None, all elements will be returned.
  • log (int, optional) – Log number within the log file. Default is -1 (last log)
Returns:

data – Depending on the input arguments, the output data will be a floating point number or a one- or two-dimensional numpy array.

Return type:

float or np.array

getEntry(entry=-1)

Retrieve an entry from the log file and return a dict with values.

Parameters:entry (int, optional) – Entry number to retrieve, as shown in the Log Viewer. Default is -1, which will get the last trace in the file.
Returns:d – Dictionary with entry data. Keys are the channel names, the values as numpy arrays.
Return type:dict
getFilePath(tags)

Get path of hdf5 log file.

Returns:path – Full path and name of hdf5 log file.
Return type:str
getLogChannels()

Get log channels in the log file.

Returns:log_channels – List of dicts representing log channels. The dictionaries contain the following keys:
name
: str
Name of channel.
unit
: str
Unit of channel.
complex
: bool
If True, the channel contains complex data.
vector
: bool
If True, the channel contains vector data.
Return type:list of dict

Examples

Get list of log channels from the log file TestLog.

>>> import Labber
>>> l = Labber.LogFile('TestLog')
>>> print(l.getLogChannels())
[{'name': 'Signal', 'unit': 'V', 'complex': False, 'vector': False}]
getNumberOfEntries(name=None, log=None)

Get number of entries in the log file for the given channel.

Parameters:
  • name (str, optional) – Name of channel for data count. Default is first log channel.
  • log (int, optional) – Log configuration number within the log file. Default is None, which will count all entries for all logs.
Returns:

n – Number of entries.

Return type:

int

getNumberOfLogs()

Get number of individual log configurations in the log file.

Returns:n – Number of log configurations.
Return type:int
getProject()

Get project name from log file.

Returns:project – String with project name.
Return type:str
getStepChannels()

Get step channels in the log file.

Returns:log_channels – List of dicts representing step channels. The dictionary contains the following keys:
name
: str
Name of channel.
unit
: str
Unit of channel.
values
: 1D numpy array
Step values for step channels.
complex
: bool
If True, the channel contains complex data. Always False for step channels.
vector
: bool
If True, the channel contains vector data. Always False for step channels.
Return type:list of dict

Examples

Get list of step channels from the log file TestLog

>>> import Labber
>>> l = Labber.LogFile('TestLog')
>>> print(l.getStepChannels())
[{'name': 'Time', 'unit': 's', 'complex': False, 'vector': False,
  'values': array([ 0.   ,  0.002,  ..., 0.998, 1.   ])},
 {'name': 'Frequency', 'unit': 'Hz', 'complex': False, 'vector': False,
  'values': array([ 1., 5., 10.])}]
getTags()

Get tag list from log file.

Returns:tags – List of strings with tags.
Return type:list of str
getTraceXY(y_channel=None, x_channel=None, entry=-1)

Retrieve a trace with (x,y) data from the log file .

Parameters:
  • y_channel (str or int, optional) – Name or log index of the channel with y-data. Default is first log channel.
  • x_channel (str or int, optional) – Name or step index of the channel with x-data. Default is first step channel.
  • entry (int, optional) – Entry number to retrieve, as shown in the Log Viewer. Default is -1, which will get the last trace in the file.
Returns:

(x,y) – A tuple with x and y data as 1-d numpy arrays.

Return type:

tuple

getUser()

Get user from log file.

Returns:name – String with user name.
Return type:str
setComment(comment, log=-1, set_all=True)

Set comment in log file.

Parameters:
  • comment (str) – String with comment.
  • log (int, optional) – Log number within the log file. Default is -1 (last log).
  • set_all (bool, optional) – Set comment of all log numbers within the log file. Default is True.
setProject(project)

Set project name in the log file.

Parameters:project (str) – String with project name.
setTags(tags)

Set list of tags in the log file.

Parameters:tags (list of str) – List of string with tags.
setUser(name)

Set user name in the log file.

Parameters:name (str) – String with user name.