Skip to content

Sequence Module

Core sequence handling and manipulation.

Overview

The sequence module provides the Sequence class for representing individual DNA/protein sequences.

Classes

pypopart.core.sequence

DNA sequence representation and manipulation for PyPopART.

Sequence

Represents a DNA sequence with metadata.

Supports IUPAC nucleotide codes including ambiguous characters.

Source code in src/pypopart/core/sequence.py 
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
class Sequence:
    """
    Represents a DNA sequence with metadata.

    Supports IUPAC nucleotide codes including ambiguous characters.
    """

    # IUPAC nucleotide codes (uppercase)
    VALID_CHARS = set('ACGTRYSWKMBDHVN-?')

    # Reverse complement mapping
    COMPLEMENT = {
        'A': 'T',
        'T': 'A',
        'C': 'G',
        'G': 'C',
        'R': 'Y',
        'Y': 'R',
        'S': 'S',
        'W': 'W',
        'K': 'M',
        'M': 'K',
        'B': 'V',
        'V': 'B',
        'D': 'H',
        'H': 'D',
        'N': 'N',
        '-': '-',
        '?': '?',
    }

    def __init__(
        self,
        id: str,
        data: str,
        metadata: Optional[Dict[str, Any]] = None,
        description: Optional[str] = None,
    ):
        """
        Initialize a sequence.

        Parameters
        ----------
        id :
            Sequence identifier.
        data :
            DNA sequence string.
        metadata :
            Optional metadata dictionary.
        description :
            Optional sequence description.

        Raises :
        ValueError :
            If sequence contains invalid characters.
        """
        self.id = id
        self.data = data.strip().upper()
        self.metadata = metadata if metadata is not None else {}
        self.description = description

        # Validate sequence
        self._validate()

    def _validate(self) -> None:
        """
        Validate sequence data contains only valid IUPAC characters.

        Raises
        ------
            ValueError: If invalid characters found
        """
        invalid = set(self.data) - self.VALID_CHARS
        if invalid:
            raise ValueError(f'Invalid characters in sequence: {sorted(invalid)}')

    def __len__(self) -> int:
        """Return sequence length."""
        return len(self.data)

    def __eq__(self, other: object) -> bool:
        """Check equality based on sequence data."""
        if not isinstance(other, Sequence):
            return False
        return self.data == other.data

    def __hash__(self) -> int:
        """Hash based on sequence data for use in sets/dicts."""
        return hash(self.data)

    def __str__(self) -> str:
        """Return FASTA format string representation."""
        header = f'>{self.id}'
        if self.description:
            header += f' {self.description}'
        return f'{header}\n{self.data}'

    def __repr__(self) -> str:
        """Return detailed representation."""
        return (
            f"Sequence(id='{self.id}', length={len(self)}, data='{self.data[:20]}...')"
        )

    def reverse_complement(self) -> 'Sequence':
        """
        Calculate reverse complement of sequence.

        Returns
        -------
            New Sequence object with reverse complement.
        """
        rev_comp_data = ''.join(self.COMPLEMENT[base] for base in reversed(self.data))
        return Sequence(
            id=f'{self.id}_rev_comp',
            data=rev_comp_data,
            metadata=self.metadata.copy(),
            description=f'Reverse complement of {self.id}',
        )

    def gc_content(self) -> float:
        """
        Calculate GC content as fraction (0.0-1.0).

        Ignores gaps (-) and ambiguous characters (N, ?).

        Returns
        -------
            GC content fraction.
        """
        # Count G, C, and S (which represents G or C)
        gc_count = sum(1 for base in self.data if base in 'GCS')
        # Count only ACGT bases (exclude gaps, ambiguous chars)
        total_count = sum(1 for base in self.data if base in 'ACGT')

        if total_count == 0:
            return 0.0
        return gc_count / total_count

    def count_gaps(self) -> int:
        """
        Count number of gap characters.

        Returns
        -------
            Number of gaps.
        """
        return self.data.count('-')

    def count_ambiguous(self) -> int:
        """
        Count number of ambiguous characters (N and ?).

        Returns
        -------
            Number of ambiguous characters.
        """
        return sum(1 for base in self.data if base in 'N?')

    def remove_gaps(self) -> 'Sequence':
        """
        Create new sequence with gaps removed.

        Returns
        -------
            New Sequence object without gaps.
        """
        ungapped_data = self.data.replace('-', '')
        return Sequence(
            id=self.id,
            data=ungapped_data,
            metadata=self.metadata.copy(),
            description=self.description,
        )

    def slice(self, start: int, end: Optional[int] = None) -> 'Sequence':
        """
            Extract a slice of the sequence.

        Parameters
        ----------
            start :
                Start position (0-based, inclusive).
            end :
                End position (0-based, exclusive), None for end of sequence.

        Returns
        -------
            New Sequence object with sliced data.
        """
        sliced_data = self.data[start:end]
        slice_desc = f'slice[{start}:{end if end else "end"}]'
        return Sequence(
            id=f'{self.id}_{slice_desc}',
            data=sliced_data,
            metadata=self.metadata.copy(),
            description=f'Slice {slice_desc} of {self.id}',
        )

    def to_dict(self) -> Dict[str, Any]:
        """
        Convert sequence to dictionary representation.

        Returns
        -------
            Dictionary with sequence data and statistics.
        """
        return {
            'id': self.id,
            'data': self.data,
            'metadata': self.metadata,
            'description': self.description,
            'length': len(self),
            'gc_content': self.gc_content(),
            'gaps': self.count_gaps(),
            'ambiguous': self.count_ambiguous(),
        }

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> 'Sequence':
        """
            Create sequence from dictionary.

        Parameters
        ----------
            data :
                Dictionary with sequence information.

        Returns
        -------
            New Sequence object.
        """
        return cls(
            id=data['id'],
            data=data['data'],
            metadata=data.get('metadata', {}),
            description=data.get('description'),
        )
__init__ 
__init__(
    id: str,
    data: str,
    metadata: Optional[Dict[str, Any]] = None,
    description: Optional[str] = None,
)

Initialize a sequence.

Parameters:

Name Type Description Default
id str

Sequence identifier.

 required
data str

DNA sequence string.

 required
metadata Optional[Dict[str, Any]]

Optional metadata dictionary.

 None
description Optional[str]

Optional sequence description.

 None
Raises
required
ValueError

If sequence contains invalid characters.

 required
Source code in src/pypopart/core/sequence.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def __init__(
    self,
    id: str,
    data: str,
    metadata: Optional[Dict[str, Any]] = None,
    description: Optional[str] = None,
):
    """
    Initialize a sequence.

    Parameters
    ----------
    id :
        Sequence identifier.
    data :
        DNA sequence string.
    metadata :
        Optional metadata dictionary.
    description :
        Optional sequence description.

    Raises :
    ValueError :
        If sequence contains invalid characters.
    """
    self.id = id
    self.data = data.strip().upper()
    self.metadata = metadata if metadata is not None else {}
    self.description = description

    # Validate sequence
    self._validate()
__len__ 
__len__() -> int

Return sequence length.

Source code in src/pypopart/core/sequence.py 
82
83
84
def __len__(self) -> int:
    """Return sequence length."""
    return len(self.data)
__eq__ 
__eq__(other: object) -> bool

Check equality based on sequence data.

Source code in src/pypopart/core/sequence.py 
86
87
88
89
90
def __eq__(self, other: object) -> bool:
    """Check equality based on sequence data."""
    if not isinstance(other, Sequence):
        return False
    return self.data == other.data
__hash__ 
__hash__() -> int

Hash based on sequence data for use in sets/dicts.

Source code in src/pypopart/core/sequence.py 
92
93
94
def __hash__(self) -> int:
    """Hash based on sequence data for use in sets/dicts."""
    return hash(self.data)
__str__ 
__str__() -> str

Return FASTA format string representation.

Source code in src/pypopart/core/sequence.py 
 96
 97
 98
 99
100
101
def __str__(self) -> str:
    """Return FASTA format string representation."""
    header = f'>{self.id}'
    if self.description:
        header += f' {self.description}'
    return f'{header}\n{self.data}'
__repr__ 
__repr__() -> str

Return detailed representation.

Source code in src/pypopart/core/sequence.py 
103
104
105
106
107
def __repr__(self) -> str:
    """Return detailed representation."""
    return (
        f"Sequence(id='{self.id}', length={len(self)}, data='{self.data[:20]}...')"
    )
reverse_complement 
reverse_complement() -> Sequence

Calculate reverse complement of sequence.

Returns:

Type Description
New Sequence object with reverse complement.
Source code in src/pypopart/core/sequence.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
def reverse_complement(self) -> 'Sequence':
    """
    Calculate reverse complement of sequence.

    Returns
    -------
        New Sequence object with reverse complement.
    """
    rev_comp_data = ''.join(self.COMPLEMENT[base] for base in reversed(self.data))
    return Sequence(
        id=f'{self.id}_rev_comp',
        data=rev_comp_data,
        metadata=self.metadata.copy(),
        description=f'Reverse complement of {self.id}',
    )
gc_content 
gc_content() -> float

Calculate GC content as fraction (0.0-1.0).

Ignores gaps (-) and ambiguous characters (N, ?).

Returns:

Type Description
GC content fraction.
Source code in src/pypopart/core/sequence.py 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def gc_content(self) -> float:
    """
    Calculate GC content as fraction (0.0-1.0).

    Ignores gaps (-) and ambiguous characters (N, ?).

    Returns
    -------
        GC content fraction.
    """
    # Count G, C, and S (which represents G or C)
    gc_count = sum(1 for base in self.data if base in 'GCS')
    # Count only ACGT bases (exclude gaps, ambiguous chars)
    total_count = sum(1 for base in self.data if base in 'ACGT')

    if total_count == 0:
        return 0.0
    return gc_count / total_count
count_gaps 
count_gaps() -> int

Count number of gap characters.

Returns:

Type Description
Number of gaps.
Source code in src/pypopart/core/sequence.py 
144
145
146
147
148
149
150
151
152
def count_gaps(self) -> int:
    """
    Count number of gap characters.

    Returns
    -------
        Number of gaps.
    """
    return self.data.count('-')
count_ambiguous 
count_ambiguous() -> int

Count number of ambiguous characters (N and ?).

Returns:

Type Description
Number of ambiguous characters.
Source code in src/pypopart/core/sequence.py 
154
155
156
157
158
159
160
161
162
def count_ambiguous(self) -> int:
    """
    Count number of ambiguous characters (N and ?).

    Returns
    -------
        Number of ambiguous characters.
    """
    return sum(1 for base in self.data if base in 'N?')
remove_gaps 
remove_gaps() -> Sequence

Create new sequence with gaps removed.

Returns:

Type Description
New Sequence object without gaps.
Source code in src/pypopart/core/sequence.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
def remove_gaps(self) -> 'Sequence':
    """
    Create new sequence with gaps removed.

    Returns
    -------
        New Sequence object without gaps.
    """
    ungapped_data = self.data.replace('-', '')
    return Sequence(
        id=self.id,
        data=ungapped_data,
        metadata=self.metadata.copy(),
        description=self.description,
    )
slice 
slice(start: int, end: Optional[int] = None) -> Sequence

Extract a slice of the sequence.

Returns:

Type Description
New Sequence object with sliced data.
Source code in src/pypopart/core/sequence.py 
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
def slice(self, start: int, end: Optional[int] = None) -> 'Sequence':
    """
        Extract a slice of the sequence.

    Parameters
    ----------
        start :
            Start position (0-based, inclusive).
        end :
            End position (0-based, exclusive), None for end of sequence.

    Returns
    -------
        New Sequence object with sliced data.
    """
    sliced_data = self.data[start:end]
    slice_desc = f'slice[{start}:{end if end else "end"}]'
    return Sequence(
        id=f'{self.id}_{slice_desc}',
        data=sliced_data,
        metadata=self.metadata.copy(),
        description=f'Slice {slice_desc} of {self.id}',
    )
to_dict 
to_dict() -> Dict[str, Any]

Convert sequence to dictionary representation.

Returns:

Type Description
Dictionary with sequence data and statistics.
Source code in src/pypopart/core/sequence.py 
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
def to_dict(self) -> Dict[str, Any]:
    """
    Convert sequence to dictionary representation.

    Returns
    -------
        Dictionary with sequence data and statistics.
    """
    return {
        'id': self.id,
        'data': self.data,
        'metadata': self.metadata,
        'description': self.description,
        'length': len(self),
        'gc_content': self.gc_content(),
        'gaps': self.count_gaps(),
        'ambiguous': self.count_ambiguous(),
    }
from_dict classmethod 
from_dict(data: Dict[str, Any]) -> Sequence

Create sequence from dictionary.

Returns:

Type Description
New Sequence object.
Source code in src/pypopart/core/sequence.py 
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'Sequence':
    """
        Create sequence from dictionary.

    Parameters
    ----------
        data :
            Dictionary with sequence information.

    Returns
    -------
        New Sequence object.
    """
    return cls(
        id=data['id'],
        data=data['data'],
        metadata=data.get('metadata', {}),
        description=data.get('description'),
    )