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

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

plugin -> plug-in in readme

File size: 6.6 KB
Line 
1MageTab Exporter Plug-in
2---------------------------
3
4From BASE2 experiment the plug-in exports the experimental metadata in MageTab format
5
6
7I Description
8----------------
9Executed on an experiment in BASE2, the plug-in generates an SDRF and IDF files
10(see MageTab specification at http://www.mged.org/mage-tab/) with experiment's metadata,
11and an archive containing raw data files.
12
13
14II Requirements
15----------------
16The plug-in 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 plug-in with earlier versions of BASE, please let the developer know.
18 
19
20III Installation
21----------------
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 plug-in 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 plug-in (if any).
27  (5) Click Save
28
29  The new plug-in appears under the name "MageTab exporter" in the plug-ins list, and is now ready for use.
30 
31
32IV Usage 
33----------------
34
35The plug-in 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.
37
38The plug-in 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.
41
42The MageTab exporter plug-in has following parameters:
43  - Experiment
44    the experiment to export, set by default to the one that was open when launching the plug-in
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 plug-in 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 plug-in
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 plug-in 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)
71
72The MageTab exporter plug-in supports configuration, so site's default/preferred settings of many parameters can be stored
73and reused to ease the execution. 
74
75
76V Useful tips
77----------------
78       
79To get most of the plug-in capabilities you could:
80  (1) make sure that the format of the author and affiliation fields is parsable by the plug-in.
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"
89   
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 plug-in 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"
97         
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. 
101 
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 plug-in 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 plug-in ("ArrayExpress accession AnnotationType" parameter).
108     
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 plug-in configuration parameter
112  ("Material Type AnnotationType"), the plug-in will use the annotations in the exported SDRF file
113  (Material Type column).
114 
115  (4) store some of the settings in a plug-in configuration. The annotation types are the best candidates. Also
116  raw data file types could be predefined in platform specific configurations.
117 
118   
119
120License
121----------------
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
125http://www.gnu.org/licenses/gpl-3.0.html
126 
Note: See TracBrowser for help on using the repository browser.