Overview

One central place to log data on the fly.

topsDataLog makes it easy to log data as you go. It's a "singleton" class, which means that only one can exist at a time, and you never have to create one yourself. You just call topsDataLog methods from any code that needs to use the log.

topsDataLog is a subclass of topsGroupedList, which means it has all the organization and capabilities of topsGroupedList, plus more.

Thus, you must log each piece of data in a "group" of related data. The group might correspond to a recuurring event, such as 'trial start'. You don't have to supply a "mnemonic" for each piece of data because topsDataLog uses timestamps to identify pieces of data in each group.

In your experiment code, you can add to the log as many times as you like. If you're not sure whether some piece of data will turn out to be important, you can go ahead and log it anyway. You don't have to worry about the log filling up, how to allcate space for more data, or even how the data are ultimately stored. That's the log's job.

Other topsFoundataion classes will also add data to the log, to help you keep track of details that aren't specific to your experiment. For example, topsRunnable objects make log entries as they start and finish running.

With your log entries and the entries made automatically by topsFoundataion classes, it should be straightforward to look at the log after an experiment and get a sense of what happened and when. The log's gui() method should make this even easier. You can use it to launch topsDataLogGUI, which plots a raster of all logged data over time, with data groups as rows.

Inheritance diagram for topsDataLog:

[legend]

Properties and Events
Property	printLogging = false
	any function that returns the current time as a number jig moved to topsFoundation clockFunction = @topsClock; More...

Property	fileWithPath = ''
	string name of a file to read from and write to, which may include the file path

Properties and Events inherited from topsFoundation
Property	name = ''
	a string name to indentify the object

Property	clockFunction =@topsClock
	clock function, to standardize

Protected Properties
Property	earliestTime
	the time of the first logged data, as reported by clockFunction

Property	latestTime
	the time of the last logged data, as reported by clockFunction

Property	lastFlushTime
	the most recent time when the log was flushed More...

Property	fHeader
	topsDataFile metadata struct for writing to disk incrementally

Property	lastWriteTime
	time of the most recent writeIncrementToFile()

Property	lastNewDataTime
	time of the most recent getNewData()

Protected Properties inherited from topsGroupedList
Property	groups = {}
	cell array of strings or numbers for all list groups

Property	length = 0
	number of items contained among all groups

Property	allGroupsMap
	containers.Map of data for each group

Methods
	set_fileWithPath (self, fileWithPath)
	Update the topsDataFile metadata to reflect a new fileWithPath.

Methods inherited from topsGroupedList
self	topsGroupedList (varargin)
	Constuct with name optional. More...

fig	gui (self)
	Open a GUI to view object details. More...

p	guiPanel (self, varargin)
	Make a topsGroupedListPanel with details about this object.

	addItemToGroupWithMnemonic (self, item, group, mnemonic)
	Add a new item to the list. More...

	removeItemFromGroup (self, item, group)
	Remove all instances of an item from a group. More...

	removeMnemonicFromGroup (self, mnemonic, group)
	Remove a mnemonic and its item from a group. More...

	removeGroup (self, group)
	Remove a whole group from the list. More...

	removeAllGroups (self)
	Remove a whole groups from the list. More...

	makeGroupFromList (self, groupName, list)
	Make a group from a cell array list of pairs: <string mnemonic>="">,

	mergeGroupsIntoGroup (self, sourceGroups, destinationGroup)
	Combine multiple groups into another group. More...

item	getItemFromGroupWithMnemonic (self, group, mnemonic)
	Get an item out of the list. More...

varargout	subsref (self, info)
	Get list items with {} syntax. More...

self	subsasgn (self, info, value)
	Add list items with {} syntax. More...

n	numel (self, varargin)
	Tell Matlab how many items to expect from {} syntax It's always 1.

mnemonics	getAllMnemonicsFromGroup (self, group)
	Get all mnemonics from a group. More...

items mnemonics	getAllItemsFromGroup (self, group)
	Get all items (and optionally all mnemonics) from a group. More...

groupStruct	getAllItemsFromGroupAsStruct (self, group)
	Get all items from a group, as a struct array. More...

isContained	containsGroup (self, group)
	Does the list contain the given group? More...

matches isMatch	getGroupNamesMatchingExpression (self, expression)
	Get string group names that match the given regular expression. More...

isContained	containsMnemonicInGroup (self, mnemonic, group)
	Does the list contain the given group and mnemonic? More...

isContained	containsItemInGroup (self, item, group)
	Does the list contain the given group and item? More...

Methods inherited from topsFoundation
self	topsFoundation (name)
	Constuct with name optional. More...

fig	gui (self)
	Open a GUI to view object details. More...

p	guiPanel (self, varargin)
	Make a topsDetailPanel with details about this object. More...

Protected Methods
	writeIncrementToFile (self)
	Write a data increment and other data to file and do accounting.

dataStruct	readIncrementFromFile (self)
	Read a data increment and other data from file.

dataStruct	readOldLogStructFromFile (self)
	Read an old-style data from file.

	populateWithDataStruct (self, dataStruct)
	Populate the log groupedList with struct data.

Static Methods
static log	theDataLog (clearTheLog)
	Access the current data log "singleton". More...

static fig	gui ()
	Open a GUI to view object details. More...

static	setVerbose (isVerbose)
	Toggle verbose printouts for data logging. More...

static	flushAllData ()
	Clear out all data from the log. More...

static	logDataInGroup (data, group, timestamp)
	Add some data to the log. More...

static logStruct	getSortedDataStruct (timeRange)
	Get all data from the log. More...

static logStruct	getNewData ()
	Get new data, recently added to the log. More...

static isNew	logNewData (logStruct)
	Log data from a data struct, if it's new. More...

static	writeDataFile (fileWithPath)
	Write logged data to a file. More...

static dataStruct	readDataFile (fileWithPath)
	Read previously logged data from a file. More...

static ecodes	parseEcodes (group, fileWithPath)
	Convenient routine to make a FIRA-like ecodes struct from a set of trial structures found in a data file NOTE: this only works if entries in the structures are scalars (includig nans)

static data	getTaggedData (group, fileWithPath)
	Convenient routine to collect tagged data into a cell array. More...

Static Methods inherited from topsGroupedList
static isContained	mapContainsItem (map, item)
	Does the containers.Map contain the given item? More...

static groupList	createGroupFromList (groupName, list)
	Convenient utility.

Static Methods inherited from topsFoundation
static c index	cellAdd (c, item, index)
	Add an item to a cell array. More...

static selector	cellContains (c, item)
	Does a cell array conatin an item? More...

static c	cellRemoveItem (c, item)
	Remove an item from a cell array. More...

static c	cellRemoveElement (c, index)
	Remove indexed elements from a cell array. More...

static index selector	findStructName (s, name)
	Where is the given name in the given struct array? More...

Private Methods
self	topsDataLog ()
	Constructor is private. More...

Constructor

◆ topsDataLog()

self topsDataLog ( )

private

Constructor is private.

Use topsDataLog.theDataLog to access the current instance of topsDataLog.

Methods

◆ theDataLog()

static log theDataLog ( clearTheLog )

static

Access the current data log "singleton".

Returns the current instance of topsDataLog. Use this method instad of a class constructor. This method will create a new data log the first time it's called, and return the same data log subsequently.

For most log operations, you don't need this method. You can just use the static methods below and they will access the current data log for you.

For a few operations it makes sense to get at the log itself, using this method. For example, you might wish to change the log's clockFunction, to use some custom timer. In that case you would get the log using this method, and set the value of log.clockFunction just like you would set the value of any object property.

◆ gui()

static fig gui ( )

static

Open a GUI to view object details.

Opens a new GUI with components suitable for viewing objects of this class. Returns a topsFigure object which contains the GUI.

◆ setVerbose()

static setVerbose ( isVerbose )

static

Toggle verbose printouts for data logging.

Parameters

isVerbose whether to print as data are logged

If isVerbose is true, topsDataLog will print a message to the Command Window whenever data is added to the log. If isVerbose is false or omitted, topsDataLog will print nothing.

◆ flushAllData()

static flushAllData ( )

static

Clear out all data from the log.

You can't create new instances of topsDataLog, but you can always clear out the existing instance. You probably should do this before starting an experiment.

Removes all data from all groups, then removes the groups themselves. Sets earliestTime and latestTime to nan.

◆ logDataInGroup()

static logDataInGroup	(	data	,
		group	,
		timestamp
	)

static

Add some data to the log.

Parameters

data	a value or object to store in the log (but not an object of the handle type).
group	a string for grouping related data, such as the name of a recurring event.
timestamp	optional time marker to use for data, instead of the current time.

If data is a handle object, converts it to a struct. This is because Matlab does a bad job of dealing with large numbers of handles to the same object, and a worse job of writing and reading them to disk. Better to keep the data log out of that mess.

Adds data to group, under the given timestamp, in the current instance of topsDataLog. If timestamp is omitted, uses the current time reported by clockFunction.

Updates earliestTime and latestTime to account for the the time of this log entry.

Since topsDataLog is a subclass of topsGroupedList, logging data is a lot like adding items to a list. group is treated just like the groups in topsGroupedList. The data log uses a timestamp as the mnemonic for each data item.

◆ getSortedDataStruct()

static logStruct getSortedDataStruct ( timeRange )

static

Get all data from the log.

Parameters

timeRange optional time limits for data, of the form [laterThan asLateAs]

Gets all data items from the current instance of topsDataLog, as a struct array, using getAllItemsFromGroupAsStruct(). Sorts the struct array by the time values stored in its mnemonics field.

◆ getNewData()

static logStruct getNewData ( )

static

Get new data, recently added to the log.

Gets recent data items from the current instance of topsDataLog, as a struct array. "Recent" means data added to the log since the last time getNewData() was called. Updates lastNewDataTime with the current time.

◆ logNewData()

static isNew logNewData ( logStruct )

static

Log data from a data struct, if it's new.

Parameters

dataStruct struct data, as from getSortedDataStruct()

Adds adds data from the given dataStruct to the data log, but only if the new data are newer than lastNewDataTime. Returns a logical selector with the same size as dataStruct, which is true where items were found to be new and added to the log.

◆ writeDataFile()

static writeDataFile ( fileWithPath )

static

Write logged data to a file.

Parameters

fileWithPath optional .mat filename, which may include a path, in which to save logged data.

Converts recently logged data to a standard Matlab struct using topsDataLog.getSortedDataStruct() and writes the struct to disk, via the topsDataFile class.

writeDataFile() behaves differently depending on fileWithPath and the fileWithPath property of the current topsDataLog instance:

If fileWithPath is provided, assigns fileWithPath to the fileWithPath property of the current topsDataLog instance and writes data to the given fileWithPath.
If fileWithPath is omitted, but the current topsDataLog instance has a non-empty fileWithPath property, writes data according to the fileWithPath property.
If fileWithPath is omitted, and the current topsDataLog instance has an empty fileWithPath property, opens a dialog for chosing a a file. If a file is chosen, writes data to the chosen file and saves the chosen file to the fileWithPath property.

◆ readDataFile()

static dataStruct readDataFile ( fileWithPath )

static

Read previously logged data from a file.

Parameters

fileWithPath optional .mat filename, which may include a path, from which to read logged data.

Reads any previously unread data from disk, via the topsDataFile class. Populates the current instance of topsDataLog with any new data. May also return the new data, in a struct of the same form as topsDataLog.getSortedDataStruct().

readDataFile() behaves differently depending on fileWithPath and the fileWithPath property of the current topsDataLog instance:

If fileWithPath is provided, assigns fileWithPath to the fileWithPath property of the current topsDataLog instance and reads data from the given fileWithPath.
If fileWithPath is omitted, but the current topsDataLog instance has a non-empty fileWithPath property, reads data according to the fileWithPath property.
If fileWithPath is omitted, and the current topsDataLog instance has an empty fileWithPath property, opens a dialog for chosing a a file. If a file is chosen, reads data from the chosen file and saves the chosen file to the fileWithPath property.

◆ getTaggedData()

static data getTaggedData	(	group	,
		fileWithPath
	)

static

Convenient routine to collect tagged data into a cell array.

group is string name fileWithPath is optional filename

Properties and Events

◆ printLogging

Property printLogging = false

any function that returns the current time as a number jig moved to topsFoundation clockFunction = @topsClock;

true or false, whether to print info as data are logged

◆ lastFlushTime

Property lastFlushTime

protected

the most recent time when the log was flushed

flushAllData() sets lastFlushTime to the current time, as reported by clockFunction.

The documentation for this class was generated from the following file:

topsDataLog.m

Overview

Properties and Events

Protected Properties

Methods

Protected Methods

Static Methods

Private Methods

Constructor

◆ topsDataLog()

Methods

◆ theDataLog()

◆ gui()

◆ setVerbose()

◆ flushAllData()

◆ logDataInGroup()

◆ getSortedDataStruct()

◆ getNewData()

◆ logNewData()

◆ writeDataFile()

◆ readDataFile()

◆ getTaggedData()

Properties and Events

◆ printLogging

◆ lastFlushTime