# Sanjay's MATLAB library functions

The whole library can be downloaded (0.15 MB) as a zip, or is available on GitHub / OSF. Unzip this and add 'matlib' to your MATLAB path. The individual functions are specified below.

## 2-dimensional data visualisation

Useful for looking at data consisting of paired measurements.

This is designed to do a between-subjects comparison of one variable conditioned on another -- when two variables are measured per trial. For example, if you supply the RT and accuracy for each trial, it will generate a conditional accuracy plot. Can handle multiple conditions and multiple subjects.

This plots the mean Y value in each quantile bin of X. The error bar is the standard deviation of the Y values in each bin.

Use this to plot the quantile levels of a Y variable, when datapoints are binned according to the quantile of another X variable.

Plot a mesh of quantile levels of two variables, X and Y, when both variables are binned according to quantiles. The deviation of the lines from a rectangular grid thus indicates deviations from independence.

Shortcut function that works like scatter, then also does a linear regression and plots the fit line.

This functions like scatter, but plots a heatmap of the density of points.

## Basic matrix functions

Some of these functions really ought to be included in Matlab! My implementations are not fast, but they are terser than writing loops etc.

This allows you to concatenate any arrays - even if they are of different sizes. The syntax is the same as the normal "cat". Any items that are smaller are padded with nans on all the relevant dimensions

Does what a pivot-table does in excel. Converts data in "long form" to an n-dimensional table. The last column is treated as values, the earlier columns as categories.

Undoes what "pivot" did. Converts an n-dimensional table into long-form, with a "condition" column for each dimension of the input.

Performs an N-dimensional anova, given an N-dimensional matrix. Simply supply the matrix, where there is one measurement per cell. All the other parameters are the same as for anovan - so to perform repeated measures, use "random" on one of your matrix dimensions.

Group an n-dimensional array according to conditions specified in a identical-sized array. The conditions are categorical, and are used to divide the data into groups. Then the mean is taken for each group, along the specified dimension.

Takes a matrix that has nan-padding, and "right-aligns" the values by removing trailing nans from each row. For example, if subjects (rows) have different numbers of trials (columns), you might have "nan"s in the last columns for some subjects. This function would allow you to look at the last trial, penultimate trial etc.

Performs assignments like MATRIX(4,:)=VECTOR, but it avoids "dimensional agreement". Like "nancat", it pads missing regions with "nan". For example, if you are creating a matrix of subject x trial, you can use this to assign data from each subject.

Remove sequential repeated values in a vector.

Segments a vector by giving the starts and stops of sequences of repeated values.

Allows you to index into a matrix, using a different column from each row. The vector of indices has the same size as the columnheight of the matrix, and each element corresponds to a row. The number indicates which column to extract.

Smoothing that works along one dimension of an n-dim array. It is similar to using conv2 with a 1-dimensional filter

retrieves the first element of an array. Equivalent to X(1). Useful when chaining commands - allows you to extract the first value without storing the whole array anywhere. Was very useful before the find function allowed a count parameter.

Flattens a matrix into a vector. Equivalent to X(:), but usefult when chaining commands.

Z-score that leaves nan as nan, ignoring those values when calculating the mean and standard deviation. this is useful for imputation, allowing "nan" to be replaced by "0" in some cases.

Wrapped the original "linspace" to allow vector endpoints, and thus generate linearly spaced vector outputs.

Converts nans to zeros, as though you had done "X(isnan(X))=0;". This is useful for removing nans within chained functions.

Converts 1s to nans, leaves 0s as 0s, as though you had done "X(X>0)=nan;". Useful for masking out unwanted values in a large matrix, e.g. RT+bool2nan(RT<0) removes negative RTs.

Works out what permutation order you need, to get from one sequence to another. For example, the inverse permutation to get [1 2 3 4 5] from [1 5 2 3 4] is [1 3 4 5 2].

## Structure operations

Returns a structure containing all the variables and values from the current workspace - just as though you had performed "save;X=load".

Dumps fields from the given structure into the current workspace.

Takes an array of structures, and puts the index of the structure inside onto the individual fields. In other words, it is like using catStruct to concatenate all the structures in the array, so that the fields have extra dimensions. Only works when the fields are numerical arrays.

In a structure whose fields are all arrays of the same length, (corresponding to trials for instance,) this allows a single element (trial) to be removed from each field.

Allows concatenation of structures which have the same fields, by individually concatenating each of their individual fields. Only works when the fields are arrays.

This creates an altered version of a structure to try and make it assignment-compatible with another structure - i.e. it creates fields that are missing. Both structures may need to be altered to make them compatible. This may be necessary if you want to concatenate two structures using [] or cat.

## Simple graphical functions

Functions for simple data visualisation

The commonest task is to plot the means and standard errors of a set of data. This function takes means over dimension 1, plots dimension 2 as the x-axis, and dimension 3 as different lines. It uses either "errorbar", or else the "area" parameter can draw a shaded error region.

Takes a matrix of data, with subjects as rows (as for errorBarPlot), and performs pairwise comparisons across columns. A matrix is returned, or "plot_p" draws horizontal "comparison lines" and p-values over a previously drawn plot.

Calls plot, but accepts n-dimensional arrays. Can draw extra dimensions as different line colours, line-styles, or subplots, allowing 5 dimensions to be visualised. Can propagate the submatrices to any graph function, like "surf", errorBarPlot" or "imagesc"

Performs all pairwise correlations across fields in an structure-array

Fast simple fit and plot a sigmoid to data of various kinds.

Continuous histogram, like "hist". Uses sliding-window method to show frequency in each window, and is thus equivalent to a box-smoothed histogram. Operates on n-dimensional arrays, counting along the first dimension. Can return counts and do plot.

Use with the usual subplot syntax, except an array in place of the plot number. It goes through each of those plots, and ensures the scales are equal.

For the current plot, make the X and Y axes the same.

This generates a colour from the current gradient. If you want to have 7 colours from the spectrum, the third one is colourMap(3,7). Calling colourMap with a Nx3 matrix (or an existing colourmap) will set the current axis default colour order. Handy for colouring a sequence of lines on the same axis.

## Reaction time functions

Plot a reciprocal probit plot of reaction times. Under this plot, a recinormal distribution appears as a straight line. This can separate trials by condition, and can plot the probit relative to the whole dataset, or relative to the individual conditions. Returns an intercept and slope of the fit line.

Calculates an empirical hazard function. Works a bit like ecdf, but calculates the conditional probability of an event given it has not already happened.

Plots a delta-plot of vincentised data. It takes the quantiles of the two reaction time distributions, and compares the values of the corresponding quantiles. It allows comparison of the shapes of two distributions.

This Monte-Carlo simulates an N-horse race between ballistic processes. It is optimised for fast sampling. It allows an arbitrary logic of start/stop/control when each process terminates, and can be used to predict multiple sequential responses and error-corrections.

This is a companion to generalRaceModel, and fits the a race model to a given dataset. Data is given as an RT matrix for each response-type, over a number of trials, and the model is run multiple times to obtain likelihoods of the parameters. Supported fitting algorithms include simulated annealing and genetic algorithm (with the appropriate matlab toolboxes). Experimental feature: can also be used to fit joint distributions of RT1 and RT2 when two responses occur in the same trial.

## Eye movement analysis functions

These functions are designed for use with the Eyelink 1000 and the associated API. You will need a copy of edf2asc.exe supplied with the Eyelink to use the batch-conversion functions - ensure that the exe is 'on your path' - e.g. in the c:\windows\system folder.

Convert the named edf file into a matlab structure. The structure will contain eye position, saccades and fixations as parsed by the Eyelink online parser, and any events sent to the eye tracker during the experiment. It uses an intermediate ASC file, and if the ASC already exists, it does not need the edf2asc program.

Runs the edf2asc tool on each file in a directory, creating the ASC files.

Reads multiple EDF files from a single experiment, into a matlab structure. Designed for use with Sanjays experiment framework.

A multi-purpose tool for epoching and analysing saccades and pupil data. Handles rotation/reflection/translation, saccade-related snipping, event-related snipping, baseline correction, blink removal +/- interpolation and more.

This browses through each trial, displaying the both a screen-based plot and a time-based plot of the eye. Trial events and trial locations can be displayed from a parameter file, e.g. directly from Sanjays experiment framework.

## Sanjay's Experiment Framework

These functions should provide a robust framework for developing experiments under PsychToolbox. The library does screen creation, eyelink initialisation, error handling, and runs a sequence of trials which can be automatically generated using a factorial design, with counterbalancing over the experiment.

Actually runs the experiment.

Create factorial design from the trial variables and block variables.

Creates the screen window, loads image resources, and loads sound resources, into the experiment array.

Logs events in the experiment. Will ensure they are logged on eyelink also, if connected.

Does what it says.