README.md

Alyx-MATLAB

This repository contains a MATLAB class called Alyx, that facilitates RESTful POST and GET requests to an instance of the Alyx database.

Getting started

These instructions are for installing the package and interating with the database from MATLAB. See deployment for notes on how to deploy the project on a live system.

Prerequisites

Alyx-MALTAB requires MATLAB 2016a or later. The code and instructions for installing the actual database can be found on the cortex-lab/Alyx repository.

MATLAB's built-in functions urlread and urlwrite are not particularly informative when the server returns an error. For debugging purposes, consider installing the latest release of the missing-http toolbox and using the http.jsonGet and http.jsonPost functions instead, as they return a status code ans the server's full response.

Installing

To install the package simply clone the master branch on your computer, then in MATLAB add the main folder to the paths, along with the helpers subfolder:

cd alyx-matlab
savepath(pwd, fullfile(pwd, helpers));

Once the paths are added you can read the help pages:

doc Alyx

Also, open the Alyx.m class definition file and change the BaseURL property to the URL of your Alyx database instance:

Running tests

Logging in/out

To instantiate an instance of Alyx, call the constructor like so:

ai = Alyx;

When called with no arguments, a login window is automatically displayed.
To instantiate the object without immediately logging in, call it with
the first two arguments empty. NB: The inputs are the Username and
Token.

ai = Alyx('','');

To log in use the login method. Upon success, this sets the Token
property with a token from Alyx. To determine whether you're logged in,
use the IsLoggedIn property. After logging in the object automatically
flushes any posts in the queue (more later). NB: Alyx is not a handle
class, so make sure you assign the output to itself.

Using endpoints to GET data

You can use the getData method to retrieve data directly from the
specified endpoint. For instance to retrieve session data:

sessions = ai.getData('sessions'); % NB: Don't run this line, it will be very slow!

The data are return as a struct. The second output argument is the
server status code. For a full list of status codes and their meanings:

doc matlab.net.http.StatusCode

To use any URL queries, just add them the endpoint string in the standard
URL format:

sessions = ai.getData('sessions?type=Base&subject=test');

For more info:

doc webread

The query options are set on the server side. You can find which options
are availible for each endpoint by vising the endpoint URL, but be warned
it is slow to load as you are running a GET within the browser. NB: Not
all endpoints have a GET options, again see the DJANGO API page
e.g.

The postData method uses the jsonPost method, which in turn uses the
built in MATLAB function webwrite. More info:

doc Alyx.jsonPost
doc webwrite

Debugging with http.jsonPost

Unfortunately, the MATLAB built in http interface functions are limited
in terms of debugging, as they don't directly return the server's
responses upon failure. Status codes must be extracted from the error
message bodies, and the full reponse of the server is usually not
returned. In order to debug your Alyx posts, you can use the missing
http package's jsonPost function instead. See line 47 of
Alyx.flushQueue:

opentoline(which('flushQueue'),47,1)

MySQL queries

One can also interact with Alyx through connection to the underlying
MySQL database. This currently isn't really supported by the alyx-matlab
package and isn't encouraged. More information: