Users

Accessing the users page

Access the user administration page from the Admin page. Admin page is only accessible if you are logged in as an administrator

Creating Users

NIS Users

NiDB will check by default if an NIS account already exists when a user logs in for the first time. If the user exists in NIS, an account will created within NiDB. NIS must be enabled and able to authenticate to the NIS through the NiDB server.

Regular Users

To create a regular user, go to Admin → Users. Click the Add User button. Enter their information, including password and email address. The username can be any field, such as an alphanumeric string, or an email address. If the user is given NiDB admin permissions, then they will be able to add/edit users.

Account Self-registration

On public servers, or systems where users are allowed to register themselves, they can create an account and verify their email address to fully register the account. The account will then exist, but they will have no permissions to any projects within NiDB. After a user registers, they will appear on the Admin → Users → All Other Users tab. Click the username to edit their project permissions. Note: be careful allowing users to self-register, for obvious reasons.

Managing Users

There are 3 options of where to find users A) users in the current instance (switch instance by clicking the instance list in the upper left menu) B) users not in the current instance C) deleted users

To manage project permissions for users, go to Admin → Users and click on the username you want to manage. The page can change the name, password, email, admin status, if the account is enabled/disabled, and the projects to which the user has permissions. After changing any information on the page, click the Save button at the bottom of the page. See list of user options and settings below.

Projects

Data collected in the system must be associated with a subject, and that subject must be enrolled in a project. There is a default project in NiDB called Generic Project, but its preferable to create projects parallel to IRB approved studies.

Projects are listed after clicking on the Admin → Projects menu. Clicking the project allows editing of the project options. Clicking the Create Project button will show the new project form. Fill out the form, or edit the form, using the following descriptions of the options

Reports

Reports of imaging studies (often used for billing/accounting purposes on MRI equipment for example) are organized by modality or equipment. Clicking any of the 'year' links will display a calendar for that year with the number of studies per day matching the specified criteria. Clicking the month name will show a report for that month and modality/equipment. Clicking the day will show a report of studies collected on that day.

Overview

All modules in NiDB system are run from the nidb command line program. Modules are automated by being started from cron.

nidb can be run manually to test modules and get debugging information. It can also be used when running on a cluster to insert results back into the database. Running nidb without command line parameters will display the usage.

> ./nidb

Neuroinformatics Database (NiDB)

Options:
  -h, --help                     Displays help on commandline options.
  --help-all                     Displays help including Qt specific options.
  -v, --version                  Displays version information.
  -d, --debug                    Enable debugging
  -q, --quiet                    Dont print headers and checks
  -r, --reset                    Reset, and then run, the specified module
  -u, --submodule <submodule>    For running on cluster. Sub-modules [
                                 resultinsert, pipelinecheckin, updateanalysis,
                                 checkcompleteanalysis ]
  -a, --analysisid <analysisid>  resultinsert -or- pipelinecheckin submodules
                                 only
  -s, --status <status>          pipelinecheckin submodule
  -m, --message <message>        pipelinecheckin submodule
  -c, --command <command>        pipelinecheckin submodule
  -t, --text <text>              Insert text result (resultinsert submodule)
  -n, --number <number>          Insert numerical result (resultinsert
                                 submodule)
  -f, --file <filepath>          Insert file result (resultinsert submodule)
  -i, --image <imagepath>        Insert image result (resultinsert submodule)
  -e, --desc <desc>              Result description (resultinsert submodule)
  --unit <unit>                  Result unit (resultinsert submodule)

Arguments:
  module                         Available modules:  import  export  fileio
                                 mriqa  qc  modulemanager  importuploaded
                                 upload  pipeline  cluster  minipipeline  backup

Running Modules

Avaiable modules are: import, export, fileio, mriqa, qc, modulemanager, importuploaded, upload, pipeline, minipipeline, and backup

For example, to run the import module, run as the nidb user

./nidb import

This will output

-------------------------------------------------------------
----- Starting Neuroinformatics Database (NiDB) backend -----
-------------------------------------------------------------
Loading config file /nidb/nidb.cfg                                              [Ok]
Connecting to database                                                          [Ok]
   NiDB version 2023.2.942
   Build date [Feb 10 2023 11:22:26]
   C++ [201703]
   Qt compiled [6.4.2]
   Qt runtime [6.4.2]
   Build system [x86_64-little_endian-lp64]
Found [0] lockfiles for module [import]
Creating lock file [/nidb/lock/import.441787]                                   [Ok]
Creating log file [/nidb/logs/import20230428113035.log]                         [Ok]
Checking module into database                                                   [Ok]
.Deleting log file [/nidb/logs/import20230428113035.log]                        [Ok]
Module checked out of database
Deleting lock file [/nidb/lock/import.441787]                                   [Ok]
-------------------------------------------------------------
----- Terminating (NiDB) backend ----------------------------
-------------------------------------------------------------

As with all modules, detailed log files are written to /nidb/logs and are kept for 4 days.

Running from cluster

To run nidb from the cluster, for the purpose of inserting results into the database or for checkins while running pipelines, this would be run on the cluster node itself. Access to an nidb.cfg file is necessary to run nidb somewhere other than on the main database server. A second config file /nidb/nidb-cluster.cfg can be copied to the cluster location along with the nidb executable.

pipelinecheckin

To check-in when running a pipeline, use the following

./nidb cluster -u pipelinecheckin -a <analysisid> -s <status> -m <message>

# example
./nidb cluster -u pipelinecheckin -a 12235 -s started -m "Copying data"

The analysisid is the rowid of the analysis which is bring reported on. Status can include one of the following: started, startedrerun, startedsupplement, processing, completererun, completesupplement, complete. Message can be an string, enclosed in double quotes.

updateanalysis

This option counts the byte size of the analysis directory and number of files and updates the analysis details in the main database.

./nidb cluster -u updateanalysis -a <analysisid>

checkcompleteanalysis

This option checks if the 'complete files' list exists. These files are specified as part of the pipeline definition. If the files exist, the analysis is marked as successfuly complete.

./nidb cluster -u checkcompleteanalysis -a <analysisid>

resultinsert

Text, number, and images can be inserted using this command. Examples

./nidb cluster -u resultinsert -t 'Yes' -e 'subject response'

./nidb cluster -u resultinsert -n 9.6 -e 'reactiontime' --unit 's'

./nidb cluster -u resultinsert -i <imagepath> -e 'realignment results'

./nidb cluster -u resultinsert -f <filepath> -e 'useful file'

The admin modules can be accessed by clicking on the Admin menu item. Your account must have administration permissions to see this menu.

Data (Front-end) Administration

Settings that the end-user will see.

• Users - Create and manage users

• Projects - Create and manage projects

• Reports - Create imaging data reports

System (Back end) Administration

Settings that the end-user will not see

• NiDB Settings

• Informational Links

• Backup

• Modules

• Modalities

• Sites

• Instances

• Mass email

• DICOM receiver

Settings

Config variables

The NiDB Settings page contains all configuration variables for the system. These variables can be edited on the Settings page, or by editing the nidb.cfg file. The default path for this file should be /nidb/nidb.cfg. The exact location of the config file is specified on the NiDB Settings page.

PHP Variables

PHP has default resource limits, which may cause issues with NiDB. Limits are increased during the installation/upgrade of NiDB. The current limits are listed on the bottom of the Settings page as a reference if your NiDB installation is not working as expected.

cron

NiDB replaces the crontab for the nidb account with a list of modules required to run NiDB. This crontab is cleared and re-setup with the default nidb crontab each time NiDB is setup/upgraded. Any items you add to the crontab will be erased during an upgrade and need to be setup again.

System messages

At the top of the Settings page, you can specify messages which are displayed system-wide when a user logs in. These can be messages related to planned system down time or other notifications.

Informational Links

NiDB is often run on a network with many other websites such as compute node status, internal Wikis, and project documentation. Links to websites can be specified on the Admin page directly.

Backup

Depending on the size or importance of your data, you may want to backup your data in an off-line format rather than simply mirroring the hard drives onto another server. A backup system is available to permanently archive imaging data onto magnetic tape. LTO tapes are written in triplicate to prevent loss of data. Each tape can be stored in a separate location and data integrity ensured with a majority rules approach to data validation.

Backup process

Backup directory paths are specified in the config file. See the Config variables section.

Data is automatically copied to the backupdir when it is written to the archivedir. Data older than 24 hours is moved from backupdir to backupstagingdir. When backupstagingdir is at least the size of backupsize, then a tape is ready to be written.

Tape 0 lists the current size of the backupstagingdir.

Modules

NiDB has several modules that control backend operations. These can be enabled, disabled, put into debug mode, and the logs viewed.

Enabled modules are listed in green. Running modules will list the process id of the instance of the module. Some modules can have multiple instances running, ie multithreaded, while some modules can only run 1 instance. Each running instance is color-coded with green having checked in recently and red having checked in 2 hours.

Each module has lock file(s) stored in /nidb/lock and log files in /nidb/logs

Module manager

The module manager monitors modules to see if they have crashed, and restarts them if they have. If a module does not checkin within 2 hours (except for the backup module) it is assumed that it has crashed, and the module manager will reset the module by deleting the lock file and removing the database entry.

Modalities

Each modality requires it's own SQL table. Details of the SQL tables, including number of rows and table size, can be viewed on the modalities page.

Sites

Sites are used in various places within NiDB. This section is used when data is collected at multiple sites and stores details about each site.

Instances

NiDB has the ability to separate projects into different instances, basically creating project groups, to which access permissions can be applied. For example, a user can be part of certain instances, giving them the opportunity to view projects within that instance if they have permissions. This can be a good way to group projects from a multi-site project.

Mass email

This will attempt to send an email to every registered email address within the system. It's spam, so use it sparingly.

DICOM receiver