source: trunk/doc/historical/user/getting_started.html @ 7982

Last change on this file since 7982 was 7982, checked in by Nicklas Nordborg, 22 months ago

Merge BASE 3.18.2 to the trunk

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