MATLAB reference

Defines the names and levels of experimental conditions.

See also TrialConditions.generate

trialconds = generate(conditions, labels)
trialconds = generate(conditions, labels, Name, Value)

Define the names of experimental conditions (aka factors) and the possible labels within each condition. Conditions are determined from the absolute path of potential sources.

Input arguments

• conditions is a cell array of condition names (eg {'medication', 'dose'}) in the order they must appear in the file paths of trial sources
• labels is a struct with a field for each condition name (eg isfield(labels, 'medication')). Each condition field must have 'to' and 'from' fields which contain the final names and all the name possibilities, respectively. The 'from' field is optional if the terminology in the filenames is the desired terminology.

Name-value arguments

• 'Required' (defaults to all conditions): The conditions which every trial must have (in the case of some trials having optional/additional conditions).
• 'Separator' (defaults to '[_-]'): The character separating condition labels

Examples

labels.session(1).to = '\d';
labels.stim(1).to = 'stim';
labels.stim(2).to = 'placebo';
% or equivalently:
labels.session.to = '\d';
labels.stim = struct('to', { 'stim'; 'placebo' });

conds = TrialConditions.generate({'session';'stim'}, labels)

subset = DataSubset(name, source, pattern)
subset = DataSubset(name, source, pattern, ext)

Describes a subset of source data files found within a folder dir which match pattern.

Input arguments

• name: The name of the DataSubset that will be used in findtrials as the source name in a Trial.
• source: The Source type of all files described by this subset
• pattern: The pattern (using glob syntax) that defines where sources in this subset are stored on disk.

Examples

subsets = [
    DataSubset('events', @GaitEvents, '/path/to/events/Subject */*.csv')
]

See also Source, TrialConditions, Trial.findtrials

trial = Trial(subject, name, conditions, sources)

Characterizes a single instance of data collected from a specific subject. The Trial has a name, and may have on or more conditions which describe experimental conditions and/or subject specific charateristics which are relevant to subsequent analyses. A Trial may have one or more complementary sources of data (e.g. simultaneous recordings from separate equipment stored in separate files, supplementary data for a primary data source, etc).

Input arguments

• subject: The unique identifier (ID) char vector of the subject/participant in the trial
• name: The trial name (a char vector)
• conditions: A struct containing a field for every condition
• sources: A struct containing a field for every source

Examples

trial = Trial('1', 'baseline', struct('group', 'control', 'session', 2), struct())

trials = findtrials(subsets, conditions)
trials = findtrials(subsets, conditions, Name, Value)

Find all the trials matching conditions which can be found in subsets.

Input arguments

• subsets: The DataSubsets to use when finding sources
• conditions: The TrialConditions for these sources/trials

Name-Value arguments:

• 'SubjectFormat': The regex pattern used to match the trial's subject ID. (defaults to 'Subject (?<subject>\d+)'`).
• 'IgnoreFiles': A list of files to ignore that are in any of the subsets, given in the form of an absolute path.
• 'DefaultConditions': Default conditions to set when a given condition is not matched. Defaults can be given for required conditions. If a condition is not required, has no default, and is not matched, it will not be included as a condition for a source.
• 'Debug': Show files that did not match all the required conditions (default is false)
• 'Verbose': Also show files that did match all required conditions. Has no effect is 'Debug' is set to false.
• 'MaxLog': The maximum number of files per subset to show when 'Debug' is set to true

See also Trial, DataSubset, TrialConditions.generate

summarize(trials)
summarize(trials, Name, Value)

Summarize an array of trials

Name-Value arguments

• 'Verbosity': The maximum number of unique level combinations to show

results = analyzetrials(func, trials)
results = analyzetrials(func, trials, Name, Value)

Evaluate a function on each trial in an array of trials

If the function errors for a particular trial, an emtpy result will be returned for that trial, and a warning will be printed that includes the problematic trial and the error that was thrown. However, the rest of the trials in the array will continue to be analyzed with the given function.

Input arguments

• func: A handle to a function, e.g. @<function name>
• trials: An array of Trials, typically generated by findtrials

Name-Value arguments

• 'Parallel': Use multiple threads/processes to evaluate the function on multiple trials at once. Can result in a faster analysis, but requires the "Parallel Computing Toolbox"

See also Trial.findtrials

tbl = stack(segres)
tbl = stack(segres, Name, Value)

Stack an array of SegmentResults into a long form table

Name-Value arguments

• 'Conditions': The conditions to include in the table (default is all conditions present in any trials/segments). Used to remove "conditions" which are not experimental (i.e. needed for grouping/reducing in subsequent statistics)
• 'Variables': The variables to include in the table (default is all variables present in any trials/segments).

write_results(filename, tbl, conds)
write_results(filename, tbl, conds, Name, Value)

Write the results in tbl to file at filename, including only the conditions given by conds.

Input arguments

• filename: The path to write the results to
• tbl: The table containing results. Must already be in 'long' form (default from stack)
• conds: A cell array listing the subset of conditions which are to be included/written to file

Name-Value arguments

• 'Variables': A cell array listing the subset of variables to be written to file
• 'Format': Must be either 'wide' or 'long', defaults to 'wide'. Determines the shape of the written results. (Needs to be 'wide' for some common stats in SPSS, e.g. ANOVA.)
• 'Archive': A logical value controlling whether a file already existing at filename should be archived to [filename '.bak'] before writing the new results to filename.

See also SegmentResult.stack

src = Source(path)

A type representing a source of data in a particular file format

Input arguments

• path: The absolute path to the source file

Examples

src = Source('/path/to/source/file')

Creating custom sources

All subtypes of Source must:

• have a path field
• have at least these two constructors:
  • empty constructor
  • single argument constructor accepting a char vector of an absolute path

Source subtypes should:

• have a Source.readsource method

Source subtypes may implement these additional methods to improve user experience and/or enable additional funcitonality:

• Source.readsegment
• Source.generatesource (if enabling requiresource! generation)
• Source.dependencies (if defining a generatesource method)
• Source.srcext
• Source.srcname_default

data = readsource(src)

Read the source data from file.

requiresource(trial, src)
requiresource(trial, src, Name, Value)

Require a source to exist for a trial, attempt to generate the source if missing and possible to generate.

Name-Value arguments

• 'Name': The name to use if the src is missing and needs to be generated. Defaults to the srcname_default(src).
• 'Force': (Re)generate the src, even if it already exists.
• 'Dependencies': The sources that src depends on to be generated. Defaults to dependencies(src), which will be empty if the src class has not defined a dependencies method.
• Any remaining unmatched name-value arguments will be passed on to generatesource (if called).

Examples

requiresource(trial, GaitEvents(), 'Dependencies', {C3DSource()})

newsrc = generatesource(src, trial, deps)
newsrc = generatesource(src, trial, deps, Name, Value)

Generate a source src for trial using the dependent sources deps. Returns a source of the same class as src, but is not required to be exactly equal to src (i.e. a different src.path).

Input arguments

• src: A source that may or may not exist yet (e.g. if 'Force' was set to true in requiresource).
• trial: The trial that src/newsrc is being generated for/from.
• deps: The sources that src depends on to be generated (i.e. sources which contain data which is used to generate the data comprising newsrc)

Name-Value arguments

Any name-value arguments will be specific to a particular Source class subtype. N.B.: generatesource will normally be called by requiresource, which uses name-value arguments 'Name', 'Force', and 'Dependencies'. These names are functionally reserved (i.e. not available for use in generatesource methods), as they will not be passed on to generatesource by requiresource.

deps = dependencies(src)

Get the sources that src depends on to be generated with generatesource. By default sources are assumed not to be automatically generatable, therefore dependencies returns false unless a dependencies method has been created for a specific class subtyping Source.

ext = srcext(src)

Get the file extension for a source.

Input arguments

• src: Can be the class of a source subtype or an instance of a source. If src is a class, the default extension for that src < Source class will be returned; if src is an instance of a source, then the actual extension for that src will be returned, regardless of whether it matches the default extension for that class or not.

Examples

% assuming the existence of a class `GaitEvents` which subtypes `Source`
src = GaitEvents('/path/to/file.tsv')
ext = srcext(GaitEvents) % == '.csv'
ext = srcext(src) % == '.tsv'

Implementation notes

When defining a method for a custom class subtyping Source, the period should be included in the extension.

Example implementation

function ext = srcext(obj)
% Calling the default `srcext` method for `Source` will return the actual
% extension for `< Source` instances
    ext = srcext@Source(obj);

    if isempty(ext)
        ext = '.ext';
    end
end

name = srcname_default(src)

Get the default name for a source of a given < Source class

seg = Segment(trial, source)
seg = Segment(trial, source, Name, Value)

Describes a segment of time in a source for a trial, optionally with additional conditions specific to that segment of time. The conditions for the whole trial will be combined with any conditions specific to the segment (so that all conditions applicable to that segment of time will be available in one spot).

Input arguments

• source: Can be an instance of a Source class subtype, or the name of a source known/expected to be present in trial.

Name-Value arguments

• 'Start': The beginning time of the segment
• 'Finish': The ending time of the segment
• 'Conditions': A struct containing any additional conditions for that segment.

data = readsegment(seg)
data = readsegment(seg, Name, Value)

Read the segment of time from the source of seg. Name-value arguments (besides 'Start' and 'Finish', which are reserved) are passed on to the readsource method for the segment's src class.

segres = SegmentResult(seg)
segres = SegmentResult(seg, results)

Contains a segment and the results of an analysis.

Input arguments

• seg: A Segment
• results: (Optional) A struct where each field is an individual result. If omitted,

an empty struct will be created.