Quickstart

The following is a very basic walkthrough of how PHZLAB is used. If you are new to PHZLAB, I would encourage you to follow along in the MATLAB command window with this section.

Loading data

Usually you will create an empty PHZ variable and manually add your data into it.

PHZ = phz_create('blank');
PHZ.srate = 1000;
PHZ.data = rand(30, 10 * PHZ.srate); % 30 trials by 10 seconds of random data
PHZ.units = 'V';

If you recorded these data using Biopac AcqKnowledge and saved the .acq file as a .mat file (using the 'Save as...' menu in AcqKnowledge), then you can specify a specific channel from that file to load. PHZLAB will automatically read the sampling rate, datatype, and units. You can override these values with parameter-value pairs:

PHZ = phz_create( ...
    'filename',     'my_biopac_data.mat', ...
    'filetype',     'acq', ...
    'channel',      1, ...
    'datatype',     'EMG', ...
    'units',        'V');

Change the units to millivolts. If these are Biopac data, you can use the special Biopac transform function to account for the hardware gain setting on the amplifier when converting the units:

% manual calculation and changing units
PHZ = phz_transform(PHZ, 1000);
PHZ.units = 'mV';

% using Biopac gain (hardware gain value on amplifier was 50)
PHZ = phzBiopac_transform(PHZ, 50, 'm');

Filter the data with a 10-500 Hz bandpass and a 60 Hz notch filter:

PHZ = phz_filter(PHZ, [10 500 60]);

Split a continuous data file into epochs and label them. This requires that you already have the start time for each epoch. You must also specify the window around each start time to extract. All epochs must be the same length. (Given the diversity of ways of recording epoch times, PHZLAB does not have a "catch all" way of extracting them, but it does have a couple of helper functions. See phzUtil_findAudioMarkers.m and phzBiopac_readJournalMarkers.m.)

% times is a vector of start times in samples
PHZ = phz_epoch(PHZ, times, [-1 5]);

% labels is a cell array of labels for each trial
PHZ = phz_labels(PHZ, labels);

Save this file to disk:

phz_save(PHZ, 'folder/for/phzfiles/datafile1.phz');

Processing

Subtract the mean of a baseline period from each epoch. You can manually enter a time range, or, if you've set the appropriate PHZ.region field, you can use that name instead:

% manually enter time region
PHZ = phz_blsub(PHZ, [-1 0]);

% use the PHZ.region baseline field
PHZ.region.baseline = [-1 0];
PHZ = phz_blsub(PHZ, 'baseline');

% if no region is given, the region called 'baseline' is used
PHZ = phz_blsub(PHZ);

Mark trials for rejection that contain values above a threshold.

PHZ = phz_reject(PHZ, 0.05);

Combining PHZ files

PHZLAB can combine all .phz files in a given folder into a single PHZ variable. This lets you apply processing functions to the whole dataset at once, and allows you to easily make plots that include all data.

PHZ = phz_combine('folder/for/phzfiles');

If there is too much data to put into a single file (usually the case with FFR data), PHZLAB will throw an error and suggest that you do some preprocessing (including averaging, e.g., by using phz_summary) before combining the files. This can be done from the call to phz_combine. You won't be able to change this processing later without re-combining the files with different settings:

PHZ = phz_combine('folder/for/phzfiles', ...
                  'blsub',    [-1 0], ...
                  'reject',   0.05, ...
                  'summary',  {'participant', 'group', 'trials'});

Plotting

Plot the average waveform of all trials:

phz_plot(PHZ)

Plot only the control group:

phz_plot(PHZ, 'subset', {'group', 'control'})

Plot only trials with a reaction time less than 10.

phz_plot(PHZ, 'subset', PHZ.resp.q1_rt < 10);

Plot a separate line for each group:

phz_plot(PHZ, 'summary', 'group')

Draw a different plot for each trial type, where each plot has a different line for each group:

phz_plot(PHZ, 'summary', {'group', 'trials'})

Draw a bar plot of the mean of each epoch instead of the time series data (includes standard error bars):

phz_plot(PHZ, ...
         'summary', {'group', 'trials'}, ...
         'feature', 'mean')

Take the mean from a specific time region:

% enter the region manually
phz_plot(PHZ, ...
         'summary', {'group', 'trials'}, ...
         'feature', 'mean', ...
         'region',  [0 4])

% use the region fields
PHZ.region.target = [0 4];
phz_plot(PHZ, ...
         'summary', {'group', 'trials'}, ...
         'feature', 'mean', ...
         'region',  'target')

See what it would look like with a different rejection threshold:

phz_plot(PHZ, ...
         'summary', {'group', 'trials'}, ...
         'feature', 'mean', ...
         'region',  [0 4], ...
         'reject',  0.1)

Exporting

Use the same input argument structure as your call to phz_plot to write those data to a csv file. Just add a filename argument.

phz_writetable(PHZ, ...
               'summary',  {'group', 'trials'}, ...
               'feature',  'mean', ...
               'region',   [0 4], ...
               'filename', 'mydata.csv')

Presets

Most of the above can be done using the presets feature, which allows for each switching between different analysis pipelines. See the presets tutorial for details.