ISAcreator V User Guide. User Guide: V1.3.2 February2011 Contact: Download:

Transcription

1 ISAcreator V User Guide User Guide: V1.3.2 February2011 Contact: isatools@googlegroups.com Download: 1

2 USER GUIDE LIST OF IMPROVEMENTS Improved user interface - addition of pure swing scroll bars throughout the tool - enhancement to the graphic (icons, buttons, corners) Publication and bibliographic search widget - overhaul and redesign Live configuration switch-over - it is no longer required to restart ISAcreator should user need to change configuration, for instance, when creating a new study with different annotation requirements QR code generation plugin component - it enables producing QRcode label using ZXing library, while reusing component developed for the mapping tool to associated metadata annotation (for example the vector of factor values defining a treatment) to the actual barcode 2

3 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 22 Default Folder Configuration page 23 Protocol and Contact exchange page 24 Build in text editor page 25 Ontology search page 26 Publication fetcher page 27 User profile and data catching page 28 File browser/chooser page 31 Expert assistance page 35 Mapping widget page 45 Experiment visualization page 55 Plugin Architecture page 65 3

4 ISAcreator INTRODUCTION Biological, biomedical and environmental studies commonly range from simple one assay-based to complex multiassay 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

5 MAIN MENU OPTIONS 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, examples of ISA-Tab formatted example are provided for you for importing, editing and learning the tool s functionalities. Before you import this example, you have to import the default configuration provided. More test examples are available from the ISA-Tab webpage. 5

6 ISA ANNOTATION STRUCTURE (1) Tree view Tree view Tree view Tree view 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 accessing the Study menu, and then use the + add study button; 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), 6 study(s), sample(s) and assay(s), and allows navigating between their forms and spreadsheets.

7 ISA ANNOTATION STRUCTURE (2) 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, located just right above the first column of the assay section. 7

8 ISA ANNOTATION STRUCTURE (3) 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

9 ISA ANNOTATION STRUCTURE (4) 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

10 ISA ANNOTATION STRUCTURE (5) 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

11 An example. User Guide V1.3.2 February2011 ISA ANNOTATION STRUCTURE (6) 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

12 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 and to learn the tool s functionalities, a default configuration and several examples are provided in the ISAcreator distribution package. 12

13 SPREADSHEET FUNCTIONALITY 13

14 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

15 SPREADSHEET FUNCTIONALITY (2) 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

16 SPREADSHEET FUNCTIONALITY (3) 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

17 SPREADSHEET FUNCTIONALITY (4) 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

18 SPREADSHEET FUNCTIONALITY (5) 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

19 SPREADSHEET FUNCTIONALITY (6) 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

20 SPREADSHEET FUNCTIONALITY (7) 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

21 SPREADSHEET FUNCTIONALITY (8) Transposed View functionality. For added useability, it is possible to transpose the record view so that records are shown as columns. This particularly useful when few records are present and when large amount of descriptors are present. Highlighting function is also available from this view. It paints rows is different shades depending on the ISA syntactic field elements (e.g all Characteristics*+ fields are colored in green, Factor Values*+ in blue and so on ). Note that the ontology annotation widget is available from this view too! 21

22 BUILT-IN WIDGETS 22

23 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. 23

24 Config location SETTINGS It is now possible to define default location where ISAcreator will fetch ISAconfigurations and ISA submission from. This saves time when looking for information and can help keeping things tidy on one place. To do so, navigate to settings from the main menu and select the program file locat from the available settings pane and fill in the necessary information. 24

25 Protocol and Contact Exchange When dealing with multiple installation of ISAcreator, users may need to exchange protocols and contacts information between those instance. This is now possible thanks to these 2 tabs. To do so, navigate to settings from the main menu and select the contacts or protocols from the available settings pane. Select export to generate an xml file containing all the information from the donor instance) 25 and use import in the acceptor instance to upload the information.

26 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. 26

27 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. 27

28 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 ontology name. 28

29 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. 29

30 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 30

31 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. 31

32 USER PROFILE and CACHING 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. 32

33 FILE BROWSER/CHOOSER (1) 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. 33

34 FILE BROWSER/CHOOSER (2) 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). 34

35 FILE BROWSER/CHOOSER (3) 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. 35

36 EXPERT ASSISTANCE 36

37 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. 37

38 EXPERT ASSISTANCE (2) Define study Step: The wizard asks for information about the study The organism being used (support only single organism studies for now) The number of factor groups (treatment groups) The number of subjects for each treatment group (in other words, the size of each treatment group or the number of biological replicates, i.e. animals, cultures). The factors (or experimental variable) and their levels 38 The assays (or response variables) and this bit is identical to the assay section creating study manually from scratch)

39 EXPERT ASSISTANCE (3) 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. 39

40 EXPERT ASSISTANCE (3) Factor Levels widget: Its purpose is to allow description of values taken by a declared factor in the experimental design. The widget is essentially a set of records. Records may be added or removed as needed thanks to buttons provided in the top right-hand corner. A unit option tick box is provided and should be used when reporting quantitative factor levels such as time point, decomposed as a numeric value and an associated unit A contextual menu is available through a right click. It allows to copy, paste, and propagate a selected valued to the entire column. The widget also support pasting from your favourite spreadsheet editor. Finally, the Factor Level widget also rely on the Ontology Lookup Widget for supporting textual 40 annotation (see next slide)

41 EXPERT ASSISTANCE (3) Type here for looking up terms Type here to search the recent history Type here directly for free text Factor Levels widget: When reporting Quantitative Factor Levels, such as the name of a drug, the genetic modification made, the unit box should be unchecked. Activating a cell in the table displays the Ontology widget, which may be used to lookup terms. If free text is good enough, simply type in the bottom box. Tip! Semi-colon are treated as value separator, so you can type in a semi-colon separated list of values and each value will be assign to a specific cell in the factor level widget. 41

42 EXPERT ASSISTANCE (4) 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). 42

43 EXPERT ASSISTANCE (5) Check treatment 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 fails). 43

44 EXPERT ASSISTANCE (6) 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! 44

45 EXPERT ASSISTANCE (7) Overview. Based on the information you have entered the wizard computes and creates the different study(s) and assay(s), filling several fields and assigning certain identifiers. It relies on the visualization component to provide an overview of the overall experiment. At this stage, you can still go back and alter the information entered continue adding (or editing) the information where necessary. IMPORTANT: Clicking the Next button on this page finalizes the creation of the ISA spreadsheets. It is then 45no longert possible to go.

46 MAPPING UTILITY 46

47 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. 47

48 MAPPING UTILITY (2) Click here to open file chooser and select the file to be imported 48

49 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. 49

50 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. MAPPING UTILITY (4) 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 (-) ). 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. 50

51 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! 51

52 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. 52

53 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. 53

54 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. 54

55 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. 55

56 EXPERIMENT VISUALIZATION 56

57 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. 57

58 EXPERIMENT VISUALIZATION (2) 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. 58

59 EXPERIMENT VISUALIZATION (3) 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). 59

60 EXPERIMENT VISUALIZATION (4) 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 or review phase. 60

61 Plugin Architecture 61

62 Plugin Architecture: QR codes(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. 62

63 Plugin Architecture: QR codes(2) The plugin architecture is demonstrated here with a 2 nd generation barcode creation function. It relies on Zebra Crossing QR code library and has been developed to provide a facility for bridging experimental planning and wet lab realization. Barcodes can be read by mobile devices and the function could prove extremely valuable when hooking to automated workstations. 63

64 Plugin Architecture: QR codes(3) Qrbuilder enables experimentalists to decide which information to include in a user friendly way. In this example, labels will encode information about treatment conditions in the form of a vector of factor values and the name of the Source material. Clicking the QrCodes icon in the menu bar displays both the actual QR codes and the corresponding information. Those Qrcodes can be saved and printed and associated the each ISA record. 64