source: trunk/doc/src/docbook/faq/faqs.xml @ 6807

Last change on this file since 6807 was 5820, checked in by Nicklas Nordborg, 11 years ago

References #1590: Documentation cleanup

Last part of the "Write documentation" chapter and FAQ and Apecix sections.

File size: 18.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE part PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: faqs.xml 3246 2007-04-16 14:12:23Z martin $
7 
8  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Philippe Rocca-Serra, Martin Svensson
9  Copyright (C) 2008 Jari Häkkinen, Nicklas Nordborg
10 
11  This file is part of BASE - BioArray Software Environment.
12  Available at http://base.thep.lu.se/
13 
14  BASE is free software; you can redistribute it and/or
15  modify it under the terms of the GNU General Public License
16  as published by the Free Software Foundation; either version 3
17  of the License, or (at your option) any later version.
18 
19  BASE is distributed in the hope that it will be useful,
20  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
22  GNU General Public License for more details.
23 
24  You should have received a copy of the GNU General Public License
25  along with BASE. If not, see <http://www.gnu.org/licenses/>.
26-->
27
28<part id="faqsdoc">
29  <?dbhtml dir="faq" filename="index.html" ?>
30  <title>FAQ</title>
31
32  <chapter id="faqs" chunked="0">
33    <?dbhtml filename="faq.html" ?>
34    <title>Frequently Asked Questions with answers</title>
35
36    <para>
37      This chapter presents a list of solutions to common problems and
38      tasks in BASE. The information is is collected from the mailing
39      lists, private communication, and from issues frequently
40      encountered in BASE introduction courses. If you have BASE
41      solutions that should be added to this chapter please contact us
42      through the usual communication channels, see
43      <xref linkend="resources" /> for contact information.
44    </para>
45
46    <sect1 id="faqs.reporter">
47      <title>Reporter related questions with answers</title>
48      <qandaset defaultlabel='qanda'>
49        <?dbhtml cellspacing="0px" cellpadding="0px" ?>
50
51        <qandaentry>
52          <question>
53            <simpara>
54              My favourite database is not used for annotating reporters. Can I add
55              my database to BASE and if so, how should it proceed?
56            </simpara>
57          </question>
58          <answer>
59            <simpara>
60              Yes, you can add resources to annotate reporters. You will need to
61              upgrade BASE and you may have to contact your system administrator for
62              doing so.
63            </simpara>
64
65            <simpara>
66              In order to change, remove or add annotation fields attached to
67              reporters, you will need modify the <filename>extended-properties.xml</filename>
68              file and run a BASE update. Please refer to section
69              <xref linkend="installation.main" />
70              for information about both processes. Once done with the upgrade, you'll
71              have to define a new reporter import plug-in. Instructions can be found
72              in <xref linkend="plugins" />.
73            </simpara>
74          </answer>
75        </qandaentry>
76
77        <qandaentry>
78          <question>
79            <simpara>
80              I have made a mistake while loading my reporters. How can I delete them
81              all in one go ?
82            </simpara>
83          </question>
84          <answer>
85            <simpara>
86              The reporter import plug-in can be executed in <emphasis>delete</emphasis>
87              mode. Run the plug-in again and select the same file you used for the import.
88              Select the <guilabel>Mode=delete</guilabel> option.
89              In the <guilabel>Error handling</guilabel> section select the
90              <guilabel>Reporter is used=skip</guilabel> option. This will delete all
91              reporters that was created in the previous import.
92            </simpara>
93          </answer>
94        </qandaentry>
95
96        <qandaentry>
97          <question>
98            <simpara>
99              I get a message "Error: Unable to import root
100              bioassay. Item not found:
101              Reporter[externalId=AFFX-2315060]" when I try to create
102              a root bioassayset.
103            </simpara>
104          </question>
105          <answer>
106            <simpara>
107              BASE requires all reporters (probesets in Affymetrix
108              speak) to be stored in the database before they can be
109              used. The reporter information is typically imported
110              from a reporter annotation file but in some cases the
111              reporter annotation file supplied by Affymetrix fails to
112              describe all reporters (probesets) on a chip. BASE will
113              refuse to store data related to such chips until the
114              missing reporters are added to the database. Hence the
115              rejection of the new root bioassayset.
116            </simpara>
117
118            <simpara>
119              The resolution is straightforward, simply import the
120              probeset information from the CDF file associated with
121              the array design. The catch is that normal BASE user
122              credential is not enough to perform the import therefore
123              someone with proper credential (the BASE server
124              administrator is one of them) must perform the
125              import. Follow the instructions at
126              <xref linkend="reporters.import" /> to import
127              reporters. Make sure to select plug-in option to ignore
128              already existing reporters when starting the import
129              otherwise the existing reporter annotations will be
130              changed. The goal here is to add missing reporters to
131              allow BASE work with your data. The CDF file does not
132              contain any annotation information and cannot be used to
133              annotate reporters.
134            </simpara>
135          </answer>
136        </qandaentry>
137
138      </qandaset>
139    </sect1>
140
141    <sect1 id="faqs.arraydesign">
142      <title>Array design related questions with answers</title>
143      <qandaset defaultlabel='qanda'>
144        <?dbhtml cellspacing="0px" cellpadding="0px" ?>
145        <qandaentry>
146          <question>
147            <para>
148              What it the best way to create an array design in BASE when starting
149              from a GAL file?
150            </para>
151          </question>
152          <answer>
153            <para>
154              This requires some work but here is the
155              procedure to remember:
156            </para>
157            <para>
158              A gal file tells where <guilabel>Reporters</guilabel>
159              have been spotted on an array. So a GAL file can be used to do 2 things
160            </para>
161            <orderedlist>
162              <listitem>
163                <para>
164                  Define the features of an array design for a non-Affymetrix platform
165                  using the <guilabel>Reporter Map importer plug-in</guilabel>.
166                </para>
167                <para>
168                  To do so, after having created an new array design, go to the
169                  single-item view by of the newly created array design.
170                  Click on the &gbImport;
171                  the button. If you do not see it, it means that you have not
172                  enough privileges (contact the administrator).
173                </para>
174                <para>
175                  This starts the plug-in configuration wizard. Select
176                  the <guilabel>auto detect</guilabel> option and in the
177                  next step your GAL file.
178                </para>
179                <para>
180                  Now, there is the risk that no file format has been defined
181                  for GAL files. This must be done by an administrator or other user
182                  with proper privileges. See <xref linkend="plugins.configuration" /> 
183                  for information about this.
184                </para>
185                <para>
186                  Once done (and if everything went fine), you can see from the
187                  Array Design list view that the
188                  <guilabel>Has features</guilabel>
189                  entry has been modified and is set to 'Yes (n)' where n
190                  indicates the number of spots (features) for this array.
191                </para>
192                <note>
193                  <para>
194                    Features can also be loaded from a Genepix GPR file
195                    with the same procedure.
196                  </para>
197                </note>
198              </listitem>
199              <listitem>
200                <para>
201                  Define the
202                  <guilabel>Reporters</guilabel>
203                  present on the array design using the
204                  <guilabel>Reporter importer plug-in</guilabel>.
205                </para>
206                <para>
207                  To do so, Go to
208                  <menuchoice>
209                    <guimenu>View</guimenu>
210                    <guimenuitem>Reporters</guimenuitem>
211                  </menuchoice>
212                  and click on
213                  &gbImport;. This starts a
214                  <guilabel>Reporter Importer plug-in</guilabel>
215                </para>
216                <para>
217                  More information about importing Reporters can be found in
218                  <xref linkend="reporters" />
219                </para>
220              </listitem>
221            </orderedlist>
222          </answer>
223        </qandaentry>
224
225        <qandaentry>
226          <question>
227            <para>
228              I am confused. What is the difference between
229              <guilabel>Reporter map importer</guilabel>,
230              <guilabel>Print map importer</guilabel> and
231              <guilabel>Reporter importer</guilabel>?
232            </para>
233          </question>
234          <answer>
235            <para>
236              The reporter map and print map importer are used to
237              import features to an array design.
238              The latter one must be used when your array design is connected to PCR
239              plates and supports two file formats: Biorobotics TAM
240              and Molecularware MWBR. See
241              <ulink url="http://www.flychip.org.uk/protocols/robotic_spotting/fileformats.php"
242                >http://www.flychip.org.uk/protocols/robotic_spotting/fileformats.php</ulink>
243              for more information about those file formats.
244              If you are only using commercial platforms or if you do not use plates in the array LIMS, you
245              have no need for the print map importer and should use the reporter
246              map importer instead.
247            </para>
248
249            <para>
250              The reporter importer is used to load reporter annotations into BASE.
251            </para>
252          </answer>
253        </qandaentry>
254      </qandaset>
255    </sect1>
256
257    <sect1 id="faqs.biomaterial">
258      <title>Biomaterial, Protocol, Hardware, Software related questions with answers</title>
259      <qandaset defaultlabel='qanda'>
260        <?dbhtml cellspacing="0px" cellpadding="0px" ?>
261        <qandaentry>
262          <question>
263            <para>
264              I have just created a new item but I can not see
265              it. Am I doing something wrong?
266            </para>
267          </question>
268          <answer>
269            <para>
270              Try clearing the filter. To do so: use the
271              <guilabel>view / presets</guilabel>
272              dropdown and select the
273              <guilabel>clear filter</guilabel>
274              entry. This will remove all characters in the search boxes and all
275              preselection of item in the drop down lists. If this does not solve your
276              problem, then check if the <guilabel>view / presets</guilabel>
277              has the <guilabel>owned by me</guilabel> entry selected.
278            </para>
279          </answer>
280        </qandaentry>
281
282        <qandaentry>
283          <question>
284            <para>
285              I can only see XX columns in the list view but I know I have
286              a lot more information. Is there a way I can customise the column
287              display?
288            </para>
289          </question>
290          <answer>
291            <para>
292              Yes, you can display many more columns. See <xref 
293              linkend="webclient.itemlist.columns" />.
294            </para>
295          </answer>
296        </qandaentry>
297
298        <qandaentry>
299          <question>
300            <para>
301              Is it possible to sort the values in a column in the list view?
302            </para>
303          </question>
304          <answer>
305            <para>
306              Of course it is. See <xref linkend="webclient.itemlist.order" />.
307            </para>
308          </answer>
309        </qandaentry>
310
311        <qandaentry>
312          <question>
313            <para>
314              Is it possible to sort the annotation types from
315              <guilabel>Annotation &amp; parameters</guilabel> tab in the
316              single-item view?
317            </para>
318          </question>
319          <answer>
320            <para>
321            No. This is not possible at the moment. The annotations are always sorted
322            by the name of the annotation type.
323            </para>
324          </answer>
325        </qandaentry>
326
327        <qandaentry>
328          <question>
329            <para>
330              I have to create pools of samples in my experiment due to scarcity of
331              the biological material. Can I represent those pooled samples is BASE?
332            </para>
333          </question>
334          <answer>
335            <para>
336              Yes, you can. From the sample list select a number of samples
337              by marking their checkboxes. Then click on the <guibutton>Pool</guibutton>
338              button. For more information see
339              <xref linkend="biomaterial.samples.create" />.
340              Pooling can also be applied to extracts.
341            </para>
342          </answer>
343        </qandaentry>
344        <qandaentry>
345          <question>
346            <para>
347              I need to create a new item subtype but the
348              &gbNew;
349              button is grey and does not work. Why?
350            </para>
351          </question>
352          <answer>
353            <para>
354              Your privileges are not high enough and you have not been granted
355              permission to create subtypes. Contact your BASE administrator.
356              For more information about permissions, please refer to
357              <xref linkend="accounts" />.
358            </para>
359          </answer>
360        </qandaentry>
361        <qandaentry>
362          <question>
363            <para>
364              I have created an Annotation Type <userinput>Temperature</userinput>
365              and shared it to everyone but when I want to use it for annotating a
366              sample, I can not find it! How is that?
367            </para>
368          </question>
369          <answer>
370            <para>
371              The most likely explanation is that this particular annotation
372              type has been declared as a protocol parameter. This means that it will
373              only be displayed in BASE if you have used a sample creation protocol
374              which uses that parameter.
375            </para>
376          </answer>
377        </qandaentry>
378
379        <qandaentry>
380          <question>
381            <para>
382              I have carried out an experiment using both Affymetrix and Agilent
383              arrays but I can not select more than one raw data type in BASE. What
384              should I do?
385            </para>
386          </question>
387          <answer>
388            <para>
389              In this particular case and because you are using 2 different raw data
390              file formats, you will have to split your experiment in 2. One
391              experiment for those samples processed using Affymetrix platform and
392              another one using Agilent platform. You do not necessarily have to
393              provide all information about the samples again but simply create new
394              raw bioassay data which can be grouped in a new experiment.
395            </para>
396          </answer>
397        </qandaentry>
398      </qandaset>
399    </sect1>
400
401    <sect1 id="faqs.datafiles_rawdata">
402      <title>Data Files and Raw Data related questions with answers</title>
403      <qandaset defaultlabel='qanda'>
404        <?dbhtml cellspacing="0px" cellpadding="0px" ?>
405        <qandaentry>
406          <question>
407            <para>
408              It seems that BASE does not support the data files generated by my brand
409              new scanner. Is it possible to add it to BASE?
410            </para>
411          </question>
412          <answer>
413            <para>
414              Yes it is possible to extend BASE so that it can support your system.
415              You will need to define a new raw data type for BASE by modifying
416              the <filename>raw-datatypes.xml</filename> configuration file.
417            </para>
418            <para>
419              Then, you will have to run the <filename>updatedb.sh</filename>
420              to make the new raw data type available to the system. See
421              <xref linkend="installation.upgrade" />.
422            </para>
423            <para>
424              Finally, you will have to configure a raw data import plug-in in order to
425              be able to create rawbioassays. See
426              <xref linkend="plugins.configuration" />
427              and
428              <xref linkend="experiments_analysis.rawbioassay.rawdata" />
429              for further information.
430            </para>
431          </answer>
432        </qandaentry>
433
434        <qandaentry>
435          <question>
436            <para>Are Affymetrix CDT and CAB files supported by BASE?</para>
437          </question>
438          <answer>
439            <para>
440              There is no support for CDT or CAB. Currently only CDF and CEL files are
441              supported by the Affymetrix plug-ins. Annotation files (.csv) are used
442              for uploading probeset (reporter in BASE language) information. The
443              issue of supporting CDT and CAB files is an import and a plug-in issue.
444              There are two ways to solve this:
445              <orderedlist>
446              <listitem>
447                <para>
448                Write code that treats the files in a proper way and submit
449                the solution to the developer team (preferred route).
450                </para>
451              </listitem>
452              <listitem>
453                <para>
454                Submit a ticket through
455                <ulink url="http://base.thep.lu.se">http://base.thep.lu.se</ulink>
456                explaining what you'd like to see with respect to to CDT and CAB files.
457                </para>
458              </listitem>
459              </orderedlist>
460             
461              <note>
462                <para>
463                To include CDT and CAB support to BASE, the file formats must be
464                open, that is we must be able to read them without proprietary
465                non-distributable code.
466                </para>
467              </note>
468            </para>
469          </answer>
470        </qandaentry>
471
472        <qandaentry>
473          <question>
474            <para>Are Illumina data files supported by BASE?</para>
475          </question>
476          <answer>
477            <para>
478              Yes, but not by default. There is
479              an <ulink url="http://baseplugins.thep.lu.se/wiki/net.sf.basedb.illumina">Illumina
480              package</ulink> that provides Illumina support to
481              BASE. The package is straightforward to install, visit
482              the package site for more information.
483            </para>
484          </answer>
485        </qandaentry>
486
487      </qandaset>
488
489    </sect1>
490
491
492    <sect1 id="faqs.analysis">
493      <title>Analysis related questions with answers</title>
494      <qandaset defaultlabel='qanda'>
495        <?dbhtml cellspacing="0px" cellpadding="0px" ?>
496        <qandaentry>
497          <question>
498            <para>
499              Is it possible to use the formula filter to filter for
500              <constant>null</constant> 
501              values (or non-<constant>null</constant> values)?
502            </para>
503          </question>
504          <answer>
505            <para>
506              Yes, use an expression like:
507              <userinput>ch(0) != null</userinput>. This will match
508              all values, except <constant>null</constant> values.
509            </para>
510          </answer>
511        </qandaentry>
512
513        <qandaentry>
514          <question>
515            <para>
516              OK, I have uploaded 40 CEL files in BASE but are there any tool to
517              perform normalisation on Affymetrix raw data?
518            </para>
519          </question>
520          <answer>
521            <para>
522              Yes, there is. BASE team has created a plug-in based on
523              <ulink url="http://rmaexpress.bmbolstad.com/">
524              RMAExpress methods from Bolstad and Irizarry</ulink> so you can normalise
525              Affymetrix data sets of reasonable size (not 1000 CEL files at a time
526              though even though this might depend on your set-up...)
527              The plug-in is not included in a standard BASE installation, but
528              can be downloaded from the <ulink url="http://baseplugins.thep.lu.se/wiki/se.lu.thep.affymetrix"
529                >BASE plug-ins web site</ulink>.
530            </para>
531          </answer>
532        </qandaentry>
533
534        <qandaentry>
535          <question>
536            <para>
537              I am trying to import raw bioassays using the import
538              button in the experiment properties view but BASE claims
539              that <emphasis>Could not find any plugins that you have
540              permission to use</emphasis>. I know there are import
541              plug-ins available to me since I have successfully
542              imported data before, why does the import fail?
543            </para>
544          </question>
545          <answer>
546            <para>
547              All raw bioassays in the experiment are already
548              imported. In this case the BASE server cannot detect
549              anything to import and returns the somewhat confusing
550              message. Simply add the non-imported raw bioassays to
551              the experiment and try again.
552            </para>
553          </answer>
554        </qandaentry>
555      </qandaset>
556    </sect1>
557
558  </chapter>
559
560</part>
Note: See TracBrowser for help on using the repository browser.