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

Last change on this file since 4477 was 4477, checked in by Jari Häkkinen, 14 years ago

Addresses #1106. Moving to GPLv3 in chunked commits.

File size: 25.6 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 Hakkinen, 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 this program; if not, write to the Free Software
26  Foundation, Inc., 59 Temple Place - Suite 330,
27  Boston, MA  02111-1307, USA.
28-->
29
30<part id="faqsdoc">
31  <?dbhtml dir="faqsdoc"?>
32  <title>FAQ</title>
33
34  <chapter id="faqs" chunked="0">
35    <?dbhtml dir="faqs"?>
36    <title>Frequently Asked Questions with answers</title>
37
38    <para>
39      This chapter presents a list of solutions to common problems and
40      tasks in BASE. The information is is collected from the mailing
41      lists, private communication, and from issues frequently
42      encountered in BASE introduction courses. If you have BASE
43      solutions that should be added to this chapter please contact us
44      through the usual communication channels, see
45      <xref linkend="resources" /> for contact information.
46    </para>
47
48    <sect1 id="faqs.reporter">
49      <title>Reporter related questions with answers</title>
50      <qandaset defaultlabel='qanda'>
51        <?dbhtml cellspacing="0px" cellpadding="0px" ?>
52
53        <qandaentry>
54          <question>
55            <simpara>
56              My favourite database is not used for annotating reporters. Can I add
57              my database to BASE and if so, how should it proceed?
58            </simpara>
59          </question>
60          <answer>
61            <simpara>
62              Yes, you can add resources to annotate reporters. You will need to
63              upgrade BASE and you may have to contact your system administrator for
64              doing so.
65            </simpara>
66
67            <simpara>
68              In order to change, remove or add annotation fields attached to
69              reporters, you will need modify the <filename>extended-properties.xml</filename>
70              file and run a BASE update. Please refer to section
71              <xref linkend="installation_upgrade.installation" />
72              for information about both processes. Once done with the upgrade, you'll
73              have to define a new reporter import plug-in. Instructions can be found
74              in <xref linkend="plugins" />.
75            </simpara>
76          </answer>
77        </qandaentry>
78
79        <qandaentry>
80          <question>
81            <simpara>
82              I have made a mistake while loading my reporters. How can I delete them
83              all in one go ?
84            </simpara>
85          </question>
86          <answer>
87            <simpara>
88              The reporter import plug-in can be executed in <emphasis>delete</emphasis>
89              mode. Run the plug-in again and select the same file you just for the import.
90              Select the <guilabel>Mode=delete</guilabel> option.
91              In the <guilabel>Error handling</guilabel> section select the
92              <guilabel>Reporter is used=skip</guilabel> option. This will delete all
93              reporters that was created in the previous import.
94            </simpara>
95          </answer>
96        </qandaentry>
97
98        <qandaentry>
99          <question>
100            <simpara>
101              I get a message "Error: Unable to import root
102              bioassay. Item not found:
103              Reporter[externalId=AFFX-2315060]" when i try to create
104              a root bioassayset.
105            </simpara>
106          </question>
107          <answer>
108            <simpara>
109              BASE requires all reporters (probesets in Affymetrix
110              speak) to be stored in the database before they can be
111              used. The reporter information is typically imported
112              from a reporter annotation file but in some cases the
113              reporter annotation file supplied by Affymetrix fails to
114              describe all reporters (probesets) on a chip. BASE will
115              refuse to store data related to such chips until the
116              missing reporters are added to the database. Hence the
117              rejection of the new root bioassayset.
118            </simpara>
119
120            <simpara>
121              The resolution is straightforward, simply import the
122              probeset information from the CDF file associated with
123              the array design. The catch is that normal BASE user
124              credential is not enough to perform the import therefore
125              someone with proper credential (the BASE server
126              administrator is one of them) must perform the
127              import. Follow the instructions at
128              <xref linkend="reporters.import" /> to import
129              reporters. Make sure to select plug-in option to ignore
130              already existing reporters when starting the import
131              otherwise the existing reporter annotations will be
132              changed. The goal here is to add missing reporters to
133              allow BASE work with your data. The CDF file does not
134              contain any annotation information and cannot be used to
135              annotate reporters.
136            </simpara>
137          </answer>
138        </qandaentry>
139
140      </qandaset>
141    </sect1>
142
143    <sect1 id="faqs.arraydesign">
144      <title>Array design related questions with answers</title>
145      <qandaset defaultlabel='qanda'>
146        <?dbhtml cellspacing="0px" cellpadding="0px" ?>
147        <qandaentry>
148          <question>
149            <para>
150              What it the best way to create an array design in BASE2 when starting
151              from a GAL file?
152            </para>
153          </question>
154          <answer>
155            <para>
156              This requires some work but here is the
157              procedure to remember:
158            </para>
159            <para>
160              A gal file tells where <guilabel>Reporters</guilabel>
161              have been spotted on an array. So a GAL file can be used to do 2 things
162            </para>
163            <orderedlist>
164              <listitem>
165                <para>
166                  Define the features of an array design for a non-Affymetrix platform
167                  using the <guilabel>Reporter Map importer plug-in</guilabel>.
168                </para>
169                <para>
170                  To do so, after having created an new array design, go to the
171                  single-item view by of the newly created array design.
172                  Click on the &gbImport;
173                  the button. If you do not see it, it means that you have not
174                  enough privileges (contact the administrator).
175                </para>
176                <para>
177                  This starts the plug-in configuration wizard. Select
178                  the <guilabel>auto detect</guilabel> option and in the
179                  next step your GAL file.
180                </para>
181                <para>
182                  Now, there is the risk that no file format has been defined
183                  for GAL files. This must be done by an administrator or other user
184                  with proper privileges. See <xref linkend="plugins.configuration" /> 
185                  for information about this.
186                </para>
187                <para>
188                  Once done (and if everything went fine), you can see from the
189                  Array Design list view that the
190                  <guilabel>Has features</guilabel>
191                  entry has been modified and is set to 'Yes (n)' where n
192                  indicates the number of spots (features) for this array.
193                </para>
194                <note>
195                  <para>
196                    Features can also be loaded from a Genepix GPR file
197                    with the same procedure.
198                  </para>
199                </note>
200              </listitem>
201              <listitem>
202                <para>
203                  Define the
204                  <guilabel>Reporters</guilabel>
205                  present on the array design using the
206                  <guilabel>Reporter importer plug-in</guilabel>.
207                </para>
208                <para>
209                  To do so, Go to
210                  <menuchoice>
211                    <guimenu>View</guimenu>
212                    <guimenuitem>Reporters</guimenuitem>
213                  </menuchoice>
214                  and click on
215                  &gbImport;. This starts a
216                  <guilabel>Reporter Importer plug-in</guilabel>
217                </para>
218                <para>
219                  More information about importing Reporters can be found in
220                  <xref linkend="reporters" />
221                </para>
222              </listitem>
223            </orderedlist>
224          </answer>
225        </qandaentry>
226
227        <qandaentry>
228          <question>
229            <para>
230              I am confused. What is the difference between
231              <guilabel>Reporter map importer</guilabel>,
232              <guilabel>Print map importer</guilabel> and
233              <guilabel>Reporter importer</guilabel>?
234            </para>
235          </question>
236          <answer>
237            <para>
238              The reporter map and print map importer are used to
239              import features to an array design.
240              The latter one must be used when your array design is connected to PCR
241              plates and supports two file formats: Biorobotics TAM
242              and Molecularware MWBR. See
243              <ulink url="http://www.flychip.org.uk/protocols/robotic_spotting/fileformats.php"
244                >http://www.flychip.org.uk/protocols/robotic_spotting/fileformats.php</ulink>
245              for more information about those file formats.
246              If you are only using commercial platforms or if you do not use plates in the array LIMS, you
247              have no need for the print map importer and should use the reporter
248              map importer instead.
249            </para>
250
251            <para>
252              The reporter importer is used to load reporter annotations into BASE.
253            </para>
254          </answer>
255        </qandaentry>
256      </qandaset>
257    </sect1>
258
259    <sect1 id="faqs.biomaterial">
260      <title>Biomaterial, Protocol, Hardware, Software related questions with answers</title>
261      <qandaset defaultlabel='qanda'>
262        <?dbhtml cellspacing="0px" cellpadding="0px" ?>
263        <qandaentry>
264          <question>
265            <para>
266              I have just created a new item but I can not see
267              it. Am I doing something wrong?
268            </para>
269          </question>
270          <answer>
271            <para>
272              Try clearing the filter. To do so: use the
273              <guilabel>view / presets</guilabel>
274              dropdown and select the
275              <guilabel>clear filter</guilabel>
276              entry. This will remove all characters in the search boxes and all
277              preselection of item in the drop down lists. If this does not solve your
278              problem, then check if the <guilabel>view / presets</guilabel>
279              has the <guilabel>owned by me</guilabel> entry selected.
280            </para>
281          </answer>
282        </qandaentry>
283
284        <qandaentry>
285          <question>
286            <para>
287              I can only see XX columns in the list view but I know I have
288              a lot more information. Is there a way I can customise the column
289              display?
290            </para>
291          </question>
292          <answer>
293            <para>
294              Yes, you can display many more columns. See <xref 
295              linkend="webclient.itemlist.columns" />.
296            </para>
297          </answer>
298        </qandaentry>
299
300        <qandaentry>
301          <question>
302            <para>
303              Is it possible to sort the values in a column in the list view?
304            </para>
305          </question>
306          <answer>
307            <para>
308              Of course it is. See <xref linkend="webclient.itemlist.order" />.
309            </para>
310          </answer>
311        </qandaentry>
312
313        <qandaentry>
314          <question>
315            <para>
316              Is it possible to sort the annotation types from
317              <guilabel>Annotation &amp; parameters</guilabel> tab in the
318              single-item view?
319            </para>
320          </question>
321          <answer>
322            <para>
323            No. This is not possible at the moment. The annotations are always sorted
324            by the name of the annotation type.
325            </para>
326          </answer>
327        </qandaentry>
328
329        <qandaentry>
330          <question>
331            <para>
332              I have to create pools of samples in my experiment due to scarcity of
333              the biological material. Can I represent those pooled samples is BASE2?
334            </para>
335          </question>
336          <answer>
337            <para>
338              Yes, you can. From the sample list select a number of samples
339              by marking their checkboxes. Then click on the <guibutton>Pool</guibutton>
340              button. For more information see
341              <xref linkend="biomaterials.samples.create" />.
342              Pooling can also be applied to extracts and labeled extracts.
343            </para>
344          </answer>
345        </qandaentry>
346        <qandaentry>
347          <question>
348            <para>
349              I would like to add a software type in BASE2 but there is no button for
350              doing so. Is it possible?
351            </para>
352          </question>
353          <answer>
354            <para>
355              No, this is not possible, since there is only one place
356              software is used, namely to register the feature extraction
357              of a scanned image.
358            </para>
359          </answer>
360        </qandaentry>
361
362        <qandaentry>
363          <question>
364            <para>
365              I need to create a new hardware type but the
366              &gbNew;
367              button is grey and does not work. Why?
368            </para>
369          </question>
370          <answer>
371            <para>
372              Your privileges are not high enough and you have not been granted
373              permission to create hardware types. Contact your BASE2 administrator.
374              For more information about permissions, please refer to
375              <xref linkend="user_administration" />.
376            </para>
377          </answer>
378        </qandaentry>
379        <qandaentry>
380          <question>
381            <para>
382              I have created an Annotation Type <userinput>Temperature</userinput>
383              and shared it to everyone but when I want to use it for annotating a
384              sample, I can not find it! How is that?
385            </para>
386          </question>
387          <answer>
388            <para>
389              The most likely explanation is that this particular annotation
390              type has been declared as a protocol parameter. This means that it will
391              only be displayed in BASE2 if you have used a sample creation protocol
392              which uses that parameter.
393            </para>
394          </answer>
395        </qandaentry>
396
397        <qandaentry>
398          <question>
399            <para>
400              I have carried out an experiment using both Affymetrix and Agilent
401              arrays but I can not select more than one raw data type in BASE2. What
402              should I do?
403            </para>
404          </question>
405          <answer>
406            <para>
407              In this particular case and because you are using 2 different raw data
408              file formats, you will have to split your experiment in 2. One
409              experiment for those samples processed using Affymetrix platform and
410              another one using Agilent platform. You do not necessarily have to
411              provide all information about the samples again but simply create new
412              raw bioassay data which can be grouped in a new experiment.
413            </para>
414          </answer>
415        </qandaentry>
416      </qandaset>
417    </sect1>
418
419    <sect1 id="faqs.datafiles_rawdata">
420      <title>Data Files and Raw Data related questions with answers</title>
421      <qandaset defaultlabel='qanda'>
422        <?dbhtml cellspacing="0px" cellpadding="0px" ?>
423        <qandaentry>
424          <question>
425            <para>
426              It seems that BASE2 does not support the data files generated by my brand
427              new scanner. Is it possible to add it to BASE2?
428            </para>
429          </question>
430          <answer>
431            <para>
432              Yes it is possible to extend BASE2 so that it can support your system.
433              You will need to define a new raw data type for BASE2 by modifying
434              the <filename>raw-datatypes.xml</filename> configuration file.
435            </para>
436            <para>
437              Then, you will have to run the <filename>updatedb.sh</filename>
438              to make the new raw data type available to the system. See
439              <xref linkend="installation_upgrade.upgrade" />.
440            </para>
441            <para>
442              Finally, you will have to configure a raw data import plug-in in order to
443              be able to create rawbioassays. See
444              <xref linkend="plugins.configuration" />
445              and
446              <xref linkend="experiments_analysis.rawbioassay.rawdata" />
447              for further information.
448            </para>
449          </answer>
450        </qandaentry>
451
452        <qandaentry>
453          <question>
454            <para>
455              I have created a raw bioassay which is not Affymetrix but the system does not
456              allow me to upload a data file whereas it is possible to do so if I
457              declared my rawbioassay of type Affymetrix. Why?
458            </para>
459          </question>
460          <answer>
461            <para>
462              This is normal. BASE2 deals with Affymetrix data files differently. BASE2
463              stores native Affymetrix file and does not load the value in tables as
464              it does for other platforms. See <xref linkend="experiments_analysis.rawbioassay.rawdata" />
465              for more information.
466            </para>
467          </answer>
468        </qandaentry>
469
470        <qandaentry>
471          <question>
472            <para>
473              I have created a raw bioassay using Affymetrix CEL file but the
474              interface says 'no spot'. I have really loaded the file! Why?
475            </para>
476          </question>
477          <answer>
478            <para>
479              Again, this is because of the specific treatment of
480              Affymetrix files compared to other platforms. Affymetrix data
481              is kept in the files and are not imported into the database.
482              Currently, the number of spots can only be counted when
483              data is located in the database.
484            </para>
485          </answer>
486        </qandaentry>
487
488        <qandaentry>
489          <question>
490            <para>Are Affymetrix CDT and CAB files supported by BASE2?</para>
491          </question>
492          <answer>
493            <para>
494              There is no support for CDT or CAB. Currently only CDF and CEL files are
495              supported by the Affymetrix plug-ins. Annotation files (.csv) are used
496              for uploading probeset (reporter in BASE language) information. The
497              issue of supporting CDT and CAB files is an import and a plug-in issue.
498              There are two ways to solve this:
499              <orderedlist>
500              <listitem>
501                <para>
502                Write code that treats the files in a proper way and submit
503                the solution to the developer team (preferred route).
504                </para>
505              </listitem>
506              <listitem>
507                <para>
508                Submit a ticket through
509                <ulink url="http://base.thep.lu.se">http://base.thep.lu.se</ulink>
510                explaining what you'd like to see with respect to to CDT and CAB files.
511                </para>
512              </listitem>
513              </orderedlist>
514             
515              <note>
516                <para>
517                To include CDT and CAB support to BASE, the file formats must be
518                open, that is we must be able to read them without proprietary
519                non-distributable code.
520                </para>
521              </note>
522            </para>
523          </answer>
524        </qandaentry>
525
526        <qandaentry>
527          <question>
528            <para>Are Illumina data files supported by BASE2 ?</para>
529          </question>
530          <answer>
531            <para>
532              Yes, but not by default. There is
533              an <ulink url="http://baseplugins.thep.lu.se/wiki/net.sf.basedb.illumina">Illumina
534              package</ulink> that provides Illumina support to
535              BASE. The package is straightforward to install, visit
536              the package site for more information.
537            </para>
538          </answer>
539        </qandaentry>
540
541        <qandaentry>
542          <question>
543            <para>Unzipped files never inherit file type specified
544            during upload, why?</para>
545          </question>
546          <answer>
547            <para>
548              Unfortunately this is an "unfixable" defect. The API for
549              unpacking files is a kind of plug-in interface
550              (FileUnpacker) that has been made public. The "mistake"
551              is that the API does not include any information from
552              the file upload dialog except the directory to upload to
553              (not even the file name is included). Introducing new
554              method or parameters will break the API and we prefer to
555              not do that.
556            </para>
557            <para>
558              As a workaround to this problem the extension of each
559              file is checked against the list of MIME types
560              (<menuchoice>
561                <guimenu>Administrate</guimenu>
562                <guimenuitem>Types</guimenuitem>
563                <guimenuitem>Mime Types</guimenuitem>
564              </menuchoice>).
565              If a MIME type with the same extension is found and has
566              been connected to a file type, this file type is
567              transferred to the file. This will obviously only work
568              for non-generic file
569              extensions, <emphasis>eg.</emphasis>, .gpr for GenePix
570              raw data files, .cel for Affymetrix CEL files, etc.
571            </para>
572          </answer>
573        </qandaentry>
574      </qandaset>
575
576    </sect1>
577
578    <sect1 id="faqs.data_repositories">
579      <title>Data Deposition to Public Repositories related questions with answers</title>
580      <qandaset defaultlabel='qanda'>
581        <?dbhtml cellspacing="0px" cellpadding="0px" ?>
582        <qandaentry>
583          <question>
584            <para>
585              I am asked by reviewers to deposit my microarray data in a public
586              repository. How can BASE2 help me?
587            </para>
588          </question>
589          <answer>
590            <para>
591              The BASE2 development team are working on a plug-in
592              that produces a Tab2Mage file accepted by ArrayExpress.
593              For the plug-in to work properly, a series of rules need to be
594              followed, please refer to
595              <xref linkend="experiments_analysis.magexport" />
596              for additional information.
597            </para>
598            <para>
599              More information about the Tab2Mage format can be found at
600              <ulink url="http://tab2mage.sourceforge.net"
601                >http://tab2mage.sourceforge.net</ulink>.
602              To send the submission to array express, use the ArrayExpress FTP site
603              at <ulink url="ftp://ftp.ebi.ac.uk pwd">ftp://ftp.ebi.ac.uk pwd</ulink>.
604              Log in with username and password <userinput>aexpress</userinput>.
605            </para>
606            <warning>
607              <para>
608                The current export plug-in does not support Tab2Mage normalised and
609                transformed files, so some additional work might be required to be
610                fully compliant, please refer to Tab2Mage help notes for creating
611                these final gene expression files and update the Tab2Mage files.
612              </para>
613            </warning>
614          </answer>
615        </qandaentry>
616
617        <qandaentry>
618          <question>
619            <para>
620              Repositories want me to be MIAME compliant but how do I know that?
621            </para>
622          </question>
623          <answer>
624            <itemizedlist>
625            <listitem>
626              <para>
627              Make sure to format your annotation types following the rules
628              detailed in <xref linkend="experiments_analysis.magexport" />.
629              </para>
630            </listitem>
631            <listitem>
632              <para>
633              Before exporting, it is probably a good idea to run the
634              <guilabel>Experiment Overview</guilabel>
635              detailed in
636              <xref linkend="experiments_analysis.experiment.overview" />.
637              By selecting stringent criteria from the interface, the tool will
638              detect all missing information that could be requested by
639              repositories.
640              </para>
641            </listitem>
642            <listitem>
643              <para>
644              If the experiment overview does not report any error any more,
645              you can run the Tab2Mage export plug-in suitable for ArrayExpress.
646              </para>
647            </listitem>
648            </itemizedlist>
649          </answer>
650        </qandaentry>
651
652        <qandaentry>
653          <question>
654            <para>
655              I have exported in Tab2Mage file, does it mean I am MIAME compliant?
656            </para>
657          </question>
658          <answer>
659            <para>
660              No, not necessarily! Tab2Mage exporter complies with Tab2Mage
661              specifications so you will be Tab2Mage compliant. However, MIAME
662              compliance depends very much on the kind of annotation you have
663              supplied. Please refer to the previous question for more information
664              about how to check for MIAME compliance in BASE2 using the Experiment
665              overview function.
666            </para>
667          </answer>
668        </qandaentry>
669
670        <qandaentry>
671          <question>
672            <para>
673              I have deleted the data files from BASE2 file systems since I have
674              imported them in tables. So I do not have data files to send to
675              ArrayExpress anymore.
676            </para>
677          </question>
678          <answer>
679            <para>
680              You can export the data from the tables again. Go to the
681              <guilabel>Raw data</guilabel> tab for each of the
682              raw bioassays you need to export. Use the
683              &gbExport; button to export the data. See
684              <xref linkend="import_export_data.export.table_export" />.
685              for more information.
686            </para>
687          </answer>
688        </qandaentry>
689
690        <qandaentry>
691          <question>
692            <para>
693              I have created pooled samples in BASE2. Can I export in Tab2Mage format?
694            </para>
695          </question>
696          <answer>
697            <para>
698              No, sorry, not for the moment. The
699              Tab2Mage exporter does not support pooling events. We are working on
700              adding this features in future version of the plug-in.
701            </para>
702          </answer>
703        </qandaentry>
704      </qandaset>
705    </sect1>
706
707    <sect1 id="faqs.analysis">
708      <title>Analysis related questions with answers</title>
709      <qandaset defaultlabel='qanda'>
710        <?dbhtml cellspacing="0px" cellpadding="0px" ?>
711        <qandaentry>
712          <question>
713            <para>
714              Is it possible to use the formula filter to filter for
715              <constant>null</constant> 
716              values (or non-<constant>null</constant> values)?
717            </para>
718          </question>
719          <answer>
720            <para>
721              It is possible to trick the system to filter out <constant>null</constant>
722              values but not non-<constant>null</constant> values. Use an expression like:
723              <userinput>ch(1) == 0 || ch(1) != 0</userinput>. This will match
724              all values, except <constant>null</constant> values.
725            </para>
726          </answer>
727        </qandaentry>
728
729        <qandaentry>
730          <question>
731            <para>
732              OK, I have uploaded 40 CEL files in BASE2 but are there any tool to
733              perform normalisation on Affymetrix raw data?
734            </para>
735          </question>
736          <answer>
737            <para>
738              Yes, there is. BASE2 team has created a plug-in based on
739              <ulink url="http://rmaexpress.bmbolstad.com/">
740              RMAExpress methods from Bolstad and Irizarry</ulink> so you can normalise
741              Affymetrix data sets of reasonable size (not 1000 CEL files at a time
742              though even though this might depend on your set-up...)
743              The plug-in is not included in a standard BASE installation, but
744              can be downloaded from the <ulink url="http://lev.thep.lu.se/trac/baseplugins"
745                >BASE plug-ins web site</ulink>.
746            </para>
747          </answer>
748        </qandaentry>
749      </qandaset>
750    </sect1>
751
752  </chapter>
753
754</part>
Note: See TracBrowser for help on using the repository browser.