isacreator user guideisatab.sourceforge.net/docs/isacreator_v1.2_user... · biological, biomedical...

User Guide V1.2 May 2010

http://isatab.sf.net

1

ISAcreator V 1.2

User Guide

User Guide: V1.2 May 2010

Contact: [email protected]

Download: http://isatab.sf.net

http://isatab.sf.net/

mailto:[email protected]




2

USER GUIDE TABLE OF CONTENT

• ISAcreator introduction page 3

– Main menu options page 4

– ISA annotation structure page 5

• Functionalities overview page 11

– Spreadsheet functionality page 12

– Proxy settings page 21

– Build in text editor page 22

– Ontology search page 23

– Publication fetcher page 26

– User profile and data catching page 28

– File browser/chooser page 29

• Expert assistance page 32

• Mapping widget page 40

• Experiment visualization page 50




3

ISAcreator INTRODUCTION

Biological, biomedical and environmental studies commonly range from simple one assay-based to complex multi-assay studies, as shown in the figure. Such studies are information intensive and to record their complex structure it is necessary to define and capture the experimental metadata, including experimental design, sample source(s) and treatment(s), the preparation of the sample for the analytical assay, the processes and instruments used throughout, and the final data.The ISAcreator is a ‘user-friendly’ standalone Java application that addresses these needs by assisting the experimentalists to annotate and edit the metadata - in ISA-Tab format - and associate raw and derived data as external files.




4

After creating your profile, you log in to create new studies manually or with the help of the expert assistance functionality. You can also upload and edit an existing study (this option is also useful when similar studies needs to be created), or map and import metadata from a spreadsheet (this option is useful for legacy datasets).

When downloading the ISAcreator zip file, an example ISA-Tab formatted example is provided for you for importing, editing and learning the tool’s functionalities: <<BII-I-1>> is an investigation with 2 studies each with several assays. Before you import this example, you have to import the (corresponding) example configuration provided <<isa_configuration-20100117>>. More test examples are available from the ISA-Tab webpage.

MAIN MENU OPTIONS


http://isatab.sourceforge.net/examples.html





5

ISA ANNOTATION STRUCTURE (1)

ISAcreators uses four central panes to help you describe the experimental metadata: (1) the ‘investigation definition’ and (2) the ‘study definition’ forms, (3) the ‘sample definition’ and (4) the ‘assay’ spreadsheets.

A study is created (or removed) by clicking on ‘+study’ or ‘-study’ buttons, in the bottom left pane, as indicated by the arrow; note that only when two or more studies are created the investigation form appears to group related studies.

An expandable tree view, in the top left pane, displays the relation between the investigation (if present), study(s), sample(s) and assay(s), and allows navigating between their forms and spreadsheets.

Tree view

Tree view

Tree view

Tree view




6


The ‘study definition’ form.

This form allows you to: (1) describe the overall study; (2) define key entities, as applicable, such as design, associated publications, factors (or experimental variable), protocols, parameters, which need to be referenced in the sample and assay spreadsheets; (3) create related assay spreadsheet(s).

An assay is created by (1) defining the type of measurement (i.e. gene expression) and the technology employed (i.e.DNA microarray) in the relevant section, and (2) clicking on the ‘+create assay’ button.




7


The ‘investigation definition’ form.

Only when two or more studies are created the investigation form appears to group related studies. This form allows you to: (1) describe the overall investigation; (2) associate related publications; and (3) specify contact information.




8


The ‘sample definition’ spreadsheet.

This spreadsheet allows you to describe the samples used in the study, their source(s), characteristics, sampling methodology and any treatments or manipulations performed, prior to preparation for the analytical assay(s).




9


The ‘assay’ spreadsheet.

This spreadsheet allows you to (1) link each sample (described in the sample definition sheet) to a type of assay (as defined in the study form), (2) specify protocols and additional information relating to the execution of those protocols, and (3) references the associated data files (whether raw or derived).

ISAcreator and the underlying ISA-Tab format focus on structuring the experimental metadata; raw and derived data files are considered as external files.




10

An example.

In a study looking at the effect of a compound inducing liver damage in rats by characterizing the metabolic profile of urine (by NMR spectroscopy) and measuring protein and gene expression in the liver (by mass spectrometry and DNA microarrays respectively), you need to create one study and three assay.

• In the study form you (1) describe the overall study; (2) define the design, associated publications, if relevant, factors (i.e. compound, dose), protocols (i.e. housing, treatment), parameters, which need to be referenced in the sample and assay spreadsheets; (3) create three assay spreadsheet(s), defining the defining for each the type of measurement (i.e. gene expression) and the technology employed (i.e. DNA microarray)

• In the sample spreadsheet you (1) add information on the rats (source) specifying their characteristics (i.e. sex, strain, provider); (2) describe their treatment with the compound and the steps undertaken to take urine and liver (sample) from the treated rats (sample); (3) reference to relevant protocol(s) - declared in the study form, (4) reference to relevant factor(s) - declared in the study form- and specify their value(s) (i.e. penicillin, 1mg/day)

• In the first assay spreadsheet for the urine metabolic profile (measurement) by NMR spectroscopy (technology) you define the (stepwise) description of the methods by which the urine was processed for the assay, subsequent steps and protocols, and the link to the resultant raw and derived data files.

• In the second assay spreadsheet for the gene expression profile (measurement) by DNA microarray (technology) you define the (stepwise) description of how the RNA extract was prepared from the liver (or a section), how the extract was labeled, how the hybridization was performed and so on, and will also contain the links to the resultant raw and derived data files.

• In the third assay spreadsheet for the protein expression profile (measurement) by mass spectrometry (technology), you define the (stepwise) description of how the protein extract was prepared from the liver (or a section), how the extract was labeled, how the hybridization was performed and so on, and will also contain the links to the resultant raw and derived data files.





11

FUNCTIONALITIES OVERVIEW

• Key ISAcreator functionalities

– It draws on spreadsheets, such as Excel, for its look and feel

– It provides a ‘wizard’ to assist users in describing an experimental design

– It offers visualizations of the structure and balance of studies

– It increases efficiency by remembering prior behavior (via user profiles) and by providing functions such as ‘auto fill’, sorting and citation import

– It supports tagging of data with ontology terms accessed in real time

– It allows import from existing spreadsheets through a mapping widget

• Configuration functionalities (set via the ISAconfigurator tool)

– It can be configured to validate compliance with minimum reporting guidelines and informs the user where required data are missing

– It can be configured to ensure regulate use of ontology and minimum reporting information

• For testing purpose an example of configuration is provided <<isa_configuration-20100117>>, in the ISAcreator distribution package. This allow you to import the <<BII-I-1>> ISA-Tab formatted study to for importing, editing and learning the tool’s functionalities.




12

SPREADSHEET FUNCTIONALITY




13

SPREADSHEET FUNCTIONALITY (1)

‘Add Row’ functionality.

You can call these actions via a button (1) or from a contextual menu activated through a right click (2). You can specify the number of rows using the widget (3). The new rows are added at the bottom of the spreadsheet




14


‘Remove Row’ functionality.

You can remove rows, one at a time or several together, by selecting the row(s) and either click the ‘Remove Row’ button or use the right click to open the contextual menu and select ‘Remove Row’. As the action can not be undone, a warning message is displayed asking for a confirmation, to ensure you do not remove important information accidentally.




15


‘Add Column’ functionality.

You can columns, one at a time, via the contextual menu. Columns headers are controlled in order to comply with ISA-Tab specifications and, for this reason, the mechanism for adding columns is more complex than the one for adding rows. There are 4 types of columns headers (Factors, Characteristics, Protocol REF, Parameters) and each has dedicated buttons, but depending on position some types may not be available for selection. For instance, after a material node, such as ‘Source Name’, you can add ‘Characteristics’ among others, but after a ‘Protocol REF’, you can only add ‘Parameter’, ‘Performer’ or ‘Data’ columns.




16


‘Sort’ functionality.

As with Excel, you can sort on a single field or 2 fields at a time. This is a particularly useful when annotating large sets and for grouping elements based on a particular criteria. The sorting widget contains 2 fields: the first to select the column on which to perform the sort and the second to specify whether sorting should be ascending or descending.




17

‘Copy downwards’ functionality.

You can propagate the annotation by copying downwards the content of a single field or an entire record (i.e. all the values of the fields present in that record).Before carrying out the action, a confirmation message is prompted to the user. As the action can not be undone, a warning message is displayed asking for a confirmation, to ensure you do not copy the information accidentally.





18


‘Simple Autofill values’ functionality.

You can auto generate incremental numbers by (1) activating a cell, (2) select a range of cell, and (3) select the ‘Simple Autofill values’ from the contextual menu.




19

‘Highlight groups’ functionality.

You can color code the samples belonging to the same factor group (defined by the same combination of factor values) by right clicking anywhere in the spreadsheet and select the option provided. Note that this functionality will work only if factor values have been defined. The function also displays a key matching a color code to a factor combination (i.e. diet type, component %).





20

BUILT-IN WIDGETS




21

PROXY SETTINGS

ISAcreator can now operate behind firewalls since proxy settings can now be configured from with the tool.

To do so, navigate to settings from the main menu and select the ‘http_proxy’ from the ‘available settings’ pane and fill in the necessary information.




22

BUILT-IN TEXT EDITOR

You can use the text editor widget - with redo, undo, copy and paste functions- from the study description, protocol description, publication title, publication author list in the investigation and study forms.




23

ONTOLOGY SEARCH (1)

Depending on your configuration (set via the ISAconfigurator), certain fields prompt a pop-up browser to search and select terms from ontologies that are accessed in real time via the Ontology Lookup Service and BioPortal. The ontology search widget contains two panes: the ‘ontology lookup’ function and the ‘recent history’, a list of terms recently used by the logged-in user. You can either select a term for the history list or perform a new search. By default, the search is performed on all ontologies, but depending on your configuration it can be limited to one or more recommended ontologies. The search can be performed either on terms or on their accession numbers.


http://www.ebi.ac.uk/ontology-lookup

http://bioportal.bioontology.org/



24

ONTOLOGY SEARCH (2)

Once the search is completed a the list of ontologies - containing a potential match- is displayed with the short and full name. To view the actual term(s) found in each resource, double click on the (+) icon in front of the ontology name.




25

ONTOLOGY SEARCH (3)

It is likely that each ontology contains several entries (and related identifiers), which include the term you have searched. You should select the entry most relevant to your case by double-clicking it. The selected term will appears in the ‘selected term(s)’ box. By clicking the ‘OK’ button, the term is saved in the appropriate fields, while its identifiers and ontology source are saved into the final ISA-Tab file. Depending on your configuration (set via the ISAconfigurator) and the field, multiple term selection may be allowed.




26

PUBLICATION FETCHER (1)

You can link your study to one or more published paper by clicking the ‘search for publication’ button available in the study publication section. The widget search the PubMed identifier you provide and retrieves title, author list and DOI (when available), using the Citexplore literature search engine. By clicking the ‘OK’ button, the information is saved in the appropriate fields. Note that the tool prevents entering twice the same bibliographic information so it is not possible to create 2 publication fields with the same information




27

PUBLICATION FETCHER (2)

If the paper is in a draft status, it is possible to call the ‘edit text’ function for the title to type or copy and paste information.




28

Via the user profile, ISAcreator remembers information entered by the user in previous sessions to ease the annotation process. The ‘select for history’ widget is available from the investigation and study forms, for contacts, protocols and factors. The widget contains 2 panes: on the left the history and The layout of the widget consists of 2 panes: on the left the history, on the right a pane displays the terms you have selected from the history.

USER PROFILE and CACHING




29

As alternative to typing or copy and paste, a file browser/chooser widget is available when a field is configured (via the ISAconfiguration) to require a link to an external file, for example the data files or image files. The layout of the widget consists of 2 panes: on the left a navigation pane shows the file system structure, on right a selection pane displays all the files selected from the file system. The widget allows you to select individual or multiple files, by browsing local drives or on a remote machine via ftp access.

FILE BROWSER/CHOOSER (1)




30

‘Local’ functionality.

The first navigation pane on the left shows that, when a local folders is selected, its content is displayed is displayed in an organized manner to facilitate file searches and selection. The navigation pane in the middle shows that when opening the folder with PDFs, for example, and selecting relevant files, these are displayed in the selection pane. Here you can sort and reorder the selected files. By clinking the ‘OK’ button, the full path to the file is saved in the appropriate field(s).





31

‘Remote’ functionality (supports for FTP protocol only).

By clicking on the related button, you can enter the necessary information (FTP URI) and credentials (username and password) to establish connection with a remote machine. You can then select the files on the ftp server. A connection status monitors the activity. The file browser/chooser widget also records the credentials, used by the logged-in user, for following connections.





32

EXPERT ASSISTANCE




33

EXPERT ASSISTANCE (1)

The ‘expert assistance’ wizard guides you through the steps of the creation and annotation of a study and its assay(s) by asking a series of questions or presenting options. It leverages on the experimental design information to reduce the amount of manual data entry. Note that this version only supports factorial and parallel group designs. Support for other designs, i.e. cross-over, will be available in the next releases.




34

Define the ‘study’.

The wizard asks for information about the study, it factors (or experimental variable) and their levels, and also about the size of each sample group (biological replicates of the samples used, i.e. animals, cultures). In the case of an unbalanced design (where the number of samples is different in one or more groups) the values can be edited at later stage.





35

Define ‘factor and levels’.

A widget helps you to define the experimental factor(s) and the associated level (s) that are then used by the wizard to compute the number of factor groups (assuming a parallel group design). Values can typed or copied and pasted from Excel or OpenOffice Calc, or ontology terms can be searched using the ontology lookup widget.





36


The ‘factor level(s)’ are discretized values. For example if the factor is a treatment with a drug, the factor levels are the doses administered to the samples (i.e. high dose, medium dose, low dose and their measure of the effectiveness IC50, IC50/10, IC/2) . This information is used by the wizard to compute the number of factor groups, devised as the cartesian products of the factor levels. Therefore, when defining the factor levels, it is essential to make sure that every single factor level can be used correctly in a combination with the other factor levels (reliance of factorial design assumption). Lastly defined the assay(s).




37


Check ‘factor groups’.

If the design is unbalanced (the number of samples is different in one or more groups) the wizard displays a message above the list of the automatically ‘generated factor groups’. This screen allows you to (1) identify which predicted groups were not used in the actual experiment, or (2) to edit the actual size of the each factor group (i.e. if one or more animals or cell cultures die).




38


Define the ‘assay’.

You are asked to provide more details on each assay type. Tick the relevant box to specify whether the assays were performed on pools of samples. The wizard helps you to account for specific assay features: (1) when using technologies employing labels (i.e. DNA microarrays or Gel electrophoresis) a tick box is available to indicate the ‘dye swap performed’; (2) when using technologies (i.e. DNA microarrays) where more than one design is used (e.g. different version of chips or whole genome split over several chips) a service accessing ArrayExpress fetches array accession numbers or design names. Note that the information is not cached at this stage, so if you go ‘back’ your loose the assay information entered!




39

Return to the spreadsheet view.

Based on the information you have entered the wizard computes and creates the different study(s) and assay(s) spreadsheets, filling several fields and assigning certain identifiers. At this stage, you can continue adding (or editing) the information where necessary. For example, you can add sample characteristics, or protocols and data files locations.





40

MAPPING UTILITY




41

MAPPING UTILITY (1)

The mapping tool allows you to import legacy data into ISA-Tab format.

This data must be: •an Excel file (up to Excel 2004); •a CSV file; or •a tab-delimited file.

To access the mapping utility, click on the ‘map from existing file’ item in the ‘create new study’ menu.




42

MAPPING UTILITY (2)

Click here to open file chooser and select the file to be imported




43

MAPPING UTILITY (3)

Select the types of measurement being performed in this assay and the technology used to carry out the measurement. The selected assays are shown in the right pane.




44

MAPPING UTILITY (4)

The ISA-Tab elements which can be mapped to are shown in a tree on the left hand side of the page. Clicking an element will display the mapping information for that entity.

You can add extra elements such as Characteristics, Factor Values, Comments, and so forth by clicking on this button to display a menu to add these elements.

One ISA-Tab element can be mapped to data in many columns of the incoming file and can be separated by literal values (e.g. a dash (-) ).




45

MAPPING UTILITY (5)

Clicking this icon on the mapping section will display the widget below…

Filter by column name by typing a few letters in the text box. Select a column by clicking on the corresponding list item.

Table view provides an alternative way to select columns (just click on the column), and also provides a way to see some of the data inside the incoming file.

The bars represent columns from the incoming file. Whenever filtering occurs on the list to the left, the corresponding columns and their positions will be highlighted in the green colour.

Whenever a column is selected, this panel will appear to allow you to select the column for mapping!




46

MAPPING UTILITY (6)

The visualization shows the file as the upper most element, the ISA-Tab fields as the next important element, and finally the columns in the incoming file which the ISA-Tab fields map to. This makes for a quick overview of the mapping process.

The graph is fully interactive so you can move it around, zoom in and out.




47

MAPPING UTILITY (7)

For each of the assay declared on the first screen corresponds a round of mapping.The same principles as those describe on the previous slides apply. For each on the ISA-Tab fields available for a particular assay type, those can be mapped to elements from the incoming file.The resulting mapping can be visualized by clicking the next button in order to review and possibly alter a mapping.




48

MAPPING UTILITY (8)

Implemented with this release of ISAcreator is the possibility of saving a mapping for reuse. This comes extremely handy when dealing with legacy data formatted in tabular format.

To save a mapping, simply tick the ‘save mappings?’ box to display the saving function.




49

MAPPING UTILITY (9)

Simply select a folder on the filesystem and provide a name to the mapping. The saving process will generate an xml file which can be read in by ISAcreator mapping function.This is quite convenient for templating.




50

EXPERIMENT VISUALIZATION




51

EXPERIMENT VISUALIZATION (1)

By clicking the ‘overview’ link, you can switch from the spreadsheet view to the graphical overview of a study(s) and its assay(s). The upper section of the screen gives a hierarchical view, displaying the names of the study(s) and related assay(s), along with the measurement(s) made and technology(s) used.




52


Upon selection of an assay, factor groups are displayed in the lower section. By default, each group is named based on the combination of factors (i.e. drug name, dose, time) where the dots represent the number of samples in the group. It provides at a glance view of the number of biological replications per factor group.




53

By clicking on ‘view sample names’ you can display the names associated to each sample. You can also zoom in and out the graphical display to reach a better visualization by using the scroll button of the mouse or by holding the right button of the mouse and rolling forward or backward.Also, by selecting one or more factor groups, the related samples are highlighted in the spreadsheet (see next slide).





54


This view illustrates the colors codes for factor groups shared between the graphical overview (previous slide)and the spreadsheet view. This facilitate the navigation during the annotation process but also during edit orreview phase.


isacreator user guideisatab.sourceforge.net/docs/isacreator_v1.2_user... · biological, biomedical...

Documents