source: trunk/doc/historical/getting_started.html @ 4395

Last change on this file since 4395 was 4395, checked in by Martin Svensson, 14 years ago

References #725 Transferred the getting_started document to docbook format and added to the user section in the documentation. Moved the old getting_started' file to the historical folder

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Date
File size: 24.1 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2
3<!--
4    $Id: getting_started.html 4395 2008-08-15 11:10:59Z martin $
5
6    Copyright (C) 2006 Jari Hakkinen
7
8    This file is part of BASE - BioArray Software Environment.
9    Available at http://base.thep.lu.se/
10
11    BASE is free software; you can redistribute it and/or modify it
12    under the terms of the GNU General Public License as published by
13    the Free Software Foundation; either version 2 of the License, or
14    (at your option) any later version.
15
16    BASE is distributed in the hope that it will be useful, but
17    WITHOUT ANY WARRANTY; without even the implied warranty of
18    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19    General Public License for more details.
20
21    You should have received a copy of the GNU General Public License
22    along with this program; if not, write to the Free Software
23    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
24    02111-1307, USA.
25-->
26
27<html>
28  <head>
29    <title>BASE 2.1 - User documentation: Getting started</title>
30    <link rel=stylesheet type="text/css" href="../styles.css">
31  </head>
32  <body>
33
34    <div class="navigation">
35      <a href="../index.html">BASE</a>
36      <img src="../next.gif">
37      <a href="index.html">User documentation</a>
38      <img src="../next.gif">
39      Getting started
40    </div>
41
42    <h1>BASE 2.1 - User documentation: Getting started</h1>
43
44    <div class="abstract">
45
46      <p>
47        This document describes how to get started with your new shiny
48        BASE box.
49      </p>
50
51      <b>Contents</b>
52      <ol>
53        <li><a href="#administative">Administrative tasks</a></li>
54        <li><a href="#user">User tasks</a></li>
55      </ol>
56
57      <p class="authors">
58        <b>Last updated:</b> $Date: 2008-08-15 11:10:59 +0000 (Fri, 15 Aug 2008) $ <br>
59        <b>Copyright &copy;</b> 2006 The respective authors. All
60        rights reserved.
61      </p>
62
63    </div>
64
65    <p> This description will take you from uploading raw data to
66    running the first analysis plug-ins. Both Affymetrix and Genepix
67    data will be used as examples. </p>
68
69    <ol>
70
71      <li>
72        <a name="administrative"></a>
73        <h2>Administrative tasks</h2>
74
75        <p> Most of the task in this section requires more privileges
76        than the normal user credentials. You should log in as an
77        administrator when you perform these tasks. As always, there
78        are many ways to do things and what is presented here is the
79        path to get going with BASE as fast as possible without
80        creating havoc in future use of the BASE server. </p>
81
82        <ol type=a>
83
84          <li>
85            <p> <b>Create an administrator account</b> <br> Log in as
86            'root' using the password you set during BASE
87            initialization. Create an administrator account. Log out,
88            and use the admin account for all administrative
89            tasks. The root account should not be used as the
90            administrator account. </p>
91          </li>
92
93          <li>
94            <p> <b>Create user accounts</b> <br> Create user accounts
95            using the newly created administrator account. You should
96            give your users appropriate roles, most of them should be
97            assigned to the 'User' role. (Link to role docs?) You can
98            create new roles if the default ones does not fit your
99            needs. </p>
100          </li>
101
102          <li>
103            <p> <b>Create essential plug-in configurations</b> <br>
104            Some plug-ins need to be configured before use, whereas
105            other works out of the box. Some external plug-ins as the
106            <a
107            href=http://baseplugins.thep.lu.se/wiki/thep.lu.se.RMAExpress>RMAExpress
108            plug-in for BASE</a> has to be compiled before including
109            them into your BASE server.</p>
110
111            <p> Core plug-ins are a set of plug-ins that are
112            automatically installed during setup. As pointed out
113            above, these may need a configuration to work. The way to
114            find out which plug-ins need a configuration is to choose
115            Administrate -> Plugins -> Definitions. This will display
116            a list all plug-ins available for your BASE
117            server. Nothing is shown? The reason for this is that your
118            newly created administrator does not own the definitions,
119            change the view/preset to show shared items as well. By
120            clicking on the 'Columns' tab you can select what
121            information should be displayed in the list. Please select
122            'Requires config' in the 'Columns' tab, and move it up in
123            the left panel. Finalize by clicking 'Ok'. The list now
124            has an extra column with yes and no's. Mark the 'true'
125            radio button in the 'Requires config' column to only list
126            plug-ins that need a configuration.
127
128            <p> The exercise above had two important aims. i) To show
129            you what plug-ins already exists, and ii) find three
130            essential plug-ins that needs a configuration each. Before
131            any raw data can be stored in BASE some information has to
132            be available in BASE. The slide design (reporter map) and
133            reporter information (probe set information in Affymetrix
134            vocabulary). For these imports to work for Genepix data we
135            need to create configurations for the "Reporter map
136            importer" and "Reporter importer" respectively, and a
137            configuration is needed for the raw data import plug-in,
138            "Raw data importer", as well. Affymetrix data import works
139            differently and only a "Reporter map importer"
140            configuration is needed.</p>
141
142            <p> The pre-installed plug-in definitions are already
143            shared to group 'Everyone' (all users are members of this
144            group) but the configurations created are not shared by
145            default. The configurations should be shared to the users
146            who should have access to them, normally group
147            'Everyone'. As counterexamples, the reporter importers and
148            reporter map importers do not have to be share to everyone
149            since these imports should only be allowed to be done by a
150            small group of users. Every reporter and reporter map
151            should only be imported once and all users should use the
152            same reporter and reporter map information. The raw data
153            importers should normally be shared to everyone since all
154            users import data into BASE. </p>
155
156            <p> <i>Reporter importer</i> <br> Select the "Reporter
157            importer", and click on the 'New configuration ...'
158            tab. Enter a name in the 'Name' field (Affymetrix probe
159            set importer / Genepix reporter import) and click 'Save
160            and configure' button. The next pop-up expects input of
161            regular expression needed to import reporter data. Here we
162            just give the values to add to the panel, but as of
163            version 2.1 it is possible to use a import format
164            wizard. The wizard is started by clicking on the 'Test
165            with file ...'  button. </p>
166
167            <p> Below we tabulate regexps to enter for a few file
168            formats if you prefer to enter the regexp manually. Note
169            1: Here it is assumed that the default
170            <a
171            href="../admin/extended-properties.html">extended-properties.xml</a>
172            is used. Note 2: your browser may break lines in the
173            table cells, treat these line breaks as a ' ' (space)
174            character. Note 3: Depending on your files the values to
175            input may be different.
176            <table cellspacing=3>
177              <tr>
178                <td align=left> <i>Column</i> </td>
179                <td align=left> <i>Affymetrix</i> </td>
180                <td align=left> <i>Genepix .gpr</i> </td>
181                <td align=left> <i>Genepix .txt</i> </td>
182              </tr>
183              <tr>
184                <td> Data Header </td>
185                <td> "Probe Set ID","GeneChip Array",.* </td>
186                <td> "Block"\t"Column"\t"Row"\t"Name"\t"ID"\t.* </td>
187                <td> 384_number\t384_column\t384_row\t384_position\toligo_id.* </td>
188              </tr>
189              <tr>
190                <td> Data splitter </td>
191                <td> (?!"),(?=") </td>
192                <td> \t</td>
193                <td> \t</td>
194              </tr>
195              <tr>
196                <td> Remove quotes </td>
197                <td> true </td>
198                <td> true </td>
199                <td> true </td>
200              </tr>
201              <tr>
202                <td> Name </td>
203                <td> \Probe Set ID\ </td>
204                <td> \Name\</td>
205                <td> \oligo_id\</td>
206              </tr>
207              <tr>
208                <td> Reporter ID </td>
209                <td> \Probe Set ID\ </td>
210                <td> \ID\</td>
211                <td> \oligo_id\ </td>
212              </tr>
213              <tr>
214                <td> Gene symbol </td>
215                <td> \Gene Symbol\ </td>
216                <td> </td>
217                <td> \gene_symbol_Ensembl*\ </td>
218              </tr>
219              <tr>
220                <td> Cluster ID </td>
221                <td> \UniGene ID\ </td>
222                <td> </td>
223                <td> \RefSeq\ </td>
224              </tr>
225            </table>
226            <br> Finalize with clicking 'Next'. You can of course fill
227            the other entries as well. </p>
228
229            <p> <i>Reporter map importer</i> <br> Affymetrix CDF files
230            do not need a configuration since these are not imported
231            to BASE with a plug-in. Genepix data requires a
232            configuration. To configure a plug-in for Genepix reporter
233            map imports select the "Reporter map importer" from the
234            plug-in definition list. Click on the 'New configuration
235            ...'  tab. Enter a name in the 'Name' field (Affymetrix
236            probe set importer / Genepix reporter map importer) and
237            click 'Save and configure' button. The next pop-up expects
238            input of regular expression needed to import reporter map
239            data. Here we just give the values to add to the panel,
240            but as of version 2.1 it is possible to use a import
241            format wizard. The wizard is started by clicking on the
242            'Test with file ...'  button. Below we tabulate regexps to
243            enter if you prefer to enter the regexp manually:
244            <table cellspacing=3>
245              <tr>
246                <td align=left> <i>Column</i> </td>
247                <td align=left> <i>Genepix .gpr</i> </td>
248              </tr>
249              <tr>
250                <td> Data Header </td>
251                <td> "Block"\t"Column"\t"Row"\t"Name"\t"ID"\t.* </td>
252              </tr>
253              <tr>
254                <td> Data splitter </td>
255                <td> \t</td>
256              </tr>
257              <tr>
258                <td> Remove quotes </td>
259                <td> true </td>
260              </tr>
261              <tr>
262                <td> Reporter ID </td>
263                <td> \ID\</td>
264              </tr>
265              <tr>
266                <td> Block </td>
267                <td> \Block\ </td>
268              </tr>
269              <tr>
270                <td> Column </td>
271                <td> \Column\ </td>
272              </tr>
273              <tr>
274                <td> Row </td>
275                <td> \Row\ </td>
276              </tr>
277            </table>
278            <br> Finalize with clicking 'Next'. You can of course fill
279            the other entries as well. </p>
280
281            <p> <i>Raw data importer</i> <br> Affymetrix CEL files do
282            not need a configuration since these are not imported to
283            BASE with a plug-in. Genepix data requires a
284            configuration. Create a configuration for Genepix raw data
285            import by selecting the "Raw data importer" from the
286            plug-in definition list. Click on the 'New configuration
287            ...'  tab. Enter a name in the 'Name' field (Genepix raw
288            data importer) and click 'Save and configure' button. The
289            next pop-up expects input of regular expression needed to
290            import raw data. Here we just give the values to add to
291            the panel, but as of version 2.1 it is possible to use a
292            import format wizard. The wizard is started by clicking on
293            the 'Test with file ...'  button. Below we tabulate
294            regexps to enter if you prefer to enter the regexp
295            manually:
296
297            <table cellspacing=3>
298              <tr>
299                <td align=left> <i>Column</i> </td>
300                <td align=left> <i>Genepix .gpr</i> </td>
301              </tr>
302              <tr>
303                <td>Raw data type</td>
304                <td>Genepix</td>
305              </tr>
306              <tr>
307                <td>Header</td>
308                <td>"(.+)=(.*)"</td>
309              </tr>
310              <tr>
311                <td>Data header</td>
312                <td>"Block"\t"Column"\t"Row"\t"Name"\t"ID"\t.*"Ratio of Medians \(532\/635\)".*</td>
313              </tr>
314              <tr>
315                <td>Data splitter</td>
316                <td>\t</td>
317              </tr>
318              <tr>
319                <td>Min data columns</td>
320                <td>48</td>
321              </tr>
322              <tr>
323                <td>Max data columns</td>
324                <td>48</td>
325              </tr>
326              <tr>
327                <td>Block</td>
328                <td>\Block\</td>
329              </tr>
330              <tr>
331                <td>Column</td>
332                <td>\Column\</td>
333              </tr>
334              <tr>
335                <td>Row</td>
336                <td>\Row\</td>
337              </tr>
338              <tr>
339                <td>X</td>
340                <td>\X\</td>
341              </tr>
342              <tr>
343                <td>Y</td>
344                <td>\Y\</td>
345              </tr>
346              <tr>
347                <td>Reporter ID</td>
348                <td>\ID\</td>
349              </tr>
350              <tr>
351                <td>Spot diameter</td>
352                <td>\Dia.\</td>
353              </tr>
354              <tr>
355                <td>Channel 1 foreground median</td>
356                <td>\F635 Median\</td>
357              </tr>
358              <tr>
359                <td>Channel 1 foreground mean</td>
360                <td>\F635 Mean\</td>
361              </tr>
362              <tr>
363                <td>Channel 1 foreground standard deviation</td>
364                <td>\F635 SD\</td>
365              </tr>
366              <tr>
367                <td>Channel 1 background median</td>
368                <td>\B635 Median\</td>
369              </tr>
370              <tr>
371                <td>Channel 1 background mean</td>
372                <td>\B635 Mean\</td>
373              </tr>
374              <tr>
375                <td>Channel 1 background standard deviation</td>
376                <td>\B635 SD\</td>
377              </tr>
378              <tr>
379                <td>Percent pixels within 1 standard deviation</td>
380                <td>\% > B635+1SD\</td>
381              </tr>
382              <tr>
383                <td>Percent pixels within 2 standard deviations</td>
384                <td>\% > B635+2SD\</td>
385              </tr>
386              <tr>
387                <td>Percent saturated pixels</td>
388                <td>\F635 % Sat.\</td>
389              </tr>
390              <tr>
391                <td>Channel 2 foreground median</td>
392                <td>\F532 Median\</td>
393              </tr>
394              <tr>
395                <td>Channel 2 foreground mean</td>
396                <td>\F532 Mean\</td>
397              </tr>
398              <tr>
399                <td>Channel 2 foreground standard deviation</td>
400                <td>\F532 SD\</td>
401              </tr>
402              <tr>
403                <td>Channel 2 background median</td>
404                <td>\B532 Median\</td>
405              </tr>
406              <tr>
407                <td>Channel 2 background mean</td>
408                <td>\B532 Mean\</td>
409              </tr>
410              <tr>
411                <td>Channel 2 background standard deviation</td>
412                <td>\B532 SD\</td>
413              </tr>
414              <tr>
415                <td>Percent pixels within 1 standard deviation</td>
416                <td>\% > B532+1SD\</td>
417              </tr>
418              <tr>
419                <td>Percent pixels within 2 standard deviations</td>
420                <td>\% > B532+2SD\</td>
421              </tr>
422              <tr>
423                <td>Percent saturated pixels</td>
424                <td>\F532 % Sat.\</td>
425              </tr>
426              <tr>
427                <td>Foreground pixels</td>
428                <td>\F Pixels\</td>
429              </tr>
430              <tr>
431                <td>Background pixels</td>
432                <td>\B Pixels\</td>
433              </tr>
434              <tr>
435                <td>Flags</td>
436                <td>\Flags\</td>
437              </tr>
438            </table>
439            <br> Finalize with clicking 'Next'. You can of course fill
440            the other entries as well. </p>
441          </li>
442
443          <li>
444            <p> (Affymetrix only) <b>Install
445            <a name=RMAExpressInstall
446            href=http://baseplugins.thep.lu.se/wiki/thep.lu.se.RMAExpress>RMAExpress
447            plug-in for BASE</a></b> <br> This plug-in is required for
448            Affymetrix data. The plug-in will create a bioassay set,
449            i.e., to be able to analyse the data in BASE.</p>
450          </li>
451
452          <li>
453            <p> <b>Upload files</b> <br> Before import you can upload
454            files to the server, or if preferred, files to be imported
455            can be uploaded at import time. To upload files, choose
456            'View' -> 'Files' and click in the 'Upload file...'
457            button. At upload time you assign a type to the file (can
458            be changed later if needed), and batch upload of files is
459            possible in a zip-file or tar archive. </p>
460
461            <p> As administrator you need to upload the reporter map
462            (array design) files and corresponding reporter files. For
463            Affymetrix this translates to Affydesign.cdf files and
464            Affydesign_annot.csv files. </p>
465          </li>
466
467          <li>
468            <p> <b> Reporter import </b> <br> Choose 'View' ->
469            'Reporters' and click on the 'Import...' tab. Click 'Next'
470            in the pop-up without changing anything. Select the file
471            with reporter information and click 'Next'. In the panel
472            you can choose to update reporter information for already
473            stored reporters. Click 'Next'. Set the job name and click
474            'Finish' to start the import. A progress report will be
475            displayed. It is safe to close this page, the job
476            will finish anyway. </p>
477
478            <p>In some cases the reporter annotation file from
479            Affymetrix fails to describe all probe sets on the chip,
480            you may get a message like <i>Error: Unable to import root
481            bioassay. Item not found:
482            Reporter[externalId=AFFX-2315060]</i>. In this case you
483            have to fall back to importing the probe set information
484            using the CDF file, simply do</p>
485
486            <p>Import the reporters by choosing 'View' -> 'Reporters'
487            and the clicking on 'Import...'. Click 'Next' without
488            changing the 'auto detect' settings. Supply the CDF file
489            name in the next dialog, click 'Next'. Start the import by
490            clicking 'Next' in the parameter dialog. This will add the
491            missing probe sets without changing existing probe
492            sets. The new probe sets will not have any annotations
493            associated with them since the CDFs do not contain such
494            information.</p>
495          </li>
496
497          <li>
498            <p> <b> Import reporter maps </b> <br> Performing an
499            import of array designs is only needed once for every
500            design added into BASE. Remember to share your designs
501            (normally to group 'Everyone'). </p>
502
503            <p> To create a new design, choose 'Array LIMS' -> 'Array
504            designs' and click on the 'New...' tab. Select a name for
505            the design. If it is an Affymetrix design, mark the 'Affy
506            chip' box and select a 'CDF file' (make sure that also the
507            CDF file is shared). Hint: For Affymetrix design you
508            should choose the name to be the same as the cdf file
509            name. If you are importing something else than Affymetrix
510            designs make sure that you unmark the 'Affy chip'
511            box. Finalize with 'Save'. For Affymetrix the import is
512            done, whereas Genepix have to perform reporter map
513            import. </p>
514
515            <p> <i>Genepix reporter map import</i> <br> Click on the
516            newly created array design, and click on the 'Import...'
517            tab. In the pop up, click 'Next'. Browse for the reporter
518            map file and click 'Next'. In the following dialogue you
519            can specify how to treat errors encountered. The default
520            is 'fail' which may be too restrictive, trial and error is
521            the way to go here for now. If you have trouble importing
522            try 'skip' for 'Default error handling' and 'Reporter not
523            found'. You can safely leave the 'Character set' as it
524            is. </p>
525          </li>
526
527        </ol>
528      </li>
529
530      <li>
531        <a name="user"></a>
532        <h2>User tasks</h2>
533      </li>
534
535      <p> A normal user is not allowed to add array design, reporter
536      information, and a lot of other information to BASE. The reason
537      for this is that a lot of information should only exist as one
538      copy in the database. For example, reporters should only exist in
539      one copy because everyone uses the same reporters. There is no
540      need to store several copies of the same array design. </p>
541
542      <p> A user will normally upload experimental data to BASE for
543      import into the database. To be able to import the data, the
544      array design used must be available in BASE at import time. If
545      the array design is not available, a user with the proper
546      credential must add the array design to BASE. </p>
547
548      <ol type=a>
549
550      <li>
551        <p> <b> Create a new Project </b> <br> Go to 'View' ->
552        'Projects' and click on the 'New...' tab. Name the project and
553        save. In the projects listing page, click 'Set active' for the
554        new project. The selected project should be displayed on top
555        right as 'Active project'. Selecting an active project will
556        influence the behaviour of BASE. Only information related to
557        the active project will be displayed and items created will
558        automatically be shared to the active project. </p>
559
560        <p> The display of items shared to the active project only
561        requires that the 'view/presets' pull-down menu options are
562        properly set. In 'view/preset' you can select what should be
563        displayed, and if only 'In current project' is selected then
564        only information shared to a project will be shown. </p>
565      </li>
566
567      <li>
568        <p> <b>Create raw bioassays</b> <br> Upload your raw data
569        files. Go to 'View' -> 'Raw bioassays' and click on the
570        'New...' tab. Name the raw bioassay. Select 'Raw data
571        type'. Select the 'Array design', if you cannot see see
572        designs in the pop-up the make sure that the 'view/presets'
573        pull-down menu has 'Shared to me' marked and select appropriate
574        design. Select 'CEL file' if you create an Affymetrix raw
575        bioassay. You can leave the rest untouched. Redo for all raw
576        data files. (Yes a batch creator would be nice.) </p>
577      </li>
578
579      <li>
580        <p> <b>Create a new experiment</b> <br> Go to 'View' ->
581        'Experiments' and click on the 'New...' tab. Name the
582        experiment. Click 'Add raw bioassays...' button and mark the
583        raw bioassays to add to the experiment and click
584        'Ok'. Finalize with clicking the 'Save' button. </p>
585      </li>
586
587      <li>
588        <p> <b>Analysing an experiment step I</b> <br> Select the
589        newly created experiment and in the the experiment window
590        select the 'Bioassay sets' tab. There are no bioassay sets and
591        you must create a root bioassay set. This step is different
592        depending on what data is used in the experiment but note that
593        this paragraph ends with information valid for all type of
594        data. </p>
595 
596        <p> <i>Affymetrix</i> <br> Click on the 'New root bioassay set
597        ...' tab and select the RMAExpress plug-in in the pop up. (If
598        the plug-in does not appear as an option, the installation of
599        the plug-in has failed. Please refer
600        to <a href=#RMAExpressInstall>Installing RMAExpress plug-in
601        for BASE</a>.) Click on the 'Next' button and in the new
602        window set the name for the bioassay set and select the
603        bioassays you want to include for this analysis. Click
604        'Next'. In the next pop up you can change information if you
605        like but it is not necessary, when done click on 'Finish' to
606        add the analysis job to the job queue. The job will start
607        automatically when the server as an open slot for it. The last
608        pop up window will report progress on the job. </p>
609
610        <p> <i>All flavours</i> <br> You can safely close the job
611        progress window, the server will run the job anyway. If you
612        want to monitor the progress of the job after closing the job
613        window just go to 'View' -> 'Jobs' and locate your job in the
614        list and select it. When the job is done the new bioassay set
615        will be added to the list of bioassay set for the
616        experiment. Unfortunately the list does not auto update so you
617        need to click on the 'Properties' tab and the on the 'Bioassay
618        sets' tab to refresh the list of bioassay sets. </p>
619      </li>
620
621      <li>
622        <p> <b>Analysing an experiment step II</b> <br> Now you should
623        have the first bioassay set. In the list of bioassay sets you
624        will have a number of icons attached that will start
625        tools. The set of tools available for bioassay sets is context
626        sensitive, <i>i.e.</i>, only tools that can handle the
627        bioassay sets are shown. At the time of writing of this
628        document there are four icons available; A simple plot tool,
629        experiment explorer, a filtering tool, and a plug-in
630        runner. You have to try these on your own. The aim with this
631        paragraph is to highlight the fact that you can export the
632        bioassay set data for use outside BASE. </p>
633
634        <p> To export bioassay set data select a bioassay set. In the
635        bioassay set presentation window you will have an export
636        button just below the tabs on the top. (There is also an
637        export button for the Sub analysis tree which may be confusing
638        at first, but his button will export information about the
639        analysis tree.) So, assuming you select the proper export
640        button you will be given a list of different export
641        formats. The list of supported exports depends on what plug-ins
642        are added to the server, but there should at least be an
643        export to <a href=http://www.tm4.org/mev.html>MultiExperiment
644        Viewer</a> maintained by the Dana Farber Cancer Institute. </p>
645      </li>
646
647      </ol>
648
649    </ol>
650
651    <p> This concludes this short document on how to get going with
652    BASE. We have not covered how to use the LIMS part of BASE, nor
653    annotations, and much more. We are creating documentation, please
654    browse <a href=http://base.thep.lu.se/>BASE web site</a> for the
655    latest available documents. </p>
656
657  </body>
658</html>
Note: See TracBrowser for help on using the repository browser.