--- title: BioJava3:HowTo --- This page is a work-in-progress, describing each of the key areas in which you might want to work with the new BioJava3 code. It is structured in the form of use-cases and is not a comprehensive resource. Sections will be added and updated as new modules are added and existing ones developed in more detail. Symbols and Alphabets ===================== A DNA sequence -------------- All the examples in this section require the biojava-dna module. ### Construction and basic manipulation ` String mySeqString = "ATCGatcgATCG"; // Note that you can use mixed-case strings.` ` List`` mySeq = SymbolListFormatter.parseSymbolList(mySeqString);` ` ` ` // Is it a big list? Don't want to hold it all in memory? Use an iterator instead.` ` for (Iterator`` myIterator = SymbolListFormater.parseSymbols(mySeqString);` `      myIterator.hasNext(); ) {` `   Symbol sym = myIterator.next();` ` }` `  ` ` // You can now use any List method, from Java Collections, to manipulate the list of bases.` ` ` ` // The List returned is actually a SymbolList, you can cast it to get some bio-specific` ` // functions that work with 1-indexed positions as opposed to Java's default 0-indexed positions.` ` ` ` SymbolList symList = (SymbolList)mySeq;  ` ` Symbol symA = symList.get(0); // The first symbol, List-style.` ` Symbol symB = symList.get_bio(1) ; // The first symbol, bio-style. ` ` if (symA==symB) { // Symbols are singletons, so == will work if they are identical including case.` `   System.out.println("Identical!");` ` }` ` ` ` // Instead of using equals() or == to compare symbols, use the alphabet of your choice to` ` // compare them in multiple ways. It will return different values depending on whether one` ` // is a gap and the other isn't, whether they match exactly, or if they're the same symbol` ` // but in a different case, etc.` ` Alphabet dna = DNATools.DNA_ALPHABET;` ` SymbolMatchType matchType = dna.getSymbolMatchType(Symbol.get("A"), Symbol.get("a"));` ### Reversing and Complementing DNA ` // All methods in this section modify the list in-place.` ` List`` mySeq = SymbolListFormatter.parseSymbolList("ATCG");` ` ` ` // Reverse.` ` // Method A.` ` Collections.reverse(mySeq); // Using Java Collections.` ` // Method B.` ` DNATools.reverse(mySeq); // DNATools-style.` ` ` ` // Complement.` ` DNATools.complement(mySeq);` ` ` ` // Reverse-complement.` ` DNATools.reverseComplement(mySeq);` `   ` ` // Reverse only the third and fourth bases, 0-indexed list style?` ` Collections.reverse(mySeq.subList(2,4)); // Java Collections API.` `   ` ` // Do the same, 1-indexed bio style?` ` Collections.reverse(((SymbolList)mySeq).subList_bio(3,5));` ### Editing the sequence ` // Delete the second and third bases.` ` List`` mySeq = SymbolListFormatter.parseSymbolList("ATCG");` ` mySeq.subList(1,3).clear();` ` ` ` // Remove only 2nd base, bio-style.` ` ((SymbolList)mySeq).remove_bio(2);` ` ` ` // Get another sequence and insert it after the 1st base.` ` List`` otherSeq = SymbolListFormatter.parseSymbolList("GGGG");` ` mySeq.addAll(1, otherSeq);` A quality-scored DNA sequence ----------------------------- ### Constructing a quality-scored DNA sequence ` // Construct a default unscored DNA sequence with capacity for integer scoring.` ` List`` mySeq = SymbolListFormatter.parseSymbolList("ATCG");` ` TaggedSymbolList`` scoredSeq = new TaggedSymbolList``(mySeq);` ` ` ` // Tag all the bases with the same score of 5.` ` scoredSeq.setTagRange(0, scoredSeq.length(), 5);` ` ` ` // Tag just the 3rd base (0-indexed) with a score of 3.` ` scoredSeq.setTag(2, 3);` ` ` ` // Do the same, 1-indexed.` ` scoredSeq.setTag_bio(3, 3);` ` ` ` // Get the score at base 4, 1-indexed.` ` Integer tag = scoredSeq.getTag_bio(4);` ### Iterating over the base/score pairs ` // A 1-indexed iterator and ListIterators are also available.` ` for (Iterator``> iter = scoredSeq.taggedSymbolIterator();` `      iter.hasNext(); ) {` `   TaggedSymbol`` taggedSym = iter.next();` `   Symbol sym = taggedSym.getSymbol();` `   Integer score = taggedSym.getTag();` `   // Change the score whilst we're at it.` `   taggedSym.setTag(6); // Updates the score to 6 in the original set of tagged scores.` ` }` ### Iterating over the bases only ` // Use the default iterator.` ` // A ListIterator is also available, as are 1-indexed iterators.` ` Iterator`` iter = scoredSeq.iterator();` ### Iterating over the scores only ` // A ListIterator is also available, as are 1-indexed iterators.` ` for (Iterator`` iter = scoredSeq.tagIterator(); iter.hasNext(); ) {` `   Integer score = iter.next();` ` }` File parsing and converting =========================== FASTA ----- The examples in this section require the biojava-fasta module. The examples that deal with converting to/from DNA sequences also require the biojava-dna module. Convenience wrapper classes are provided to make the parsing process simpler for the most common use-cases. ### Parsing a FASTA file (the easy way) ` for (ThingParser`` parser = ThingParserFactory.` `        getReadParser(FASTA.format, new File("/path/to/my/fasta.fa"));` `      parser.hasNext(); ) {` `   FASTA fasta = parser.next(); ` `   // fasta contains a complete FASTA record.` ` }` ` parser.close();` ### Parsing a FASTA file (the hard way) ` FASTAReader reader = new FASTAFileReader(new File("/path/to/my/fasta.fa"));` ` FASTABuilder builder = new FASTABuilder();` ` for (ThingParser`` parser = new ThingParser``(reader, builder);` `      parser.hasNext(); ) {` `   FASTA fasta = parser.next(); ` `   // fasta contains a complete FASTA record.` ` }` ` parser.close();` ### Converting the FASTA sequence into DNA sequence ` List`` mySeq = SymbolListFormatter.parseSymbolList(fasta.getSequence());` ### Converting a DNA sequence back into FASTA ` FASTA fasta = new FASTA();` ` fasta.setDescription("My Description Line");` ` fasta.setSequence(SymbolListFormatter.formatSymbols(mySeq));` ### Writing a FASTA file (the easy way) ` ThingParser`` parser = ThingParserFactory.` `   getWriteParser(FASTA.format, new File("/path/to/my/fasta.fa"), fasta);` ` parser.parseAll();` ` parser.close();` ### Writing a FASTA file (the hard way) ` FASTAEmitter emitter = new FASTAEmitter(fasta);` ` FASTAWriter writer = new FASTAFileWriter(new File("/path/to/new/fasta.fa"));` ` ThingParser`` parser = new ThingParser``(emitter, writer);` ` parser.parseAll();` ` parser.close();`