A querying toolbox for mazes
MQL is a software toolbox for MATLAB for use in analysing position data from maze based spatial experiments. It allows the user to query position data to extract specific paths or trajectories. Timestamps from defined points along trajectories are returned allowing the calculation of timings and firing rates.
To select runs where the rat moves from the bottom left of the maze to the bottom right, we specify the intervals it has to cross and the intervals it should not cross
Why use it?
If you want to analyse behaviour or neural activity in specific sections or paths of a maze.
- Comparing different directions in a section of the maze (details in Tutorial)
- Analysing different paths through a maze
- Using results of multiple queries to compare similar parts of a maze i.e. all straight parts vs all turns
Data must be a single MATLAB .m file which when loaded contains a single MATLAB variable, an n by 3 vector. The 3 columns of the vector should be:
[timestamps, x coordinates of the rat at timestamp, y coordinate of the rat at timestamp]
Timestamps for trajectory intersection with each of a query lines. See Exporting section for more details.
Signal loss during recording resulted in some positional data points appearing erroneous. When signal is lost by the tracker the position coordinates recorded are usually set close to 0 resulting in points outside of the maze close to axes. In some cases signal loss also results in positional data set to invalid areas within the maze in the space above and below the central arm. MQL interpolates position data in these two cases, firstly by isolating data outside of a user defined square perimeter of the maze and interpolating it. Secondly to amend signal loss or error inside the perimeter of the maze a user defined distance parameter is used. MQL looks for changes in position in a single timestep which are greater than the distance parameter representing the furthest the rat would be expected to move.The distance interpolation works on the basis of two consecutive excessive movements, in order to ensure an invalid data point. During the interpolation process, the corrected values between the previous and next valid point are set using the assumption of straight movement with constant running speed between the two valid points. Validity MQL additionally classifies interpolated data into valid and invalid interpolations. An interpolated position is classified as valid if it satisfies two constraints. A user defined timeout parameter which represents the maximum length a sequence of interpolationed positions can have. Exceeding this constraint classifies the entire sequence as invalid, highlighting excessive signal loss. The second constraint is that post interpolation an interpolated point should not still exceed the user defined distance parameter.
Querying In order to analyse data from any given type of trial and from any section of the maze a system was developed that enabled the flexible selection of position data on the basis of user specified constraints. Queries created by MQL consist of a number of constraints and return the subset of position data that meets all of them. Each constraint is a horizontal or vertical line that intersects with part of the maze . Runs of consecutive position data in which all the lines are crossed in order are returned by the query. Additional “avoid” constraints can be added, they are query lines used to remove position data that intersect them leaving only desired trajectories.
Exporting Once the desired results have been obtained, the timestamps at which runs cross the query lines can be exported for analysis. During exporting the query lines, avoid lines and interpolation parameters are also stored (for details see Tutorial). Exported variables avoidquerycoords- vector containing 0..n set of coordinates of any avoid query lines used in format [xmin,xmax,ymin,ymax,xmin,xmax,ymax,ymax;...] (repeated x coordinates will occur for vertical lines, repeated y coordinates will occur for horizontal lines) interpolationparams- vector of 6 elements, the box parameters followed by timeout and distance thresholds respectively [box_x1, box_x2, box_y1, box_y2, timeout, distance] querycoords- vector containing 2...n set of coordinates for query lines used in the same format as avoidcoords [xmin,xmax,ymin,ymax,xmin,xmax,ymax,ymax;...] (repeated x coordinates will occur for vertical lines, repeated y coordinates will occur for horizontal lines) timestamps- vector n × m in size where n is the number of runs and m is the number of query lines, it contains the timestamps at which the query lines were crossed. validintersection- vector n × m in size, n is the number of runs and m the number of query lines. This vector contains a boolean value for each pair of points which cross a query line, it is true(1) when the data point is valid, as determined by the interpolation coordinates, i.e. if there was prolonged signal loss during the point at which the query line was crossed potentially making it not useful in analysis. This vector is included in case you wish to check the validity of the data.
Loading previous query and interpolation
Data saved in a .m file from the export function can be loaded back into MQL, this allows previous queries to be loaded and modified, it also loads the interpolation parameters allowing the same interpolation to be used for multiple queries in order to keep analysis consistent.
This tutorial will show you how to use MQL, interpolate your data, perform a basic query and export the results for analysis. In the case of this tutorial, the trials we are intially trying to find are where the rat runs from left to right in the central arm of the maze. Once these are found we will find trials run in the opposite direction in the same section of the maze. The queries built will allow the comparison of timing and firing during these two type of trial.
Open MATLAB, browse to the folder containing the MQL files. Type loadScreen in the MATLAB command window to run MQL.
Loading and interpolating data
Click load and browse to your data file.
Enter the coordinates of a box around the maze, click preview to check the box contains all of the maze. Enter timeout and distance measures, if you wish to disable these, enter a large number as both numbers signify the maximum timeout/distance permitted, therefore a high number such as 1000000 should render them ineffective.
If you are unsure of timeout/distance parameters but wish to use them, enter numbers and interpolate, you can see the effect of interpolation on the figure plotted and can amend the parameters if necessary before querying (note you must interpolate again for the new parameters to be in use)
In order to see the effects of the interpolation, the 'view interpolation' panel gives the option to turn off the visualisation of the 4 different types of data interpolation, allowing better viewing of the effects of a single parameter.