source: extensions/no.uib.ii.magetab/trunk/readme.txt @ 1474

Last change on this file since 1474 was 1474, checked in by pawels, 11 years ago

initial import of the project

File size: 6.5 KB
1MageTab Exporter Plugin
4From BASE2 experiment the plugin exports the experimental metadata in MageTab format
7I Description
9Executed on an experiment in BASE2, the plugin generates an SDRF and IDF files
10(see MageTab specification at with experiment's metadata,
11and an archive containing raw data files.
14II Requirements
16The plugin was developed and tested with BASE 2.16.1. BASE 2.17.x versions should also be fine.
17If you are able to use the plugin with earlier versions of BASE, please let the developer know.
20III Installation
22  (1) Drop the jar in a folder in BASE (e.g. <BASE_HOME>/plugins).
23  (2) Log in to BASE as a root, browse to Administrate -> Plugins -> Definitions, and click New.
24  (3) In the dialog that opens, enter "no.uib.cbu.base.magetabexport.MageTabExporterPlugin" for class,
25    and path to the plugin jar file (e.g. <BASE_HOME>/plugins/MageTabExporter-x.x.jar) for path.
26  (4) In the job agents tab, add job agents that will be able to execute the plugin (if any).
27  (5) Click Save
29  The new plugin appears under the name "MageTab exporter" in the plugins list, and is now ready for use.
32IV Usage 
35The plugin can be launched from the details page of an experiment. Please make sure that the experiment that is
36to be exported is properly created (documented). Use the experiment overview/validation in BASE.
38The plugin supports pooled samples, extracts and labeled extracts, but currently the maximum level of
39nesting of items of one type is 2. This means that pool of samples (and extracts/labeled extracts) is
40supported, but pool of pooled samples (or extracts/labeled extracts) is not.
42The MageTab exporter plugin has following parameters:
43  - Experiment
44    the experiment to export, set by default to the one that was open when launching the plugin
45  - Save as   
46    a path and prefix for the files that are created, e.g. using /home/me/prefix will result
47    in two files being created during the plugin execution: /home/me/prefix_idf.txt and /home/me/prefix_sdrf.txt
48  - Save raw data archive as
49    name of the zip archive with raw data
50  - Overwrite
51    if files with the same names as the ones specified in "Save as" and/or "Save raw data archive as"
52    should be overwritten
53  - Release date
54    a date that is set in the IDF file as the Public Release Date
55  - Quote fields
56    if the content in tab-delimited IDF and SDRF files should be quoted with double quotes
57  - Handle missing content by
58    in certain experimental setups missing/empty content is allowed for biosources and/or samples. The plugin
59    can ignore these missing content and fill empty values with a replacement text (see next parameter).
60    If you don't expect missing items in your experiment and set the parameter to Error, the plugin will fail
61    with an error message if missing/empty item is found
62  - Replace missing content with
63    a text to replace missing items, e.g. "N/A", "-", ""
64  - Raw data file type
65    select the type of the raw data files that should be included in the raw data file archive. Options
66    available here are platform/variant specific
67  - ArrayExpress accession AnnotationType
68    type of annotations holding ArrayExpress accession ids (see (2) on section V to learn more)
69  - Material Type AnnotationType
70    type of annotations holding MGED ontology Material Type terms (see (3) in section V to learn more)
72The MageTab exporter plugin supports configuration, so site's default/preferred settings of many parameters can be stored
73and reused to ease the execution. 
76V Useful tips
79To get most of the plugin capabilities you could:
80  (1) make sure that the format of the author and affiliation fields is parsable by the plugin.
81  This will allow to split individual authors and automatically map them to institutions they are
82  affiliated with. Format the fields in the following way:
83    - individual author entires should be split by ", " (comma + space)
84    - author's names should be split by space, and in follow the order: first_name middle_name last_name
85    - affiliation mark(s) should be numbers following the last name
86    - between last name and affiliation mark(s) no spaces/characters is allowed
87    - affiliation marks should be split by a single comma
88    Example: "John Jack Jones1,3 Joly Jane2, Jeremy Joe Jakes2,1,3"
90    - individual institutions in affiliation field should be in separate lines (split by \n, \r or both)
91    - line number is the institution mark, e.g institution in line 3 will be mapped to authors with
92      affiliation mark 3.
93    - if you put a number in front of the institution name it will help you check if the plugin did
94      a good job mapping authors with affiliations
95    Example: "1 Institute Without a Name, Somestreet 100, 5044 Sometown, Somewhere
96          2 Institute With a Name, Otherstreet 10, 1042 Othertown, Somewhereelse"
98  The affiliation marks and the numbers preceding institutions are not removed, and will be present in the
99  exported IDF file. This allows to check if the automatic mapping is correct. Afterwards, before the files are submitted
100  to ArrayExpress, the numbers should be removed. 
102  (2) create an annotation type representing an ArrayExpress accession identifier. The annotation type
103  should be enabled for array designs and protocols, and used to set accession ids on the items that
104  had been previously exported to ArrayExpress. If you export an experiment using a design or protocol(s)
105  with such an annotation, the plugin will pick up identifiers from the annotations, and use them in
106  the exported SDRF file (Array Ref and Protocol Ref columns). Just remember to set the correct annotation
107  type when you configure the plugin ("ArrayExpress accession AnnotationType" parameter).
109  (3) create an annotation type representing an MGED Ontology term: Material Type. The annotation type
110  should be enabled for biosources, samples, extracts and labeled extracts. If you then annotate your
111  biomaterials using this annotation type, and select it in the plugin configuration parameter
112  ("Material Type AnnotationType"), the plugin will use the annotations in the exported SDRF file
113  (Material Type column).
115  (4) store some of the settings in a plugin configuration. The annotation types are the best candidates. Also
116  raw data file types could be predefined in platform specific configurations.
122All rights reserved. This program and the accompanying materials
123are made available under the terms of the GNU Public License v3.0
124which accompanies this distribution, and is available at
Note: See TracBrowser for help on using the repository browser.