nstitute AIMS User Guide

Institute of Mathematics and Computer Science

European Bioinformatics Institute

User Guide

Version 2.05

AIMS

Accessing AIMS system

To access Assay Information Management System you need a valid login name and a
password. If you think that you should have access to this page, but don't have login
name/password you should contact the System Administrator.

Different user s might have different access rights . Currently acce ss rights are managed at
technology level (the user can access only these Technologies access to which have been
granted to him) and at entry ownership level - depending from ownership particular entries
could be available either fully or partially or be hidden for a particular user. Also the access
rights determine whether the user will be able to create new entries. If user has access to
several Technologies, his access rights for different Technologies might be different.

There are several pages or other functionality of the system that might be unavailable or
partially available to users without sufficient access rights.

Changing user settings

User settings page allows to modify a number of user-specific settings. The modified values

are activated immediately in the current session as well as saved and used in subsequent
sessions. The settings that currently can be modified are the following:

Page size. This value specifies the number of entries that are displayed in single page in
either of 1st level (Views), 2nd level (Samples), 3rd level (Assays) pages. The default value (if
not modified by user) depends from the configuration of particular AIMS instance.

Start with welcome page. This specifies whether after login in the system the first page that
is displayed is " W el co m e pa ge " . Th e main purpose of this pa g e is sh ow ing which user grou p is
used as default group in current session, and consequently, what access rights other users will
have to entries created by user within a particular session.

Default user group. This allows to change a user group that will be used as as default in
current session, and consequently, what access rights other users will have to entries created
within this particular session. The access rights specific to the selected default group are
shown in table below.

Change password. Allows user to change password.

Welcome page

Welcome page can be displayed as a first page after login in the system. Whether this is the

case depends from the settings of user account and can be modified by user by clicking on
User settings tab. In addition, the page will be unconditionally displayed to users with
administrator rights if there are some external tasks that need to be performed.

The main functionality of this page is the option to see and change if necessary the default
group that will be used in current session, and consequently, what access rights other users
will have to entries created within this particular session. The access rights specific to the
selected default group are shown in table below.

Study level

List of Studies page allows to view/edit/delete data either for all Studies currently in
database, which are attributed to particular Technology, or Studies contained within a
particular View (if Views are configured for the given Technology). If your access rights don't
allow to access a particular Experiment even in view only mode, only the value of Study ID will
be shown, all other values will be replaced by **.

Selection of Technology
If no Technology is selected, as a first step you must select a particular Technology you will be

working with. To do this, click on Select Technology tab, select a Technology from drop-down
list and click on Change button. Technology can be changed at later stage using Select
Technology tab. Note that when Technology is changed all settings made for this Technology
during the current session (such that configurations of Views/Study/Assays pages or filter
settings) are lost.

Creating/viewing/editing/deleting Studies

- To add a new Study to database click on New Study tab. If you are viewing Studies
attributed to one particular Study then new Study will be defined for that group. Otherwise the
new Study will be created together with a new Study.

- To edit data about a Study click on the corresponding edit icon
access rights one of the following icons will be shown instead:

in view only mode, you can also view data and supplementary files for the particular Study),

(the Edit dialog is available in view only mode, you cannot access data and supplementary

files),

- To create a new Study with the parameters copied from the existing one click on the
corresponding clone icon
will be replaced by

- To delete entry about a particular Study click on the corresponding edit icon
press Delete button. If there are Assays attributed to the given Study the button will be
replaced with * Delete. This allows deleting of Study and all Assays belonging to it. Since this
is a potentially dangerous operation, you will need to reconfirm the intention to delete as well
as to provide the exact number of Assays belonging to this Study.

- To change simultaneously the values of some properties for several Studies click on Batch

edit tab. You will have the option to select Studies for editing and then, after pressing Edit
Selected button, will be directed to edit dialog which allows to change properti e s of selected

Studies.
Add/Edit/View Study dialog allows you correspondingly to e nter data about a new Study or

to edit/view (depending of your access rights) data for already existing Study.
The values of Study Ids are generated automatically, these va lues depend from T echnology

and user who is creating Study. Ids of Studies are unique.
Data files and Supplementary files allow you to link to Study and upload data files obtained

from experiments as well as supplementary information files. Depending from AIMS
configuration you have the option of just uploading files from your local computer, or choice
between uploading files from your local computer or selection of files already pre-uploaded via
FTP. Depending from technology configuration you also may have the option to associate file
type with each of the files, however currently this is treated just as informal comment.
It is possible t o link several Data or Supplementar y files with each Study, howe ver you ne ed
to press Update button after linking each of the files and re-open Edit dialog for linking

(you don't have access to Study).

. If you don't have access rights to a particular Study, the icon

.

. If you have limited

(the Edit dialog is available

and then

another one.
Technically there is no difference between treatment of Data files and Supplementary files,
however it is recommended that Data files are used for files obtained from experiments and
Supplementary files for providing additional information which can't be entered via Edit dialog
fields.

The meaning of other fields hopefully should be self-apparent. The datatypes for each of the
fields are shown on the right side (position mouse over datatype names for some additional
information).

In Batch edit mode there is a checkbox for each of Studies' fields. Check the boxes for fields
values of which you wish to change. Fields are displayed in white, if its values for all Studies
selected for batch editing is the same, and gray if there are different values. Name fields
cannot be changed in Batch edit mode.

Navigation

To navigate to List of Assays page showing Ass ay s of a pa rti c ul ar S tudy click on
Associating Studies with Views
This functionality is available if Views are configured for the given Technology and Studies

associated with a particular View are currently listed.
To change which Studies are includes in a given View click on Define View tab. All Studies will
be listed with a checkbox on a right side (checked for Studies belonging to the given View).
You can freely modify the values of checkboxes and either click on OK Define View (the
Studies associated with this View will be redefined) or on link Cancel Define View (the previous
set of Studies for this View will be kept).

icon.

Batch edit

In Batch edit mode there is a checkbox for each of entries' fields. Check the ones you wish to
change for all entries in the batch. The fields left unchecked (displayed gray) can hold different
values for each entry and the checked ones (displayed white) will hold the changed value for
all entries.

Batch uploading

Upload 1st level (Studies) page allows to upload multiple entries from a single tab-

delimited file. The file must contain a header row with recognized column names (these
consist of a level prefix followed by ".", "Parameter group" (defined in Parameters table) and
the value corresponding to "Upload name" field in in Parameters table - e.g. Study.Software
details.Version) followed by rows corresponding to uploadable entries. Upload names of fields
that are configured in (defined in Common parameters table) are not configurable in Common
parameters table, but specified in "systemConst.xml" file (and in future will be shown in this
table in read-only mode). Usually these names consist only of two components, e.g. Study.ID.
Also, there is extended syntax options for columns describing uploadable files (see below).
Level prefixes (e.g. View, Study, Assay) are also specified in specified in "systemConst.xml"
file.

To obtain a correct header for a particular level, you can download tab-delimited files
containing only this header by clicking on Download ... header or Download ... he ader
(minimal) links; these will provide correspondingly either a header containing all recognized
column names, or a "minimal" he ader containing only names of mandatory columns.

There are three "checkbox" options that you can select for batch uploads at all levels:

- Generate identifiers automatically. If checked, automatic id generation of IDs will be

used and the corresponding column, e.g. Studies.ID, either ignored or disallowed (depending
from Allow unrecognized columns setting. ID generation will not work at 1st level (View), if
the ID generation at this level is not configured for a particular Technology. If unchecked,
column with IDs (e.g. Study.ID) is mandatory and it is required that IDs must be unique (but
see the next op ti o n ) .

- Allow duplicate rows. If checked, then entries with identical IDs are allowed in upload file,
however only a single (assume that randomly selected) entry will be uploaded in system.
Generally this option could be useful only in combination with unselected Generate identifiers
automatically and selected Allow unrecognized columns. The expected use case is upload i n g a
single file containing entries of all three levels - in this case the "whole collection" can be
uploaded by uplo ad i n g the same file corres po n d i n gl y a t 1s t, 2nd and 3rd level.

- Allow unrecognized columns. If checked, the upload file can contain arbitrary column
names that are not recognized by the system. The most typical usage could be uploading a file
with columns for all three AIMS levels (most of them of recognized only at their own level,
apart from parent level ID, which could be used also at child level).

In addition, at 2nd and 3rd levels there is a radio button allowing to specify one of the
following options:

- uploading all entries as child entries for parent entry shown (and selectable) in listbox;

- uploading each entry by specifying its own parent by its ID. In this case a column with
parent ID must be present in upload file (e.g. when uploading 3rd level entries (Assays) the
file must contain also column Study.ID);

- uploading each entry by specifying its own parent by its NAME. In this case a column with
parent NAME must be present in upload file (e.g. when uploading 3rd level entries (Assays)
the file must contain also column Study.NAME).

At 2nd level (Studies) there is also a checkbox Upload under view that activates/deactivates
radio button area. If deactivated, the entries will not be made children of any 1st level entry.
Note that whilst there is many-to-many relationship between 1st and 2nd level entries, via
data upload it is possible to make a 2nd level entry a child only of one 1st level entry.

Locations of upload files.
In all situations the page will contain the following two Browse buttons:

- Parameter file. This allows you to browse your local file system and select tab-delimited file
for upload.

- Local zipped data. This allows to pr ovide a zipped arc hi v e con t ai n ing all the files th at ar e
referenced in parameter file (if any). This ZIP archive is also uploaded form your local file
system. Whilst technically this is a simplest option for file upload, http protocol might impose
severe limitation of archive size that can be uploaded in this way.

If the system and you access rights are configured for pre-uploading files via FTP, two
additional options will be provided:

- FTP zipped data. Instead of uploading ZIP archive from your local system, you can browse
for archives that are already pre-uploaded on the server.

- FTP directory. This provides a similar pre-uploading option, however in this case you have
to specify a pre-uploaded directory containing all the referenced files. This option may be
more convenient for very large files that are hard to pack in a single archive. A notable
difference from the previous option is that in this case you shouldn't reference the same file
more than once. Ignoring this will result in a partially corrupt upload, requiring substantial
manual correction!

If data/supplementary files are pre-uploaded via FTP, there will be some delay before Assays
will be available for editing (

will be shown instead of edit icon). (Edit dialogs still will be

available for users with administrator rights, although note that data files still will not be

copied into repository and changi ng file references are likely to cause errors.) If icon is
shown, this means that there have been some problems with copying data and supplementary
files.

Referencing data and supplementary files.
The column names in header for referencing files that have to be uploaded are defined in

"systemConst.xml" file and will be shown in complete header obtainable via Download ...
header link. E.g., the column names might be Study.DATA_F, Study.DF_TYPE for data files,
and Study.SUPPL_F, Study.SF_TYPE for supplementary (protocol) files. The following features
have to be taken into account:

- columns for data or supplementary files will only be available (or recognized), if linking of
files to entries is configured for particular Collection and particular level;

- the file name (given e.g. in Study.DATA_F) must contain a full path to file either in ZIP
archive or in pre-u ploaded directory .

- the file type (given e.g. in Study.DF_TYPE) is a memo field describing the file. The list of
recognized values can be checked in Edit dialog that corresponds to uploaded entries (there
could be none).

- there is extended syntax allowing to upload multiple files for a single entry. The names of
columns that reference files can contain additional suffix of the form #file_number, where
"file_number" is an arbitrary string which distinguishes different columns. E.g. to upload two
files for a single entry two columns either headers Study.DATA_F#1, Study.DATA_F#2, or
headers Study.DATA_F#SS, Study.DATA_F#17 could be used. The same suffixes can be used
to specify corresponding file types, e.g. Study.DF_TYPE#1, Study.DF_TYPE#2.

Data Export and Transfer

Both data and metadata export (i.e. request made by user's specifications) and data/metadata
transfer (predefined export to a particular) data warehouse are accessible from the same tab
Data export/transfer. To access it from Views/Studies/Assays view pages, first click on Export
tab, select the entries you wish to export and click on Data export/transfer tab.
Depending from technology conf iguration and your access rights a page with a nonempty
subset from the following three sections will be displayed.

Data transfer (transfer name)
This allows to transfer selected entries to data warehouse for which such transfer is configured

for particular technology. Usually each entry should be transfered just once, thus transfered
entries are flagged and although a repeated transfer of flagged entries is possible, a warning
will be issued before doing so.
Note that configuration of data transfer for a given technology makes this option available only
from a single AIMS level (either from Views, Studies or Assays.
The only configurable option in this section is a field for entering email - in this case the
processing program will send the updates of processing status of transfers to this address.
Apart from that, a list of configuration files used for metadata transfer as well as a list of
transferred higher level entries (with num b e r of their children) are shown (depending from the
configuration a transfer may include either metadata or datafile transfer or both).
There is a choice to request transfer by pressing Transfer button and cancelling the operation.
When transfer has been requested the corresponding entries will be marked for processing
and files will be transferred later by an external program. The following flags will be used to

mark entries:
successfully completed),

the actual data transfer has failed, or data warehouse ha s reported tha t ther e are pr obl ems

(transfer has been requested), (the actual transfer of data has been

(a successful reception of data has been confirmed), (either

with transferred files). Some of these flags may not be available for soma data transfer
configurations.

Metadata export
This allows to export metadata according to configuration that is specified by XML template.

According from you access rights there may be only option to select from Configuration files
provided by system administrator, or also an option to Upload your own configuration file.
The syntax of configuration file is described in a separate document, but it allows to configure
meta data export in XML file in rather flexible format. Export can include metadata from the
aims AIMS level from which it has been requested, from all child levels as well as from all
SIMS levels that are referenced from these entries.
Export file can be generated in two formats: XML (native format) and TSV (a tab delimited file
that is obtained from "flattening" native XML file).

Data export
This allows to export data and supplementary files. For the option to functional you must

additionally setup the options how the data files will be delivered. This is done via XML
configuration file that should be set up by system administrator.
There are two options how transfers is being made (and these should be specified in
configuration file mentioned above): sending of files to FTP to a server of your choice (in this
case you should provide to administrator server location and login details), and copying files
on the same server to different directory (e.g. your account home directory). The configurable
options in this section are: providing Export name (this shoul d be obtained from administrator
and will be used to recognize that export is initiated by you and ned to be delivered to your
location) and email address for feedback (an email will be sent to this address after the export
will be completed). After the export is requested, the corresponding entries will be marked for
processing and files will be exported later by an external program.

Directories of XML configuration files
The root directory of configuration files is defined in web.xml file by <context-param> entry

data_transfer_configuration.directory. Within this directory the location of configuration
files are as follows:

Metadata export configuration files:

exports/[technology directory]/l1 (export at Assays level),
exports/[technology directory]/l2 (export at Studies level),
exports/[technology directory]/l3 (export at Views level),

where [technology directory] is defined by FTP directory entry in Technologies table.
Date transfer configuration files:

transfers/[technology directory]/[transfer directory],
where [technology directory] is defined as above and [transfer directory] corresponds to Data
directory entry in Transfer types table.

Assay level

List of Assays page allows to view/edit/delete data either for all Assays currently in
database, which are attributed to particular Technology, or Assays attributed to particular
Experiment. If your access rights don't allow to access a particular Assay even in view only
mode, only the value of Assay ID will be shown, all other values will be replaced by **.

Selection of Technology
If no Technology is selected, as a first step you must select a particular Technology you will be

working with. To do this, click on Select Technology tab, select a Technology from drop-down
list and click on Change button. Technology can be changed at later stage using the same
Select Technology tab. Note that when Technology is changed all se ttings made for this
Technology during the current session (such that configurations of Study/Experiment/Assay
pages or filter settings) are lost.

Creating/viewing/editing/deleting Assays

- To add a new Assay to database click on New Assay tab. If you are viewing Assays attributed
to one particular Experiment then new Assay will be defined for that group. Otherwise the new
Assay will be created together with a new Experiment.

- To edit data about a Assay click on the corresponding edit icon
access rights one of the following icons will be shown instead:

in view only mode, you can also view data and supplementary files for the particular Assay),

(the Edit dialog is available in view only mode, you cannot access data and supplementary

files),

- To create a new Assay with the parameters copied from the existing one click on the
corresponding clone icon
will be replaced by

- To delete entry about a particular Assay click on the corresponding edit icon
press Delete button.

- To change simultaneously the values of some properties for several Assays click on Batch

edit tab. You will have the option to select Assays for editing and then, after pressing Edit
Selected button, will be directed to edit dialog which allows to change properti e s of selected

Assays.
Add/Edit/View Assay dialog allows you correspondingly to enter data about a new Assay or

to edit/view (depending of your access rights) data for already existing Assay.
The values of Assay Ids are generated autom atically, these values depend from Technology,

Experiment and user who is creating Assay. Ids of Assays attributed to a particular Experiment
will be unique.

The Aliquot field should either be filled by using the prompting button (if available) and
selecting the referenced Aliquot from the list (in case when multiple Aliquots will be selected,
several Assays, one for each Aliquot, will be created); or can be filled with arbitrary string
value (including empty) if prompting button is unavailable. The requirement of Aliquot
prompting depends from AIMS configuration.

Data files and Supplementary files allow you to link to Assay and upload data files obtained
from experiments as well as supplementary information files. Depending from AIMS
configuration you have the option of just uploading files from your local computer, or choice
between uploading files from your local computer or selection of files already pre-uploaded via
FTP. Depending from technology configuration you also may have the option to associate file

(you don't have access to Assay).

. If you don't have access rights to a particular Assay, the icon

.

. If you have limited

(the Edit dialog is available

and then

type with each of the files, however currently this is treated just as informal comment.
It is possible t o link several Data or Supplementary files with each Assay, however you need
to press Update button after linking each of the files and re-open Edit dialog for linking
another one.
Technically there is no difference between treatment of Data files and Supplementary files,
however it is recommended that Data files are used for files obtained from experiments and
Supplementary files for providing additional information which can't be entered via Edit dialog
fields.

The meaning of other fields hopefully should be self-apparent. The datatypes for each of the
fields are shown on the right side (position mouse over datatype names for some additional
information).

Batch edit

In Batch edit mode there is a checkbox for each of Assays' fields. Check the boxes for fields
values of which you wish to change. Fields are displayed in white, if its values for all Assays
selected for batch editing is the same, and gray if there are different values. Name and Aliquot
fields cannot be changed in Batch edit mode.

Batch uploading

Upload Assays page allows to upload multiple entries from a single tab-delimited file. The file

must contain a header row with recognized column names (these consist of a level prefix
followed by ".", "Parameter group" (defined in Parameters table) and the value corresponding
to "Upload name" field in in Parameters table - e.g. Stu dy .Softwa re details. Version) foll owed
by rows corresponding to uploadable entries. Upload names of fields that are configured in
(defined in Common parameters table) are not configurable in Common parameters table, but
specified in " systemConst.xml" file (and in future will be sh own in this table in read-only
mode). Usually these names consist only of two components, e.g. Study.ID. Also, there is
extended syntax options for columns describing uploadable files (see below). Level prefixes
(e.g. View, Study, Assay) are also specified in specified in "systemConst.xml" file.

To obtain a correct header for a particular level, you can download tab-delimited files
containing only this header by clicking on Download ... header or Download ... he ader
(minimal) links; these will provide correspondingly either a header containing all recognized
column names, or a "minimal" he ader containing only names of mandatory columns.

There are three "checkbox" options that you can select for batch uploads at all levels:

- Generate identifiers automatically. If checked, automatic id generation of IDs will be
used and the corresponding column, e.g. Studies.ID, either ignored or disallowed (depending
from Allow unrecognized columns setting. ID generation will not work at 1st level (View), if
the ID generation at this level is not configured for a particular Technology. If unchecked,
column with IDs (e.g. Study.ID) is mandatory and it is required that IDs must be unique (but
see the next op ti o n ) .

- Allow duplicate rows. If checked, then entries with identical IDs are allowed in upload file,
however only a single (assume that randomly selected) entry will be uploaded in system.
Generally this option could be useful only in combination with unselected Generate identifiers
automatically and selected Allow unrecognized columns. The expected use case is upload i n g a
single file containing entries of all three levels - in this case the "whole collection" can be
uploaded by uplo ad i n g the same file corres po n d i n gl y a t 1s t, 2nd and 3rd level.

- Allow unrecognized columns. If checked, the upload file can contain arbitrary column
names that are not recognized by the system. The most typical usage could be uploading a file
with columns for all three AIMS levels (most of them of recognized only at their own level,
apart from parent level ID, which could be used also at child level).

In addition, at 2nd and 3rd levels there is a radio button allowing to specify one of the