Installation
The steps for installing a LORIS instrument depend on the instrument format chosen (PHP or LINST) and the data storage type selected (SQL table or JSON). This document details different installation options for all types of instruments.
OPTION 1: SQL Table Storage
LINST Instruments - The Instrument Manager
The Instrument Manager module is available to users with the appropriate permissions. This module allows front-end users to upload LINST instruments into the web browser which will then be automatically installed. This module only functions with LINST instruments which are set to use a dedicated SQL table in the database.
Follow the steps below in order to use the Instrument Manager for your instrument.
- Navigate to the Instrument Manager module under the Admin menu.
- Navigate to the upload tab within the module
- Choose browse and select the file you have saved from the Instrument Builder
(the file must have a
.linst
extension) - Click "Install" to submit your instrument.
After installing your instrument, you can load it in a timepoint to test it. For instructions on populating instruments in a timepoint navigate directly to the Test Battery section directly or continue following the documentation.
Note: The instrument manager requires some special configurations to function properly. Make sure to read the module's spec sheet before attempting your first instrument install.
PHP Instruments
PHP instruments behave slightly differently than LINST instruments and
require more manual steps for installation. In order to be able to generate the
SQL table for PHP instruments, they must first be parsed. The LORIS codebase
includes a tool under the tools/
directory called the lorisform_parser.php
allowing for a PHP instrument to be parsed into an intermediary serialized format
and automatically stored in the tools/ip_output.txt
file.
The intermediary state is necessary for the generation of the SQL CREATE TABLE
patch which, in turn, is necessary for the install process when using dedicated
SQL table storage. In order to get from the intermediary serialized format to an
SQL table, the generate_tables_sql.php
tool is then used on the ip_output.txt
file.
Follow the steps below to install a new PHP instrument.
- Move your newly created instrument
NDB_BVL_Instrument_TEST_NAME.class.inc
into theproject/instruments/
directory. - Navigate to the LORIS
tools/
directory. - Run the instrument through the
lorisform_parser.php
to parse the PHP instrument into the intermediary serialed format.ls ../project/instruments/NDB_BVL_Instrument_TEST_NAME.class.inc | php lorisform_parser.php
- Run the
generate_tables_sql.php
tool to converted the serialized format into an SQLCREATE TABLE
SQL patch. The patch will be created in theproject/
directory by default.php generate_tables_sql.php
- Source the newly generated SQL patch
project/TEST_NAME.sql
into your SQL database to create the table. -
Register the instrument in the
test_names
table of the database by running the following command. Make sure to replace the'TEST_NAME'
value with the actual test name used in your instrument.INSERT INTO test_names (Test_name,Sub_group) SELECT 'TEST_NAME', ID FROM test_subgroups WHERE Subgroup_name='Instruments';
Note: The
Sub_group
entry in the query above is necessary for the instrument registration. See the Instrument Grouping section below for additional details.
By completing these steps the instrument should be installed and ready to be assigned to a battery; only instruments assigned to a behavioural test battery are available for data entry For more information about test batteries, navigate to the Test Battery section directly or continue following the documentation.
Note: Each PHP tool mentioned above contains documentation at the top of the file in case additional details are required.
OPTION 2: JSON Data Storage
PHP and LINST instruments using JSON data storage do not require a dedicated
SQL table on the database thus making their installation much simpler. Once your
instrument is finalized, save it and move it to the project/instruments/
directory
(this is the same location the Instrument Manager stores installed instruments).
Once the instrument is in the correct location, you must add it manually to the
test_names
table of the database to register it. The following query can be used
as a template for the registration.
INSERT INTO test_names (Test_name,Sub_group) SELECT 'TEST_NAME', ID FROM test_subgroups WHERE Subgroup_name='Instruments';
Note: The
Sub_group
entry in the query above is necessary for the instrument registration. See See the Instrument Grouping section below for additional details.
By completing these steps the instrument should be installed and ready to be assigned to a battery; only instruments assigned to a behavioural test battery are available for data entry For more information about test batteries, navigate to the Test Battery section directly or continue following the documentation.
Note: The
TEST_NAME
value in the SQL statement must match exactly the LINST file name without the extension or thetestname
value in PHP instruments (i.e. TheTEST_NAME
value forbmi.linst
isbmi
).
Instrument Grouping
In the interest of organization, LORIS allows for instruments to be categorized
on the User interface when displayed in the web browser. This categorization
is made possible by the test_subgroups
database table. Instruments are then
assigned to categories and sorted accordingly on the user's interface.
New entries can be added to the test_subgroups
table to create new categories
and instruments can be assigned a category by updating the Sub_group
column
in the test_names
table with the desired ID
from the test_subgroups
table.