Birdsuite FAQ

Please ensure that you have followed the installation guide, to ensure the program runs as intended.

• Supported Platforms
• General Questions
• Birdsuite is Crashing

Supported Platforms

General Questions

1. How many samples should birdsuite be run on?

   Birdsuite should be run one chemistry plate at a time (~96 samples.) You'll need to batch up your CEL files to do this. Running birdsuite on multiple chemistry plates at one time will result in poor performace due to batch effects that we can not resolve, due to structure in the data you're introducing. We prefer that you run birdsuite on at least 40 samples, as many of the methods employed utilize clustering algorithms, which function better with a fair number of exemplars.

   There are other problems that can result from running too many samples - out of memory errors, corrupted files, etc. So please batch your data appropriately.

2. What are Birdsuite's CPU/Memory/Disk requirements?

   We've found 5 Gigs of ram to be optimal for speed. You can get away with 4. You'll need about 2 G of hard drive room for the results of each batch. We have no processor requirements, other than knowing that 64 bit CPUs tend to run much better/faster for this application.

3. I really want to run Birdsuite on my [Mac/PC/Toaster Oven]! Where can I get binaries?

   We support the linux operating system, and provide source code. Some users have successfully gotten Birdsuite to run on non-Unix enviornments, but they've had to build from source. We only test our software on linux, so we can't guarantee the results. If you build the code on your system and get the same results on the test data set as we distribute, you're doing it right!

4. Birdsuite is pretty great! But I think I really want to change your code because <X> is better!

   Once you change the code (beyond what's detailed in the install instructions), we'll no longer provide support for you, unless we explicitly ask you to do so to test a change. We take user input and bugs, and add them to our version of the code, so everyone can benefit
   from the problems you may find and diagnose. We appreciate your input, but attempts to change the inner workings of this quite complicated software package can be difficult and problematic.

5. What is the difference between SNP genotypes in an analysis set PED file if called by Birdseed vs. by Birdsuite?

   Birdsuite is designed to be aware of copy number variable regions in the genome. If a SNP overlaps one of these regions, it's possible to call this SNP with knowledge of that event. If the SNP overlaps a deletion, you could have calls of -/-, A/-, T/-, A/T, AA, T/T.

   Birdseed is not aware of these differences, so classes like A/- are more likely to be either miscalled, or not called at all, since they generally fall outside of the expected cluster locations.
   
   In non copy number variant regions, birdseed and birdsuite produce the same SNP genotypes.

6. If I genotype samples with Birdseed and Birdsuite independently, which one has more calls; and which one has more accurate calls?

   Birdsuite will have both more calls (as it can call SNPs in copy number variant regions) and more accurate calls, as it calls SNPs in copy number variant regions with the correct genotype, instead of a no-call or the wrong cluster assignment.

7. We're trying to use the .bed files produced by make_bed.py on larry-bird calls in Plink. Plink requires a .gvar file and make_bed.py produces a .bed file. Is there a workaround?

   There is! Please see our analysis section, which contains links to a set of programs that will convert birdsuite output to plink compatible input files.

8. I'm installing birdsuite on my 32bit workstation with Kubuntu8.10. Everything seems to
   be ok, but at the end of your installation procedure when I do the test part, for test.canary_calls,test.larry_bird_calls, test.larry_bird_confs the results I obtain do not correspond to those you provide.
   
   We've found that the 32 and 64 bit versions of APT (and different versions of APT in general) can extract some slightly different intensities. This isn't enough to change the genotypes being called, but may slightly effect the confidence scores at some non-significant digit level.
9. How long does birdsuite take to run?
   
   That depends on how fast your CPU is, but rough benchmarks are:
   Without LSF, it make take 12-24 hours to run a plate (96 samples)
   With LSF, it make take 2-5 hours to run a plate (96 samples)

   At the Broad, we put each plate onto a separate node of our 10 slot cluster queue, so we can process somewhere on the order of 40-60 plates a day.

10. What are the similarities between the Birdsuite and the Genotyping Console 3.0 available from the Affymetrix website?
    
    NEEDS TO BE ANSWERED.

Help! Birdsuite crashes before completion! What should I do?

When you send a crash or install question for us, it's impossible for us to help you without receiving some information about what happened at the time of the crash. In order to get support, please provide the following:

1. What OS you are using
2. What versions of R, python, java are you running
3. The full command line call you used that crashed.
4. All of the text that went on the screen after the command. There are often hints here as to what went wrong.

Failure to submit this information can greatly delay our response to your issue.

One of the below may be your problem:

1. APT version.

   Affy's APT software seems to work slightly differently with each release. We're been using version 1.8.6 internally, which seems to do the right thing. Versions between 1.8.6 and 1.10.2 seem to produce odd results, or don't extract all the information birdsuite needs (for
   example, APT 1.10.1 does not extract any of the SNP info.) Use version 1.8.6. Crashes can occur far downstream (divide by 0 error on birdsuite reports, caused by having no data through the entire run.)

2. APT version, this time I'm serious!
   Affy constantly changes APT around. A new bug has come up where apt crashes because they removed the mem-usage flag:
   FATAL ERROR: Don't recognize option: 'mem-usage'
   The answer is still the same. Use an approved version of APT.
3. Where are my scripts? I can't find cn_annotate_allele_summary!.

   Birdsuite changed in a fundamental way in version 1.5.5. Python scripts now need to be installed. Please read the python install documentation here [CLICK THAT LINK!] to install them correctly

4. Running 1 CEL file.

   Birdsuite expects multiple CEL files, because it's a clustering based system (see FAQ question #1.) Birdsuite will crash. We suggest running at least 20 CEL files at one time.

5. "Argument list too long"
   This is a UNIX error. You handed birdsuite far too many CEL files on the command line. (see FAQ question #1)
6. "[[: not found"
   This occurs if you don't have bash installed on your linux box. This is part of the bash scripting in birdsuite, so if you run csh or some other shell and don't have bash, you may run into this. If you're Unix Savvy, you can change the "[[" to the proper operator.

   For example, a user has written in to comment on using sh:
   We had to modify the run_birdseye.sh, because the original one didn't recognized the [[ ]] in sh interpreter.
   We changed the double brackets for single ones [ ] and it worked.
   
   We may change the bash scripts to python in a future release to avoid these problems.

7. java.io.FileNotFoundException: true (No such file or directory)
   Birdsuite requires you to put an "=" between each name and value argument.

   ./bin/birdsuite.sh --basename=test --chipType=GenomeWideSNP_6 --outputDir=output --genderFile=test.gender --celFiles=test.cels --noLsf --apt_probeset_summarize.force

   If you omit the "=", Birdsuite's argument parser things you're telling it the value of the argument is true. So --genderFile test.gender would make birdsuite believe the value of --genderFile is true, and it's hard to parse true as a file.

   Also note that there is no space between the argument name, the "=", and the value.
   --genderFile =test.gender
   will also break birdsuite.

8. Canary is crashing, help!

   Common causes of canary crashing:

   • Using only one CEL file
   • Not installing the canary libraries we distribute with R CMD INSTALL
   • Not installing the supporting R library mclust
9. "File too large" errors

    

   Run the appropriate number of samples in birdsuite (see FAQ question #1)

10. ERROR: IntensitiesParser.cpp:41 Could not open file, file
    Birdsuite/Normals.allele_summary; Value too large for defined data type

     

    Run the appropriate number of samples in birdsuite (see FAQ question #1)

11. 
    Error in library("broadgap.canary") : 'broadgap.canary' is not a valid package – installed < 2.0.0?

    This is an R error. We're not sure of how this bug is occurring, as we're unable to recreate it. It may revolve around how you have R installed in your enviornment, if you've installed the R libraries correctly, or if you override the R_LIBS path with your own path and prevent birdsuite from seeing the canary libraries. If you have your own R_LIBS path you can try installing the Birdsuite R libraries there and see if Birdsuite is able to come up with them.

    If you're able to reproduce this bug on your system and find a solution, please let us know so we can add it here.