Edit a Sequence

How to Edit a Sequence using a Builder

NucleotideSequenceBuilder is a class that allows code to programmatically construct an immutable NucleotideSequence in a similar manner to how a Java StringBuilder can build an immutable String. NucleotideSequenceBuilder uses method chaining which allows calls to its methods to get chained together for easier reading.

The build() method will return an immutable instance of the NucleotideSequence interface which will have the same sequence as the current sequence in the builder. The Builder class will choose which implementation to use and how to encode the sequence to improve performance.

Simple example:

  //will create a NucleotideSequence which will have the sequence 'ACGT'
 
  NucleotideSequence sequence = new NucleotideSequenceBuilder("ACGT").build();

Constructing a new Builder

Sequence Builders can be created either via one of its constructors, or through one of the helper methods on the Sequence object.

Creating using constructors

A String of the input Sequence to start with, use either "-" or "*" to represent gaps.

 new NucleotideSequenceBuilder("ACGT")

An empty constructor or a constructor taking an int will create a new Builder with an empty sequence but with the initial given buffer capacity. The empty constructor will use the default buffer capacity.

 new NucleotideSequenceBuilder()
                   .append("ACGT")

Using other Sequence objects as input

new Builders can be created using an initial sequence based on another Sequence object.

There are actually 2 ways to create a new Builder object from a sequence. Jillion 5 introduced new methods on the Sequence object including toBuilder() which will make a new sequence object

Initializing Builder to full Sequence

Both of these code blocks below create a new NucleotideSequenceBuilder that is initialized to the complete sequence:

NucleotideSequence other = ...

NucleotideSequenceBuilder builder = other.toBuilder();

The Builder objects also have constructors that take Sequences as input.

NucleotideSequence other = ...

NucleotideSequenceBuilder builder = new NucleotideSequenceBuilder(other);

Initializing Builder to Subsequence

Both of these code blocks below create a new NucleotideSequenceBuilder that is initialized to the just a portion of the input sequence as specified by the Range parameter.

NucleotideSequence other = ...
Range range = Range.of(200, 500);
NucleotideSequenceBuilder builder = other.toBuilder(range);

The Builder objects also have constructors that take Sequences as input.

NucleotideSequence other = ...
Range range = Range.of(200, 500);
NucleotideSequenceBuilder builder = new NucleotideSequenceBuilder(other, range);

This is will produce the same resulting sequence as

NucleotideSequenceBuilder builder = new NucleotideSequenceBuilder(other)
                                         .trim(range);

but will be more efficient since the Builder doesn't have to read in the whole sequence, allocate all that memory and then throw most of it away.

How to ungap a Sequence

NucleotideSequence ungappedSequence = new NucleotideSequenceBuilder("AC-GT-AC-GT")
				                    .ungap()
				                    .build();

//ungappedSequence will now contain "ACGTACGT"

How to reverse complement a Sequence

NucleotideSequenceBuilders have a method called reverseComplement() which will reverse complement the current sequence stored in the builder. Any future additions to the sequence will not be auto-complemented.

NucleotideSequence complementedSeq = new NucleotideSequenceBuilder("AAAAGGGG")
                                          .reverseComplement()
                                          .build();
 
//complementedSeq will now contain "CCCCTTTT"

How to perform multiple changes to a sequence

NucleotideSequenceBuilders use method chaining to allow users to write more intent revealing code:

NucleotideSequence seq = new NucleotideSequenceBuilder("AA--AAG-GG-G")
                                    .reverseComplement()
                                    .ungap()
                                    .append("NNNN")
                                    .build();
 
//seq will now contain "CCCCTTTTNNNN"