<< 2012-3 >>
Department of
Computer Science
 
MQL Logo
Maze Query Language

A querying toolbox for mazes



  • Download current version of MQL toolbox V1.9 multiplatform - updated 10/09/2010

    • Overview
    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.
    diagram 1
    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.
    For example:

    - 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 format
    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]


    Data format

    Output
    Timestamps for trajectory intersection with each of a query lines. See Exporting section for more details.

    Functionality
    Interpolation
    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.


    Tutorial

    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.

    Running MQL
    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.

    interpolation

    For example if we want to look only at the effect of the timeout we can switch off all other options and re-plot the figure.
    View interpolation

    Once happy with the interpolation parameters click 'Query interpolated data' to launch the query screen.

    Querying
    You should see the interpolated data displayed.

    Pick a horizontal section of the maze to analyse and click the 'Vertical' radio button. In the x coords field enter the x coordinate somewhere along the section of the maze, in y coord fields enter coordinates below and above the section of the maze. Click preview to see the query line.

    preview query
    Adjust the parameters until they are satisfactory and then click 'Create' to add the query to the query list.

    create query
    Next either create another vertical query line from scratch, with the same y coords but with greater x coords, or double click Query 1 from the query list, increase the x coordinate by the desired amount and click create. This creates a new query line more quickly.

    Double click Query 01 in the Query List to edit coordinates
    update

    To create the second query line increase the x coordinate
    update query 2

    Click "Preview" to see the new line, when happy click "Create" to see it appear in the Query List as Query 02. Query lines highlighted in the query list are shown in black, other query lines are shown in green.
    create second line

    Once you have two query lines you can run the query, click the 'Run query' button. If you have position data outside of your desired section, amend your query lines to make them shorter or longer, additionally you can add avoid lines.

    Once the query is run, trajectories returned are shown in blue.
    Query results

    Avoid Lines
    Either create avoid line the same way as the query lines, but tick 'Do not intersect', you can also use the preview button to check the line is correct before creating. It can be quicker to use an existing query, for example you can edit the first query line to get the y coordinates [figure A], reduce the x coordinate, tick avoid and preview [figure B] and create the avoid line [figure C]

    Figure A -     Double click Query 01
    Click Query 01
    Figure B - Update x coord and click preview
    Update x coord and click preview
    Figure C - Click create to see the query in the Avoid List. Avoid lines highlighted in the avoid list are shown in blue, other avoid lines are shown in red.
    Click create to see the query in the Avoid List

    Exporting
    Once all the trajectories shown are satisfactory, type a filename in the export field and click Export results to create a .mat file of your results.
    Export runs
    Results file when loaded into MATLAB
    Results loaded in MATLAB

    The previous query returns runs from left to right. To return runs in the opposite direction update each of the query lines in turn such that the order is reversed; double click the first query, change the x coordinate and click update, repeat this for the second. Note t    he highlighted query line is black, highlighted avoid lines are blue.

    Image below shows the highlighted black line Query 01 (the line crossed first) is now to the right, giving runs from right to left
    Query lines swapped

    Run the query and export the results to a new MATLAB file.

    Export second set of results

    load these .m files into MATLAB and you now have the timestamps for each of the runs.

    The following MATLAB code (democode.m file included with MQL) allows the calculation of mean running times:

    Code to calc timings

    The firing rate can be calculated by writing code to count the number of spikes between the two timestamps of the runs and then dividing by the time taken for the run.

    If there is anything missing from this help or tutorial or you have any questions please feel free to contact me
    email me if you like
    Contact Us  |  News 25th Anniversary
    © 1995-2013 University of Bristol  |  Terms and Conditions  |  Use of Cookies
    About this Page