T - the type of sequence (NucleotideSequenceDocument or AminoAcidSequenceDocument)public static class SequenceListOnDisk.Builder<T extends SequenceDocument> extends Object
addSequence for each sequence to be added,
then call toSequenceListDocument or toAlignmentDocument when done.
However, to improve performance when using sequence compression (see tryCompressingSequences parameter in constructor) it is recommended a first pass be made of the sequences, providing their names to addNameOfSequence
before making the 2nd pass using addSequence
This class is not thread safe.| Constructor and Description |
|---|
SequenceListOnDisk.Builder(boolean tryCompressingSequences,
SequenceDocument.Alphabet alphabet,
boolean allowGaps)
Create a new builder
|
SequenceListOnDisk.Builder(boolean tryCompressingSequences,
SequenceDocument.Alphabet alphabet,
boolean allowGaps,
ProgressListener progressListenerForSortingAlignment,
int maximumNumberOfSequencesThatWillBeAdded)
Create a new builder
|
SequenceListOnDisk.Builder(boolean tryCompressingSequences,
SequenceDocument.Alphabet alphabet,
boolean allowGaps,
ProgressListener progressListenerForSortingAlignment,
int maximumNumberOfSequencesThatWillBeAdded,
boolean createMultipleThreads)
Create a new builder
|
| Modifier and Type | Method and Description |
|---|---|
void |
addAlignmentReferenceSequence(SequenceDocument referenceSequence,
ProgressListener progressListener)
Adds a reference sequence when building an alignment.
|
boolean |
addNameOfSequence(String sequenceName)
Adds the name of a sequence that will be later added using
addSequence(SequenceDocument, jebl.util.ProgressListener). |
void |
addSequence(SequenceDocument sequence,
ProgressListener progressListener)
Adds a new unpaired sequence.
|
void |
addSequenceWithMate(SequenceDocument sequence,
SequenceDocument mateSequence,
int expectedDistance1,
int expectedDistance2,
ProgressListener progressListener)
Similar to
addSequence but this version adds 2 sequences which are paired |
static int |
getMinimumSuggestedContigSizeForCreatingContigsOnDisk()
Returns a suggested minimum number of sequences that should be in a SequenceListOnDisk.Builder when creating one.
|
static int |
getMinimumSuggestedReferenceLengthForCreatingContigsOnDisk()
Returns a suggested minimum sequence length for the reference sequence in a SequenceListOnDisk.Builder when creating one.
|
int |
getNumberOfSequences()
Returns the number of sequences added so far to this builder.
|
SequenceListOnDisk<T> |
getSequenceList()
Gets the result returned from a previous call to
toSequenceList. |
void |
setCircularAlignmentLength(int circularAlignmentLength)
Sets the alignment being built as circular as specified by
SequenceAlignmentDocument.getCircularLength() |
static boolean |
shouldCreateContigOnDisk(int sequenceCount,
int referenceLength)
Returns true if the sequence count and/or reference length of this contig are sufficient for it to be recommended to create a contig on disk.
|
static boolean |
shouldCreateContigOnDisk(int sequenceCount,
int referenceLength,
long totalLengthOfMappedReads)
Returns true if the sequence count and/or reference length and/or total length of all the mapped reads in this contig are sufficient for it to be recommended to create a contig on disk.
|
DefaultAlignmentDocument |
toAlignmentDocument(ProgressListener progressListener)
Creates an Alignment document from this builder.
|
SequenceListOnDisk<T> |
toSequenceList(ProgressListener progressListener)
Creates a SequenceListOnDisk from this builder.
|
DefaultSequenceListDocument |
toSequenceListDocument(ProgressListener progressListener)
Creates a new SequenceListDocument from this builder.
|
public SequenceListOnDisk.Builder(boolean tryCompressingSequences,
SequenceDocument.Alphabet alphabet,
boolean allowGaps)
throws DocumentOperationException
tryCompressingSequences - true if we should analyze sequences names for compressible patterns and convert to ImmutableSequence where possible. When using compression, for optimal performance, addNameOfSequence(String) should be called on a first pass for all sequences before calling addSequence(SequenceDocument, jebl.util.ProgressListener)allowGaps - true if gaps are allowed in the sequences. This should be false when constructing sequences lists documents (see toSequenceListDocument)
and true when constructing alignments (see toAlignmentDocument)
When allowGaps is true, sequences will be sorted according to the number of leading gaps (see SequenceCharSequence.getLeadingGapsLength) they have.alphabet - the alphabet (nucleotide or amino acid) of the sequences to be added. If the calling code chooses to use generics on this builder, it is up to it to ensure the builder type matches this parameter. The generics are useful for use with toSequenceList(jebl.util.ProgressListener), but for code that will only be using toSequenceListDocument(jebl.util.ProgressListener) or toAlignmentDocument(jebl.util.ProgressListener) on this builder, they can safely not use generics.DocumentOperationException - if we can't write to a temporary file on disk.public SequenceListOnDisk.Builder(boolean tryCompressingSequences,
SequenceDocument.Alphabet alphabet,
boolean allowGaps,
ProgressListener progressListenerForSortingAlignment,
int maximumNumberOfSequencesThatWillBeAdded)
throws DocumentOperationException
tryCompressingSequences - true if we should analyze sequences names for compressible patterns and convert to ImmutableSequence where possible. When using compression, for optimal performance, addNameOfSequence(String) should be called on a first pass for all sequences before calling addSequence(SequenceDocument, jebl.util.ProgressListener)allowGaps - true if gaps are allowed in the sequences. This should be false when constructing sequences lists documents (see toSequenceListDocument)
and true when constructing alignments (see toAlignmentDocument)
When allowGaps is true, sequences will be sorted according to the number of leading gaps they have.alphabet - the alphabet (nucleotide or amino acid) of the sequences to be added. If the calling code chooses to use generics on this builder, it is up to it to ensure the builder type matches this parameter. The generics are useful for use with toSequenceList(jebl.util.ProgressListener), but for code that will only be using toSequenceListDocument(jebl.util.ProgressListener) or toAlignmentDocument(jebl.util.ProgressListener) on this builder, they can safely not use generics.progressListenerForSortingAlignment - when creating alignments, sorting and saving may need to be report progress prior to toAlignmentDocument(jebl.util.ProgressListener) is called. This progress listener will continue to have progress reported to it after returning from this method.maximumNumberOfSequencesThatWillBeAdded - an upper bound number of sequences that will be added to the alignment builder, or -1 if unknown. Progress reporting will be inaccurate if -1 is provided.DocumentOperationException - if we can't write to a temporary file on disk.public SequenceListOnDisk.Builder(boolean tryCompressingSequences,
SequenceDocument.Alphabet alphabet,
boolean allowGaps,
ProgressListener progressListenerForSortingAlignment,
int maximumNumberOfSequencesThatWillBeAdded,
boolean createMultipleThreads)
throws DocumentOperationException
tryCompressingSequences - true if we should analyze sequences names for compressible patterns and convert to ImmutableSequence where possible. When using compression, for optimal performance, addNameOfSequence(String) should be called on a first pass for all sequences before calling addSequence(SequenceDocument, jebl.util.ProgressListener)allowGaps - true if gaps are allowed in the sequences. This should be false when constructing sequences lists documents (see toSequenceListDocument)
and true when constructing alignments (see toAlignmentDocument)
When allowGaps is true, sequences will be sorted according to the number of leading gaps they have.alphabet - the alphabet (nucleotide or amino acid) of the sequences to be added. If the calling code chooses to use generics on this builder, it is up to it to ensure the builder type matches this parameter. The generics are useful for use with toSequenceList(jebl.util.ProgressListener), but for code that will only be using toSequenceListDocument(jebl.util.ProgressListener) or toAlignmentDocument(jebl.util.ProgressListener) on this builder, they can safely not use generics.progressListenerForSortingAlignment - when creating alignments, sorting and saving may need to be report progress prior to toAlignmentDocument(jebl.util.ProgressListener) is called. This progress listener will continue to have progress reported to it after returning from this method.maximumNumberOfSequencesThatWillBeAdded - an upper bound number of sequences that will be added to the alignment builder, or -1 if unknown. Progress reporting will be inaccurate if -1 is provided.createMultipleThreads - true to create multiple threads to improve performance when necessary. Normally this should be true except in cases where code is creating many SequenceListOnDisk.Builders at once in which case you might run out of system threads.DocumentOperationException - if we can't write to a temporary file on disk.public static int getMinimumSuggestedContigSizeForCreatingContigsOnDisk()
DefaultAlignmentDocument constructors. For SequenceLists, the overhead is small so creating a SequenceListOnDisk
for even a list of 2 sequences is fine.getMinimumSuggestedReferenceLengthForCreatingContigsOnDisk(),
shouldCreateContigOnDisk(int, int)public static int getMinimumSuggestedReferenceLengthForCreatingContigsOnDisk()
DefaultAlignmentDocument constructors.getMinimumSuggestedContigSizeForCreatingContigsOnDisk(),
shouldCreateContigOnDisk(int, int)public static boolean shouldCreateContigOnDisk(int sequenceCount,
int referenceLength)
sequenceCount - number of sequences in the contigreferenceLength - length of the reference sequence or -1 if no reference.getMinimumSuggestedReferenceLengthForCreatingContigsOnDisk(),
getMinimumSuggestedContigSizeForCreatingContigsOnDisk()public static boolean shouldCreateContigOnDisk(int sequenceCount,
int referenceLength,
long totalLengthOfMappedReads)
sequenceCount - number of sequences in the contigreferenceLength - length of the reference sequence or -1 if no reference.totalLengthOfMappedReads - total length of all mapped reads or -1 if unknowngetMinimumSuggestedReferenceLengthForCreatingContigsOnDisk(),
getMinimumSuggestedContigSizeForCreatingContigsOnDisk()public boolean addNameOfSequence(String sequenceName)
addSequence(SequenceDocument, jebl.util.ProgressListener). It is optional to make
a first pass of the sequences providing their names, but doing so will improve performance if tryCompressingSequences==true was passed to the builder constructor.
This method should not be called for the name of the reference sequence that will be passed to addAlignmentReferenceSequence (if any).sequenceName - the name of the sequenceaddNameOfSequence(String) will be ignored. The calling code could skip straight to the 2nd pass in this case.IllegalStateException - if toSequenceList or addSequence has already been calledpublic void setCircularAlignmentLength(int circularAlignmentLength)
SequenceAlignmentDocument.getCircularLength()circularAlignmentLength - the circular alignment length or 0 for not circular (SequenceAlignmentDocument.getCircularLength())IllegalStateException - if this is called after adding any sequences or if allowGaps==true wasn't passed to the constructor.public void addSequenceWithMate(SequenceDocument sequence, SequenceDocument mateSequence, int expectedDistance1, int expectedDistance2, ProgressListener progressListener) throws DocumentOperationException
addSequence but this version adds 2 sequences which are pairedsequence - the sequence to addmateSequence - the mate sequence to addexpectedDistance1 - the expected distance from the first sequence to its mate. Must not be 0.expectedDistance2 - the expected distance from the second sequence to its mate. This must be equal to either expectedDistance1 or -1*expectedDistance1, depending on the relative orientation of the pairs. See PairedReads for expected distance meanings.progressListener - for reporting progress if this is a large sequenceDocumentOperationException - if we can't write to disk or if the progressListener indicates we should cancel.IllegalStateException - if toSequenceList(jebl.util.ProgressListener) has already been called on this builder or if the sequence is not a NucleotideSequenceDocument or AminoAcidSequenceDocumentIllegalArgumentException - if the sequence contains gaps when not allowed, or if it contains invalid nucleotide or amino acid characters or if invalid expected distances are provided.public void addSequence(SequenceDocument sequence, ProgressListener progressListener) throws DocumentOperationException
addSequenceWithMate(SequenceDocument, SequenceDocument, int, int, jebl.util.ProgressListener) or can be be paired later by using DefaultSequenceListDocument.setPairedReadsManager on the result of toSequenceListDocument
If this list is being built for use with an alignment, since sequences will get sorted by leading gaps, paired sequences need to be added using addSequenceWithMate.
This method should not be called to add the reference sequence to a contig.
Instead addAlignmentReferenceSequence(SequenceDocument, jebl.util.ProgressListener addAlignmentReferenceSequence) should be called prior to adding any sequences.sequence - the sequence to addprogressListener - for reporting progress if this is a large sequenceDocumentOperationException - if we can't write to disk or if the progressListener indicates we should cancel.IllegalStateException - if toSequenceList(jebl.util.ProgressListener) has already been called on this builder or if the sequence is not a NucleotideSequenceDocument or AminoAcidSequenceDocumentIllegalArgumentException - if the sequence contains gaps when not allowed, or if it contains invalid nucleotide or amino acid characters.public void addAlignmentReferenceSequence(SequenceDocument referenceSequence, ProgressListener progressListener) throws DocumentOperationException
addSequencereferenceSequence - the reference sequenceprogressListener - for reporting progress if this is a large sequenceDocumentOperationException - if we can't write to disk or if the progressListener indicates we should cancel.public SequenceListOnDisk<T> toSequenceList(ProgressListener progressListener) throws DocumentOperationException
toSequenceListDocument or toAlignmentDocument instead.progressListener - for reporting progress and cancelling.DocumentOperationException - if we can't write to disk or if the progressListener indicates we should cancel.IllegalStateException - if this method or toSequenceListDocument(jebl.util.ProgressListener) has already been called or if no sequences have been addedpublic SequenceListOnDisk<T> getSequenceList()
toSequenceList. In most situations you probably want to use toSequenceListDocument or toAlignmentDocument instead.
This method need not be used unless you are constructing your own alignment or sequence list implementation rather than using toAlignmentDocument or toSequenceListDocumentIllegalStateException - if at least one of toSequenceListDocument(jebl.util.ProgressListener) or toSequenceList(jebl.util.ProgressListener) or toAlignmentDocument(jebl.util.ProgressListener) have not been called yetpublic DefaultSequenceListDocument toSequenceListDocument(ProgressListener progressListener) throws DocumentOperationException
progressListener - for reporting progress and cancelling.DocumentOperationException - if we can't write to disk or if the progressListener indicates we should cancel.IllegalStateException - if this method or toSequenceList(jebl.util.ProgressListener) has already been called
or if allowGaps is true for this builder.public DefaultAlignmentDocument toAlignmentDocument(ProgressListener progressListener) throws DocumentOperationException
Builder#Builder(boolean, SequenceDocument.Alphabet, boolean).
For constructing reference sequence alignments, use addAlignmentReferenceSequence prior to adding
sequences using addSequenceprogressListener - for reporting progress and cancelling.DocumentOperationException - if we can't write to disk or if the progressListener indicates we should cancel.IllegalStateException - if allowGaps is false for this builderpublic int getNumberOfSequences()