Detailed Description

connection to an Alyx database

This class provides methods to connect to an Alyx database, login/logout, upload data, and other management tasks. It is based on the Alyx REST API and code modified from IBL.

Inheritance diagram for alyxManager:

Public Member Functions
function	alyxManager (in varargin)
	Class constructor.

function	hasSecrets (in me)

function	setSecrets (in me, in password, in AWS_ID, in AWS_KEY, in force)
	check secrets for the AlyxManager instance

function	logout (in me)
	Set secrets for the AlyxManager instance.

function	login (in me)
	Logs out the current user from the AlyxManager instance.

function	hasEntry (in me, in type, in name)
	Log in the current user from the AlyxManager instance.

function	getData (in me, in endpoint, in varargin)
	Checks if an item exists in the Alyx database.

function	postData (in me, in endpoint, in data, in requestMethod)

function	getSessions (in me, in ref, in varargin)
	Post any new data to an Alyx/REST endpoint.

function	processValue (in name)
	Return sessions and eids for a given search query.

function	listSubjects (in me, in stock, in alive, in sortByUser)

function	updateNarrative (in me, in comments, in endpoint, in subject)
	Lists recorded subjects.

function	createSession (in me, in path, in sessionID, in session, in jsonData, in startTime)
	Update an Alyx session or subject narrative.

function	closeSession (in me, in narrative, in QC, in nTrials, in nTrialsCorrect, in jsonData)
	Create a new unique experimental session in the database.

function	registerALF (in me, in alfDir, in sessionURL)
	Close an Alyx session.

function	validateFcn (in fileObj)
	Register files contained within alfDir to Alyx.

function	expFilePath (in me, in varargin)

function	registerFile (in me, in rFiles)
	Full path for file pertaining to designated experiment.

function	registerALFFiles (in me, in paths, in session)

function	initDatabase (in me)

function get	loggedIn (in me)

function set	queueDir (in me, in qDir)

function set	baseURL (in me, in value)

function set	user (in me, in value)

function	getSecrets (in me)

function	secretUI (in me, in field)

Public Member Functions inherited from optickaCore
function	optickaCore (in varargin)
	Class constructor.

function get	fullName (in me)

function	getALF (in me, in subject, in lab, in create)
	get the ALF path

function	makeReport (in me, in rpt)
	Generate a detailed report for the opticka object.

function	findAttributes (in me, in attrName, in attrValue)

function	findAttributesandType (in me, in attrName, in attrValue, in type)
	find properties of object with specific attributes, for example all properties whose GetAcccess attribute is public and type is logical.

function	findPropertyDefault (in me, in propName)
	Return the declared default value for a class property.

function	clone (in me)
	Use this syntax to make a deep copy of the object, i.e. OBJ_OUT has the same field values, but will not behave as a handle-copy of me anymore.

function	checkSuperclasses (in List)

function	editProperties (in me, in properties)
	method to modify a set of properties

function	setProp (in me, in property, in value)
	method to fast change a particular value. This is useful for use in anonymous functions, like in the state machine.

function	initialiseSaveFile (in me, in varargin)
	just get date fragment for backwards compatibility

function	checkPaths (in me)
	checks the paths are valid

Static Public Member Functions
static function	ensureCell (in a)

static function	cellflat (in c)

static function	rmEmpty (in A)

static function	mapToCell (in f, in varargin)

static function	catStructs (in cellOfStructs, in missingValue)

static function	valueTable (in s)
	Concatenates different structures into one structure array.

static function	pick (in from, in key, in varargin)

static function	isAProp (in v, in name)

static function	namedArg (in args, in name)

static function	url2eid (in url)

static function	parseAlyxInstance (in varargin)

static function	iff (in cond, in evalTrue, in evalFalse)
	Converts input to string for UDP message and back.

Static Public Member Functions inherited from optickaCore
static function	initialiseGlobals (in doReset, in doOpen)

static function	makeArgs (in args)
	Converts cell args to structure array.

static function	addDefaults (in args, in defs)
	regularises and adds default options to arg input

static function	hasKey (in in, in key)
	check if a struct / object has a propery / field

static function	getKeys (in device)
	PTB Get key presses, stops key bouncing.

Public Attributes
Property	baseURL
	the URL of the ALYX database

Property	user
	the user to login

Property	lab
	the lab defined in the Alyx database

Property	subject
	the experimental subject

Property	queueDir
	where to save the temporary json files sent via REST

Property	sessionURL
	if we open a new session this is the main URL

Property	sessionParentURL
	if we open a new session as a child, this is the base session URL

Property	pageLimit
	limit how many values returned

Property	verbose
	more logging for debugging

Property	webOptions

Property	loggedIn

Public Attributes inherited from optickaCore
Property	name
	object name

Property	comment
	comment

Property	verbose
	verbose logging, subclasses must assign this. This is normally logical true/false

Property	optickaVersion
	version number

Property	dateStamp
	clock() dateStamp set on construction

Property	uuid
	universal ID

Property	paths
	storage of various paths

Property	fullName
	The fullName is the object name combined with its uuid and class name.

Protected Member Functions
function	getToken (in me, in username, in password)

function	makeEndpoint (in me, in endpoint)

function	jsonPost (in me, in endpoint, in jsonData, in requestMethod)

function	flushQueue (in me, in dontSend)
	Makes POST, PUT and PATCH requests with JSON body.

function	delete (in me)

Protected Member Functions inherited from optickaCore
function	parseArgs (in me, in args, in allowedProperties)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.

function	addArgs (in me, in args)

function	setPaths (in me)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.

function	getFonts (in me)
	set paths for object

function	toStructure (in me)
	Converts properties to a structure.

function	getType (in me, in in)

function	logOutput (in me, in in, in message, in override)
	Give a metaproperty return the likely property class.

function	salutation (in me, in varargin)
	Prints messages dependent on verbosity.

Protected Attributes
Property	token

Property	cache

Protected Attributes inherited from optickaCore
Property	cloning
	are we cloning this from another object

Property	mversion
	Matlab version number, this is transient so it is not saved.

Property	sansFont
	sans font

Property	monoFont
	monoFont

Property	className
	class name

Property	savePrefix
	save prefix generated from clock time

Property	fullName_
	cached full name

Constructor & Destructor Documentation

◆ alyxManager()

function alyxManager::alyxManager ( in varargin )

Class constructor.

Parameters

varargin are passed as a structure / cell of properties which is parsed.

Returns: instance of class.

Member Function Documentation

◆ baseURL()

function set alyxManager::baseURL	(	in	me,
		in	value
	)

◆ catStructs()

static function alyxManager::catStructs	(	in	cellOfStructs,
		in	missingValue
	)

static

◆ cellflat()

static function alyxManager::cellflat ( in c )

static

◆ closeSession()

function alyxManager::closeSession	(	in	me,
		in	narrative,
		in	QC,
		in	nTrials,
		in	nTrialsCorrect,
		in	jsonData
	)

Create a new unique experimental session in the database.

Creates a new experiment session in Alyx with the structure: subject/ |_ YYYY-MM-DD/ |_ sessionID/

Parameters

path	char ALF path for the session
sessionID	integer experiment sequence number
session	struct with labName, subjectName, researcherName, location
jsonData	char JSON string (default '[]')
startTime	datetime optional override for start_time

Returns: url char URL of created session; newSession struct created session record

Example: [url, session] = createSession(me, '/path/to/alf', 1, sessionStruct)

See also: ALYX

◆ createSession()

function alyxManager::createSession	(	in	me,
		in	path,
		in	sessionID,
		in	session,
		in	jsonData,
		in	startTime
	)

Update an Alyx session or subject narrative.

Update an Alyx narrative field with comments. If an endpoint is specified, the narrative for that record is updated, otherwise the last subsession URL is used. If the SessionURL property is empty and no endpoint is specified, the narrative field of the subject's Alyx record is updated.

Parameters

comments	char[] comments to add to narrative
endpoint	char[] endpoint URL (optional, uses sessionURL)
subject	char[] subject name (optional)

Returns: narrative the updated narrative string

Examples: NARRATIVE = UPDATENARRATIVE(OBJ) NARRATIVE = UPDATENARRATIVE(OBJ, COMMENTS) NARRATIVE = UPDATENARRATIVE(OBJ, COMMENTS, ENDPOINT) NARRATIVE = UPDATENARRATIVE(OBJ, COMMENTS, ENDPOINT, SUBJECT)

See also: ALYX, DAT.UPDATELOGENTRY, EUI.EXPPANEL/SAVELOGENTRY, PUTDATA

◆ delete()

function alyxManager::delete ( in me )

protected

◆ ensureCell()

static function alyxManager::ensureCell ( in a )

static

◆ expFilePath()

function alyxManager::expFilePath	(	in	me,
		in	varargin
	)

◆ flushQueue()

function alyxManager::flushQueue	(	in	me,
		in	dontSend
	)

protected

Makes POST, PUT and PATCH requests with JSON body.

Makes a POST request, with a JSON request body, asking for a JSON response.

Parameters

endpoint	char REST API endpoint to make the request to
jsonData	char JSON string to use as request body
requestMethod	char HTTP method: 'post'(default),'put','patch','delete'

Returns: statusCode integer HTTP response code; responseBody char[] response body or data struct

See also: JSONGET, JSONPUT, JSONPATCH

◆ getData()

function alyxManager::getData	(	in	me,
		in	endpoint,
		in	varargin
	)

Checks if an item exists in the Alyx database.

This method verifies the existence of a specified entry in the Alyx database based on the type and name provided. It returns true if the entry exists, and false otherwise.

Parameters

type	(char) The type of entry to check (e.g., 'users', 'subjects').
name	(char) The name of the entry to check for existence.

Returns: r (logical) Returns true if the entry exists, false otherwise.

◆ getSecrets()

function alyxManager::getSecrets ( in me )

◆ getSessions()

function alyxManager::getSessions	(	in	me,
		in	ref,
		in	varargin
	)

Post any new data to an Alyx/REST endpoint.

Makes a request to an Alyx endpoint with new data as a MATLAB struct; returns the JSON response data as a MATLAB struct. This function will create a new record by default, if requestMethod is undefined. Other methods include 'PUT', 'PATCH' and 'DELETE'.

Parameters

endpoint	char for REST endpoint
data	struct to encode as JSON and send
requestMethod	char default 'post', can be 'put','patch','delete'

Returns: data the JSON response as MATLAB struct; statusCode integer HTTP status code

Example: subjects = me.postData('subjects', myStructData, 'post')

See also: ALYX, JSONPOST, FLUSHQUEUE, REGISTERFILE, GETDATA

◆ getToken()

function alyxManager::getToken	(	in	me,
		in	username,
		in	password
	)

protected

◆ hasEntry()

function alyxManager::hasEntry	(	in	me,
		in	type,
		in	name
	)

Log in the current user from the AlyxManager instance.

◆ hasSecrets()

function alyxManager::hasSecrets ( in me )

◆ iff()

static function alyxManager::iff	(	in	cond,
		in	evalTrue,
		in	evalFalse
	)

static

Converts input to string for UDP message and back.

Parameters

varargin can be (ref, AlyxInstance) or (UDP_string)

Returns: ref either JSON string or expRef depending on call mode; AlyxInstance either empty or Alyx object depending on call mode

See also: SAVEOBJ, LOADOBJ

◆ initDatabase()

function alyxManager::initDatabase ( in me )

◆ isAProp()

static function alyxManager::isAProp	(	in	v,
		in	name
	)

static

◆ jsonPost()

function alyxManager::jsonPost	(	in	me,
		in	endpoint,
		in	jsonData,
		in	requestMethod
	)

protected

◆ listSubjects()

function alyxManager::listSubjects	(	in	me,
		in	stock,
		in	alive,
		in	sortByUser
	)

◆ loggedIn()

function get alyxManager::loggedIn ( in me )

◆ login()

function alyxManager::login ( in me )

Logs out the current user from the AlyxManager instance.

This method clears the session token and any associated session information, effectively logging the user out of the Alyx system. It also provides feedback to the user indicating the logout status.

◆ logout()

function alyxManager::logout ( in me )

Set secrets for the AlyxManager instance.

This method allows the user to set the password, AWS ID, and AWS key for the AlyxManager instance. If any of these values are not provided, the method attempts to retrieve them from a secure storage.

Parameters

password	(char) The password for the Alyx database. If not provided, it will be retrieved from secure storage.
AWS_ID	(char) The AWS ID for accessing AWS services. If not provided, it will be retrieved from secure storage.
AWS_KEY	(char) The AWS key for accessing AWS services. If not provided, it will be retrieved from secure storage.
force	(logical) If true, prompts the user to set the secrets even if no secrets are stored or provided. In this case it will use a GUI requestor to get secrets and store them

◆ makeEndpoint()

function alyxManager::makeEndpoint	(	in	me,
		in	endpoint
	)

protected

◆ mapToCell()

static function alyxManager::mapToCell	(	in	f,
		in	varargin
	)

static

◆ namedArg()

static function alyxManager::namedArg	(	in	args,
		in	name
	)

static

◆ parseAlyxInstance()

static function alyxManager::parseAlyxInstance ( in varargin )

static

◆ pick()

static function alyxManager::pick	(	in	from,
		in	key,
		in	varargin
	)

static

◆ postData()

function alyxManager::postData	(	in	me,
		in	endpoint,
		in	data,
		in	requestMethod
	)

◆ processValue()

function alyxManager::processValue ( in name )

Return sessions and eids for a given search query.

Returns Alyx records for specific refs (eid and/or expRef strings) and/or those matching search queries. Values may be char arrays, strings, or cell strings. If searching dates, values may also be a datenum or array thereof.

Parameters

ref	char[] or cellstr of experiment reference strings
varargin	can include 'subject', 'users', 'lab', 'date_range', 'dataset_types', 'number' as name-value pairs

Returns: sessions cell array of session records; eids cell array of session UUIDs

Examples: sessions = ai.getSessions('cf264653-2deb-44cb-aa84-89b82507028a') sessions = ai.getSessions('2018-07-13_1_flowers') sessions = ai.getSessions('cf264653-2deb-44cb-aa84-89b82507028a', ... 'subject', {'flowers', 'ZM_307'}) sessions = ai.getSessions('lab', 'cortexlab', ... 'date_range', datenum([2018 8 28 ; 2018 8 31])) sessions = ai.getSessions('date', now) sessions = ai.getSessions('data', {'clusters.probes', 'eye.blink'}) [~, eids] = ai.getSessions(expRefs)

See also: ALYX.UPDATESESSIONS, ALYX.GETDATA

◆ queueDir()

function set alyxManager::queueDir	(	in	me,
		in	qDir
	)

◆ registerALF()

function alyxManager::registerALF	(	in	me,
		in	alfDir,
		in	sessionURL
	)

Close an Alyx session.

Closes the current session by setting end_time and optionally updating the narrative and QC fields.

Parameters

narrative	char[] narrative text to add (optional)
QC	char quality control status (default 'NOT_SET')

Returns: session struct the updated session record

See also: ALYX, UPDATENARRATIVE

◆ registerALFFiles()

alyxManager::registerALFFiles	(	in	me,
		in	paths,
		in	session
	)

registers all files in an ALF path to Alyx

Parameters

◆ registerFile()

function alyxManager::registerFile	(	in	me,
		in	rFiles
	)

Full path for file pertaining to designated experiment.

Returns the path(s) that a particular type of experiment file should be located at for a specific experiment. NB: Unlike dat.expFilePath, this CAN NOT be used to determine where a file should be saved to. This function only returns existing file records from Alyx.

Parameters

varargin can be (ref, type[, user, reposlocation]) or (subject, date, seq, type[, user, reposlocation])

Returns: fullpath char[] full file paths; filename char[] file names; fileID char[] file UUIDs; records struct[] complete records from Alyx

See also: ALYX

◆ rmEmpty()

static function alyxManager::rmEmpty ( in A )

static

◆ secretUI()

function alyxManager::secretUI	(	in	me,
		in	field
	)

◆ setSecrets()

function alyxManager::setSecrets	(	in	me,
		in	password,
		in	AWS_ID,
		in	AWS_KEY,
		in	force
	)

check secrets for the AlyxManager instance

◆ updateNarrative()

function alyxManager::updateNarrative	(	in	me,
		in	comments,
		in	endpoint,
		in	subject
	)

Lists recorded subjects.

Lists the experimental subjects present in main repository. If logged in, returns a subject list generated from Alyx, with the option of filtering by stock (default false) and alive (default true). The sortByUser flag, when (default) true, returns the list with the user's animals at the top.

Parameters

stock	logical filter by stock (default false)
alive	logical filter by alive status (default true)
sortByUser	logical sort user's animals first (default true)

Returns: subjects cell array of subject names

See also: ALYX

◆ url2eid()

static function alyxManager::url2eid ( in url )

static

◆ user()

function set alyxManager::user	(	in	me,
		in	value
	)

◆ validateFcn()

function alyxManager::validateFcn ( in fileObj )

Register files contained within alfDir to Alyx.

Files are only registered if their filenames match a datasetType's alf_filename field. Must also provide an alyx session URL.

Parameters

alfDir	char directory containing ALF files
sessionURL	char Alyx URL of the session (uses me.sessionURL)

See also: ALYX, REGISTERFILES, POSTDATA, HTTP.JSONGET

◆ valueTable()

static function alyxManager::valueTable ( in s )

static

Concatenates different structures into one structure array.

Returns a non-scalar structure made from concatenating the structures in cellOfStructs and optionally replacing any missing values. NB: all empty values in the output struct are replaced by missingValue, including ones present in the original input.

Parameters

cellOfStructs	cell cell array of structs to concatenate
missingValue	any value to replace missing fields with

Returns: s struct concatenated structure array

Example: s = catStructs({struct1, struct2}, NaN)

See also: ALYX

Member Data Documentation

◆ baseURL

Property alyxManager::baseURL

the URL of the ALYX database

◆ cache

Property alyxManager::cache

protected

◆ lab

Property alyxManager::lab

the lab defined in the Alyx database

◆ loggedIn

Property alyxManager::loggedIn

◆ pageLimit

Property alyxManager::pageLimit

limit how many values returned

◆ queueDir

Property alyxManager::queueDir

where to save the temporary json files sent via REST

◆ sessionParentURL

Property alyxManager::sessionParentURL

if we open a new session as a child, this is the base session URL

◆ sessionURL

Property alyxManager::sessionURL

if we open a new session this is the main URL

◆ subject

Property alyxManager::subject

the experimental subject

◆ token

Property alyxManager::token

protected

◆ user

Property alyxManager::user

the user to login

◆ verbose

Property alyxManager::verbose

more logging for debugging

◆ webOptions

Property alyxManager::webOptions

The documentation for this class was generated from the following file:

communication/alyxManager.m

Detailed Description

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ alyxManager()

Member Function Documentation

◆ baseURL()

◆ catStructs()

◆ cellflat()

◆ closeSession()

◆ createSession()

◆ delete()

◆ ensureCell()

◆ expFilePath()

◆ flushQueue()

◆ getData()

◆ getSecrets()

◆ getSessions()

◆ getToken()

◆ hasEntry()

◆ hasSecrets()

◆ iff()

◆ initDatabase()

◆ isAProp()

◆ jsonPost()

◆ listSubjects()

◆ loggedIn()

◆ login()

◆ logout()

◆ makeEndpoint()

◆ mapToCell()

◆ namedArg()

◆ parseAlyxInstance()

◆ pick()

◆ postData()

◆ processValue()

◆ queueDir()

◆ registerALF()

◆ registerALFFiles()

◆ registerFile()

◆ rmEmpty()

◆ secretUI()

◆ setSecrets()

◆ updateNarrative()

◆ url2eid()

◆ user()

◆ validateFcn()

◆ valueTable()

Member Data Documentation

◆ baseURL

◆ cache

◆ lab

◆ loggedIn

◆ pageLimit

◆ queueDir

◆ sessionParentURL

◆ sessionURL

◆ subject

◆ token

◆ user

◆ verbose

◆ webOptions