SequenceCollection

class SequenceCollection(data, names=None, alphabet=None, moltype=None, name=None, info=None, conversion_f=None, is_array=False, force_same_data=False, remove_duplicate_names=False, label_to_name=None, suppress_named_seqs=False)

Container for unaligned sequences

add_seqs(other, before_name=None, after_name=None)

Returns new object of class self with sequences from other added.

Parameters:

  • other – same class as self or coerceable to that class

  • before_name (str) – which sequence is added

  • after_name (str) – which sequence is added

Notes

If both before_name and after_name are specified, the seqs will be inserted using before_name.

By default the sequence is appended to the end of the alignment, this can be changed by using either before_name or after_name arguments.

annotate_from_gff(f)

Copies annotations from gff-format file to self.

Matches by name of sequence. This method accepts string path or pathlib.Path or file-like object (e.g. StringIO)

Skips sequences in the file that are not in self.

apply_pssm(pssm=None, path=None, background=None, pseudocount=0, names=None, ui=None)

scores sequences using the specified pssm

Parameters:

  • pssm (profile.PSSM) – if not provided, will be loaded from path

  • path – path to either a jaspar or cisbp matrix (path must end have a suffix matching the format).

  • pseudocount – adjustment for zero in matrix

  • names – returns only scores for these sequences and in the name order

Return type:

numpy array of log2 based scores at every position

copy()

Returns deep copy of self.

copy_annotations(unaligned)

Copies annotations from seqs in unaligned to self, matching by name.

Alignment programs like ClustalW don’t preserve annotations, so this method is available to copy annotations off the unaligned sequences.

unaligned should be a dictionary of Sequence instances.

Ignores sequences that are not in self, so safe to use on larger dict of seqs that are not in the current collection/alignment.

counts(motif_length=1, include_ambiguity=False, allow_gap=False, exclude_unobserved=False)

counts of motifs

Parameters:

  • motif_length – number of elements per character.

  • include_ambiguity – if True, motifs containing ambiguous characters from the seq moltype are included. No expansion of those is attempted.

  • allow_gaps – if True, motifs containing a gap character are included.

  • exclude_unobserved – if True, unobserved motif combinations are excluded.

Notes

only non-overlapping motifs are counted

counts_per_seq(motif_length=1, include_ambiguity=False, allow_gap=False, exclude_unobserved=False)

counts of motifs per sequence

Parameters:

  • motif_length – number of characters per tuple.

  • include_ambiguity – if True, motifs containing ambiguous characters from the seq moltype are included. No expansion of those is attempted.

  • allow_gap – if True, motifs containing a gap character are included.

Return type:

MotifCountsArray

Notes

only non-overlapping motifs are counted

deepcopy(sliced=True)

Returns deep copy of self.

degap(**kwargs)

Returns copy in which sequences have no gaps.

dotplot(name1=None, name2=None, window=20, threshold=None, k=None, min_gap=0, width=500, title=None, rc=False, show_progress=False)

make a dotplot between specified sequences. Random sequences chosen if names not provided.

Parameters:

  • name1 (str or None) – names of sequences. If one is not provided, a random choice is made

  • name2 (str or None) – names of sequences. If one is not provided, a random choice is made

  • window (int) – k-mer size for comparison between sequences

  • threshold (int) – windows where the sequences are identical >= threshold are a match

  • k (int) – size of k-mer to break sequences into. Larger values increase speed but reduce resolution. If not specified, is computed as the maximum of (window-threshold), (window % k) * k <= threshold.

  • min_gap (int) – permitted gap for joining adjacent line segments, default is no gap joining

  • width (int) – figure width. Figure height is computed based on the ratio of len(seq1) / len(seq2)

  • title – title for the plot

  • rc (bool or None) – include dotplot of reverse compliment also. Only applies to Nucleic acids moltypes

Return type:

a Drawable or AnnotatedDrawable

entropy_per_seq(motif_length=1, include_ambiguity=False, allow_gap=False, exclude_unobserved=True, alert=False)

Returns the Shannon entropy per sequence.

Parameters:

  • motif_length (int) – number of characters per tuple.

  • include_ambiguity (bool) – if True, motifs containing ambiguous characters from the seq moltype are included. No expansion of those is attempted.

  • allow_gap (bool) – if True, motifs containing a gap character are included.

  • exclude_unobserved (bool) – if True, unobserved motif combinations are excluded.

Notes

For motif_length > 1, it’s advisable to specify exclude_unobserved=True, this avoids unnecessary calculations.

get_ambiguous_positions()

Returns dict of seq:{position:char} for ambiguous chars.

Used in likelihood calculations.

get_identical_sets(mask_degen=False)

returns sets of names for sequences that are identical

Parameters:

mask_degen – if True, degenerate characters are ignored

get_lengths(include_ambiguity=False, allow_gap=False)

returns {name: seq length, …}

Parameters:

  • include_ambiguity – if True, motifs containing ambiguous characters from the seq moltype are included. No expansion of those is attempted.

  • allow_gaps – if True, motifs containing a gap character are included.

get_motif_probs(alphabet=None, include_ambiguity=False, exclude_unobserved=False, allow_gap=False, pseudocount=0)

Return a dictionary of motif probs, calculated as the averaged frequency across sequences.

Parameters:

  • include_ambiguity – if True resolved ambiguous codes are included in estimation of frequencies, default is False.

  • exclude_unobserved – if True, motifs that are not present in the alignment are excluded from the returned dictionary, default is False.

  • allow_gap – allow gap motif

Notes

only non-overlapping motifs are counted

get_seq(seqname)

Return a sequence object for the specified seqname.

get_seq_indices(f, negate=False)

Returns list of keys of seqs where f(row) is True.

List will be in the same order as self.names, if present.

get_similar(target, min_similarity=0.0, max_similarity=1.0, metric=<cogent3.util.transform.for_seq object>, transform=None)

Returns new Alignment containing sequences similar to target.

Parameters:

  • target – sequence object to compare to. Can be in the alignment.

  • min_similarity – minimum similarity that will be kept. Default 0.0.

  • max_similarity – maximum similarity that will be kept. Default 1.0. (Note that both min_similarity and max_similarity are inclusive.) metric similarity function to use. Must be f(first_seq, second_seq).

  • similarity (The default metric is fraction) –

  • (0% (ranging from 0.0) –

  • lots (identical) to 1.0 (100% identical). The Sequence classes have) –

  • the (of methods that can be passed in as unbound methods to act as) –

  • metric –

  • frac_same_gaps. (e.g.) –

  • transform – transformation function to use on the sequences before the metric is calculated. If None, uses the whole sequences in each case. A frequent transformation is a function that returns a specified range of a sequence, e.g. eliminating the ends. Note that the transform applies to both the real sequence and the target sequence.

  • WARNING (if the transformation changes the type of the sequence (e.g.) –

  • object) (extracting a string from an RnaSequence) –

  • that (distance metrics) –

  • fail. (depend on instance data of the original class may) –

get_translation(gc=None, incomplete_ok=False, **kwargs)

translate from nucleic acid to protein

Parameters:

  • gc – genetic code, either the number or name (use cogent3.core.genetic_code.available_codes)

  • incomplete_ok (bool) – codons that are mixes of nucleotide and gaps converted to ‘?’. raises a ValueError if False

  • kwargs – related to construction of the resulting object

Return type:

A new instance of self translated into protein

has_terminal_stops(gc=None, allow_partial=False)

Returns True if any sequence has a terminal stop codon.

Parameters:

  • gc – genetic code object

  • allow_partial – if True and the sequence length is not divisible by 3, ignores the 3’ terminal incomplete codon

is_array = {'array', 'array_seqs'}
is_ragged()

Returns True if alignment has sequences of different lengths.

iter_selected(seq_order=None, pos_order=None)

Iterates over elements in the alignment.

seq_order (names) can be used to select a subset of seqs. pos_order (positions) can be used to select a subset of positions.

Always iterates along a seq first, then down a position (transposes normal order of a[i][j]; possibly, this should change)..

WARNING: Alignment.iter_selected() is not the same as alignment.iteritems() (which is the built-in dict iteritems that iterates over key-value pairs).

iter_seqs(seq_order=None)

Iterates over values (sequences) in the alignment, in order.

seq_order: list of keys giving the order in which seqs will be returned. Defaults to self.Names. Note that only these sequences will be returned, and that KeyError will be raised if there are sequences in order that have been deleted from the Alignment. If self.Names is None, returns the sequences in the same order as self.named_seqs.values().

Use map(f, self.seqs()) to apply the constructor f to each seq. f must accept a single list as an argument.

Always returns references to the same objects that are values of the alignment.

moltype = MolType(('\x00', '\x01', '\x02', '\x03', '\x04', '\x05', '\x06', '\x07', '\x08', '\t', '\n', '\x0b', '\x0c', '\r', '\x0e', '\x0f', '\x10', '\x11', '\x12', '\x13', '\x14', '\x15', '\x16', '\x17', '\x18', '\x19', '\x1a', '\x1b', '\x1c', '\x1d', '\x1e', '\x1f', ' ', '!', '"', '#', '$', '%', '&', "'", '(', ')', '*', '+', ',', '-', '.', '/', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', ':', ';', '<', '=', '>', '?', '@', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', '[', '\\', ']', '^', '_', '`', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', '{', '|', '}', '~', '\x7f', '\x80', '\x81', '\x82', '\x83', '\x84', '\x85', '\x86', '\x87', '\x88', '\x89', '\x8a', '\x8b', '\x8c', '\x8d', '\x8e', '\x8f', '\x90', '\x91', '\x92', '\x93', '\x94', '\x95', '\x96', '\x97', '\x98', '\x99', '\x9a', '\x9b', '\x9c', '\x9d', '\x9e', '\x9f', '\xa0', '¡', '¢', '£', '¤', '¥', '¦', '§', '¨', '©', 'ª', '«', '¬', '\xad', '®', '¯', '°', '±', '²', '³', '´', 'µ', '¶', '·', '¸', '¹', 'º', '»', '¼', '½', '¾', '¿', 'À', 'Á', 'Â', 'Ã', 'Ä', 'Å', 'Æ', 'Ç', 'È', 'É', 'Ê', 'Ë', 'Ì', 'Í', 'Î', 'Ï', 'Ð', 'Ñ', 'Ò', 'Ó', 'Ô', 'Õ', 'Ö', '×', 'Ø', 'Ù', 'Ú', 'Û', 'Ü', 'Ý', 'Þ', 'ß', 'à', 'á', 'â', 'ã', 'ä', 'å', 'æ', 'ç', 'è', 'é', 'ê', 'ë', 'ì', 'í', 'î', 'ï', 'ð', 'ñ', 'ò', 'ó', 'ô', 'õ', 'ö', '÷', 'ø', 'ù', 'ú', 'û', 'ü', 'ý', 'þ', 'ÿ'))
property num_seqs

Returns the number of sequences in the alignment.

omit_gap_runs(allowed_run=1)

Returns new alignment where all seqs have runs of gaps <=allowed_run.

Note that seqs with exactly allowed_run gaps are not deleted. Default is for allowed_run to be 1 (i.e. no consecutive gaps allowed).

Because the test for whether the current gap run exceeds the maximum allowed gap run is only triggered when there is at least one gap, even negative values for allowed_run will still let sequences with no gaps through.

omit_gap_seqs(allowed_gap_frac=0)

Returns new alignment with seqs that have <= allowed_gap_frac.

allowed_gap_frac should be a fraction between 0 and 1 inclusive. Default is 0.

pad_seqs(pad_length=None, **kwargs)

Returns copy in which sequences are padded to same length.

Parameters:

pad_length – Length all sequences are to be padded to. Will pad to max sequence length if pad_length is None or less than max length.

probs_per_seq(motif_length=1, include_ambiguity=False, allow_gap=False, exclude_unobserved=False, alert=False)

return MotifFreqsArray per sequence

rc()

Returns the reverse complement alignment

rename_seqs(renamer)

returns new instance with sequences renamed

Parameters:

renamer (callable) – function that will take current sequences and return the new one

reverse_complement()

Returns the reverse complement alignment. A synonymn for rc.

property seqs
set_repr_policy(num_seqs=None, num_pos=None, ref_name=None, wrap=None)

specify policy for repr(self)

Parameters:

  • num_seqs (int or None) – number of sequences to include in represented display.

  • num_pos (int or None) – length of sequences to include in represented display.

  • ref_name (str or None) – name of sequence to be placed first, or “longest” (default). If latter, indicates longest sequence will be chosen.

  • wrap (int or None) – number of printed bases per row

strand_symmetry(motif_length=1)

returns dict of strand symmetry test results per seq

take_seqs(seqs, negate=False, **kwargs)

Returns new Alignment containing only specified seqs.

Note that the seqs in the new alignment will be references to the same objects as the seqs in the old alignment.

take_seqs_if(f, negate=False, **kwargs)

Returns new Alignment containing seqs where f(row) is True.

Note that the seqs in the new Alignment are the same objects as the seqs in the old Alignment, not copies.

to_dict()

Returns the alignment as dict of names -> strings.

Note: returns strings, NOT Sequence objects.

to_dna()

returns copy of self as an alignment of DNA moltype seqs

to_fasta()

Return alignment in Fasta format

Parameters:

make_seqlabel – callback function that takes the seq object and returns a label str

to_json()

returns json formatted string

to_moltype(moltype)

returns copy of self with moltype seqs

to_nexus(seq_type, wrap=50)

Return alignment in NEXUS format and mapping to sequence ids

NOTE Not that every sequence in the alignment MUST come from

a different species!! (You can concatenate multiple sequences from same species together before building tree)

seq_type: dna, rna, or protein

Raises exception if invalid alignment

to_phylip()

Return alignment in PHYLIP format and mapping to sequence ids

raises exception if invalid alignment

to_protein()

returns copy of self as an alignment of PROTEIN moltype seqs

to_rich_dict()

returns detailed content including info and moltype attributes

to_rna()

returns copy of self as an alignment of RNA moltype seqs

trim_stop_codons(gc=None, allow_partial=False, **kwargs)

Removes any terminal stop codons from the sequences

Parameters:

  • gc – genetic code object

  • allow_partial – if True and the sequence length is not divisible by 3, ignores the 3’ terminal incomplete codon

with_modified_termini()

Changes the termini to include termini char instead of gapmotif.

Useful to correct the standard gap char output by most alignment programs when aligned sequences have different ends.

write(filename=None, format=None, **kwargs)

Write the alignment to a file, preserving order of sequences.

Parameters:

  • filename – name of the sequence file

  • format – format of the sequence file

Notes

If format is None, will attempt to infer format from the filename suffix.