SequenceCollection#

class SequenceCollection(*args, **kwargs)#

Container for unaligned sequences

Attributes:
annotation_db
named_seqs
num_seqs

Returns the number of sequences in the alignment.

seqs

Methods

add_feature(*, seqid, biotype, name, spans)

add feature on named sequence

add_seqs(other[, before_name, after_name])

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

annotate_from_gff(f[, seq_ids])

copies annotations from a gff file to a sequence in self

apply_pssm([pssm, path, background, ...])

scores sequences using the specified pssm

copy()

Returns deep copy of self.

copy_annotations(seq_db)

copy annotations into attached annotation db

counts([motif_length, include_ambiguity, ...])

counts of motifs

counts_per_seq([motif_length, ...])

counts of motifs per sequence

deepcopy([sliced])

returns deep copy of self.

degap(**kwargs)

Returns copy in which sequences have no gaps.

distance_matrix([calc])

Estimated pairwise distance between sequences

dotplot([name1, name2, window, threshold, ...])

make a dotplot between specified sequences.

entropy_per_seq([motif_length, ...])

Returns the Shannon entropy per sequence.

get_ambiguous_positions()

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

get_features(*[, seqid, biotype, name, ...])

yields Feature instances

get_identical_sets([mask_degen])

returns sets of names for sequences that are identical

get_lengths([include_ambiguity, allow_gap])

returns {name: seq length, ...}

get_motif_probs([alphabet, ...])

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

get_seq(seqname)

Return a sequence object for the specified seqname.

get_seq_indices(f[, negate])

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

get_similar(target[, min_similarity, ...])

Returns new Alignment containing sequences similar to target.

get_translation([gc, incomplete_ok, ...])

translate from nucleic acid to protein

has_terminal_stop([gc, strict])

Returns True if any sequence has a terminal stop codon.

is_ragged()

Returns True if alignment has sequences of different lengths.

iter_selected([seq_order, pos_order])

Iterates over elements in the alignment.

iter_seqs([seq_order])

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

make_feature(*, feature)

create a feature on named sequence, or on the alignment itself

omit_gap_runs([allowed_run])

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

omit_gap_seqs([allowed_gap_frac])

Returns new alignment with seqs that have <= allowed_gap_frac.

pad_seqs([pad_length])

Returns copy in which sequences are padded to same length.

probs_per_seq([motif_length, ...])

return MotifFreqsArray per sequence

rc()

Returns the reverse complement alignment

rename_seqs(renamer)

returns new instance with sequences renamed

reverse_complement()

Returns the reverse complement alignment.

set_repr_policy([num_seqs, num_pos, ...])

specify policy for repr(self)

strand_symmetry([motif_length])

returns dict of strand symmetry test results per seq

take_seqs(seqs[, negate])

Returns new Alignment containing only specified seqs.

take_seqs_if(f[, negate])

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

to_dict()

Returns the alignment as a dict of sequence names -> strings.

to_dna()

returns copy of self as an alignment of DNA moltype seqs

to_fasta([block_size])

Return alignment in Fasta format.

to_html([name_order, wrap, limit, colors, ...])

returns html with embedded styles for sequence colouring

to_json()

returns json formatted string

to_moltype(moltype)

returns copy of self with moltype seqs

to_nexus(seq_type[, wrap])

Return alignment in NEXUS format and mapping to sequence ids

to_phylip()

Return alignment in PHYLIP format and mapping to sequence ids

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, strict])

Removes any terminal stop codons from the sequences

with_modified_termini()

Changes the termini to include termini char instead of gapmotif.

write([filename, format])

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

add_feature(*, seqid: str, biotype: str, name: str, spans: List[Tuple[int, int]], parent_id: str | None = None, strand: str = '+') Feature#

add feature on named sequence

Parameters:
seqid

seq name to associate with

parent_id

name of the parent feature

biotype

biological type

name

feature name

spans

plus strand coordinates

strand

either ‘+’ or ‘-’

Returns:
Feature
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_namestr

which sequence is added

after_namestr

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: PathLike, seq_ids: list[str] | str | None = None)#

copies annotations from a gff file to a sequence in self

Parameters:
f

path to gff annotation file.

seq_name

names of seqs to be annotated. Does not support setting offset, set offset directly on sequences with seq.annotation_offset = offset

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

scores sequences using the specified pssm

Parameters:
pssmprofile.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

Returns:
numpy array of log2 based scores at every position
copy()#

Returns deep copy of self.

copy_annotations(seq_db: SupportsFeatures) None#

copy annotations into attached annotation db

Parameters:
seq_db

compatible annotation db

Notes

Only copies annotations for records with seqid in self.names

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_gap

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, warn=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.

warn

warns if motif_length > 1 and alignment trimmed to produce motif columns

Returns:
MotifCountsArray

Notes

only non-overlapping motifs are counted

deepcopy(sliced: bool = True)#

returns deep copy of self.

Parameters:
sliced

if True, reduces the sequence to current interval. This also causes dropping annotations.

degap(**kwargs)#

Returns copy in which sequences have no gaps.

Parameters:
kwargs

passed to class constructor

distance_matrix(calc='pdist')#

Estimated pairwise distance between sequences

Parameters:
calcstr

The distance calculation method to use, either “pdist” or “jc69” “pdist” is an approximation of the proportion sites different “jc69” is an approximation of the Jukes Cantor distance

Returns:
DistanceMatrix

Estimated pairwise distances between sequences in the collection

Notes

pdist approximates the proportion sites different from the Jaccard distance. Coefficients for the approximation were derived from a polynomial fit between Jaccard distance of kmers with k=10 and the proportion of sites different using mammalian 106 protein coding gene DNA sequence alignments.

jc69 approximates the Jukes Cantor distance using the approximated proportion sites different, i.e., a transformation of the above.

dotplot(name1: str | None = None, name2: str | None = None, window: int = 20, threshold: int | None = None, k: int | None = None, min_gap: int = 0, width: int = 500, title: str | None = None, rc: bool = False, show_progress: bool = False)#

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

Parameters:
name1, name2

names of sequences. If not provided, a random choice is made

window

segment size for comparison between sequences

threshold

windows where the sequences are identical >= threshold are a match

k

size of k-mer to break sequences into. Larger values increase speed but reduce resolution. If not specified, and window == threshold, then k is set to window. Otherwise, it is computed as the maximum of {threshold // (window - threshold), 5}.

min_gap

permitted gap for joining adjacent line segments, default is no gap joining

width

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

title

title for the plot

rc

include dotplot of reverse compliment also. Only applies to Nucleic acids moltypes

Returns:
a Drawable or AnnotatedDrawable
entropy_per_seq(motif_length=1, include_ambiguity=False, allow_gap=False, exclude_unobserved=True, warn=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.

warn

warns if motif_length > 1 and alignment trimmed to produce motif columns

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_features(*, seqid: str | Iterable[str] = None, biotype: str | None = None, name: str | None = None, allow_partial: bool = False) Iterator[Feature]#

yields Feature instances

Parameters:
seqid

limit search to features on this named sequence, defaults to search all

biotype

biotype of the feature, e.g. CDS, gene

name

name of the feature

allow_partial

allow features partially overlaping self

Notes

When dealing with a nucleic acid moltype, the returned features will yield a sequence segment that is consistently oriented irrespective of strand of the current instance.

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_gap

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).

The default metric is fraction similarity, ranging from 0.0 (0%
identical) to 1.0 (100% identical). The Sequence classes have lots
of methods that can be passed in as unbound methods to act as the
metric, e.g. frac_same_gaps.
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.
extracting a string from an RnaSequence object), distance metrics that
depend on instance data of the original class may fail.
get_translation(gc=None, incomplete_ok=False, include_stop=False, trim_stop=True, **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

codons that are mixes of nucleotide and gaps converted to ‘?’. raises a ValueError if False

include_stop

whether to allow a stops in the translated sequence

trim_stop

exclude terminal stop codons if they exist

kwargs

related to construction of the resulting object

Returns:
A new instance of self translated into protein
has_terminal_stop(gc: Any = None, strict: bool = False) bool#

Returns True if any sequence has a terminal stop codon.

Parameters:
gc

valid input to cogent3.get_code(), a genetic code object, number or name

strict

If True, raises an exception if a seq length not divisible by 3

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.

make_feature(*, feature: FeatureDataType) Feature#

create a feature on named sequence, or on the alignment itself

Parameters:
feature

a dict with all the necessary data rto construct a feature

Returns:
Feature

Notes

To get a feature AND add it to annotation_db, use add_feature().

moltype = MolType(('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'))#
property named_seqs#
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, warn=False)#

return MotifFreqsArray per sequence

rc()#

Returns the reverse complement alignment

rename_seqs(renamer)#

returns new instance with sequences renamed

Parameters:
renamercallable

function that will take current sequences and return the new one

reverse_complement()#

Returns the reverse complement alignment. A synonym 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_seqsint or None

number of sequences to include in represented display.

num_posint or None

length of sequences to include in represented display.

ref_namestr or None

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

wrapint 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: str | Sequence[str], 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() dict[str, str]#

Returns the alignment as a dict of sequence names -> strings.

Note the mapping goes to strings, not Sequence objects.

Returns:
a dict mapping sequence names to a string representation of
their sequences.
to_dna()#

returns copy of self as an alignment of DNA moltype seqs

to_fasta(block_size: int = 60) str#

Return alignment in Fasta format.

Parameters:
block_size

the sequence length to write to each line, by default 60

Returns:
The Fasta formatted alignment.
to_html(name_order: Sequence[str] | None = None, wrap: int = 60, limit: int | None = None, colors: Mapping[str, str] | None = None, font_size: int = 12, font_family: str = 'Lucida Console') str#

returns html with embedded styles for sequence colouring

Parameters:
name_order

order of names for display.

wrap

number of alignment columns per row

limit

truncate alignment to this length

colors

{character moltype.

font_size

in points. Affects labels and sequence and line spacing (proportional to value)

font_family

string denoting font family

Examples

In a jupyter notebook, this code is used to provide the representation.

seq_col  # is rendered by jupyter

You can directly use the result for display in a notebook as

from IPython.core.display import HTML

HTML(seq_col.to_html())
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: Any = None, strict: bool = False, **kwargs)#

Removes any terminal stop codons from the sequences

Parameters:
gc

valid input to cogent3.get_code(), a genetic code object, number or name

strict

If True, raises an exception if a seq length not divisible by 3

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.