Skip to content

Sequence operations

Importing polars_bio registers a seq namespace on every Polars expression. See Sequence operations for usage and the reference tools each function matches.

Sequence operations, available as pl.col(...).seq.

Source code in polars_bio/seq.py
@pl.api.register_expr_namespace("seq")
class SequenceExpr:
    """Sequence operations, available as ``pl.col(...).seq``."""

    def __init__(self, expr: pl.Expr):
        self._expr = expr

    def revcomp(self, alphabet: str = "dna", strict: bool = False) -> pl.Expr:
        """Reverse complement.

        Parameters:
            alphabet: ``"dna"`` pairs A with T (and U with A); ``"rna"`` pairs
                A with U.
            strict: Raise ``ComputeError`` on the first byte outside
                ``ACGTURYSWKMBDHVN`` (either case) instead of copying it.

        Example:
            ```python
            import polars as pl
            import polars_bio  # registers .seq

            pl.DataFrame({"s": ["ACGTN", None, "aacc"]}).select(
                pl.col("s").seq.revcomp()
            )  # ["NACGT", None, "ggtt"]
            ```
        """
        return _plugin(
            "revcomp",
            self._expr,
            alphabet=_choice("alphabet", alphabet, _ALPHABETS),
            strict=_flag("strict", strict),
        )

    def reverse(self) -> pl.Expr:
        """Reverse a string, for example a FASTQ quality alongside :meth:`revcomp`.

        Equivalent to ``str.reverse()`` for sequence and quality data, but
        much faster: it reverses ASCII bytes directly instead of Unicode
        grapheme clusters. A multi-byte character is kept whole.

        Example:
            ```python
            import polars as pl
            import polars_bio as pb  # registers .seq

            pb.scan_fastq("reads.fastq.gz").with_columns(
                sequence=pl.col("sequence").seq.revcomp(),
                quality_scores=pl.col("quality_scores").seq.reverse(),
            )
            ```
        """
        return _plugin("reverse", self._expr)

    def complement(self, alphabet: str = "dna", strict: bool = False) -> pl.Expr:
        """Complement, without reversing. Same rules as :meth:`revcomp`."""
        return _plugin(
            "complement",
            self._expr,
            alphabet=_choice("alphabet", alphabet, _ALPHABETS),
            strict=_flag("strict", strict),
        )

    def gc_content(self, denominator: str = "length") -> pl.Expr:
        """GC fraction between 0 and 1, as Float64.

        Counts G and C in either case (not S, like every reference tool).

        Parameters:
            denominator: ``"length"`` divides by the full sequence length in
                bytes (seqkit ``fx2tab -B GC``, seqkit ``stats``, seqfu);
                ``"acgt"`` divides by the count of A, C, G and T only
                (seqkit ``fx2tab -g``). A zero denominator gives null.
        """
        return _plugin(
            "gc_content",
            self._expr,
            denominator=_choice("denominator", denominator, _DENOMINATORS),
        )

    def translate(
        self, frame: int = 1, table: int = 1, to_stop: bool = False
    ) -> pl.Expr:
        """Translate nucleotides to amino acids.

        A trailing partial codon is dropped and stops are ``*``. An ambiguous
        codon gives an amino acid only when every base it can stand for
        agrees, otherwise ``X``. Three gap characters give ``-``; any other
        unreadable codon gives ``X``.

        Parameters:
            frame: 1, 2 or 3, or -1, -2, -3 to read the reverse complement.
            table: NCBI translation table id.
            to_stop: End the protein before the first stop codon.
        """
        return _plugin(
            "translate",
            self._expr,
            frame=_int("frame", frame, allowed=_FRAMES),
            table=_int("table", table, allowed=_CODON_TABLES),
            to_stop=_flag("to_stop", to_stop),
        )

    def mean_quality(self, offset: int = 33, method: str = "error_prob") -> pl.Expr:
        """Mean Phred quality of a quality string, as Float64.

        Parameters:
            offset: Phred offset, 33 (Sanger/Illumina 1.8+) or 64. A byte
                below it raises ``ComputeError``.
            method: ``"error_prob"`` averages the error probabilities and
                converts back, ``-10ยทlog10(mean(10^(-Q/10)))``, as seqkit
                does; ``"arithmetic"`` averages the Phred scores, as FastQC
                does. An empty string gives null.
        """
        return _plugin(
            "mean_quality",
            self._expr,
            offset=_int("offset", offset, lo=0, hi=255),
            method=_choice("method", method, _QUALITY_METHODS),
        )

revcomp(alphabet='dna', strict=False)

Reverse complement.

Parameters:

Name Type Description Default
alphabet str

"dna" pairs A with T (and U with A); "rna" pairs A with U.

'dna'
strict bool

Raise ComputeError on the first byte outside ACGTURYSWKMBDHVN (either case) instead of copying it.

False
Example
import polars as pl
import polars_bio  # registers .seq

pl.DataFrame({"s": ["ACGTN", None, "aacc"]}).select(
    pl.col("s").seq.revcomp()
)  # ["NACGT", None, "ggtt"]
Source code in polars_bio/seq.py
def revcomp(self, alphabet: str = "dna", strict: bool = False) -> pl.Expr:
    """Reverse complement.

    Parameters:
        alphabet: ``"dna"`` pairs A with T (and U with A); ``"rna"`` pairs
            A with U.
        strict: Raise ``ComputeError`` on the first byte outside
            ``ACGTURYSWKMBDHVN`` (either case) instead of copying it.

    Example:
        ```python
        import polars as pl
        import polars_bio  # registers .seq

        pl.DataFrame({"s": ["ACGTN", None, "aacc"]}).select(
            pl.col("s").seq.revcomp()
        )  # ["NACGT", None, "ggtt"]
        ```
    """
    return _plugin(
        "revcomp",
        self._expr,
        alphabet=_choice("alphabet", alphabet, _ALPHABETS),
        strict=_flag("strict", strict),
    )

reverse()

Reverse a string, for example a FASTQ quality alongside :meth:revcomp.

Equivalent to str.reverse() for sequence and quality data, but much faster: it reverses ASCII bytes directly instead of Unicode grapheme clusters. A multi-byte character is kept whole.

Example
import polars as pl
import polars_bio as pb  # registers .seq

pb.scan_fastq("reads.fastq.gz").with_columns(
    sequence=pl.col("sequence").seq.revcomp(),
    quality_scores=pl.col("quality_scores").seq.reverse(),
)
Source code in polars_bio/seq.py
def reverse(self) -> pl.Expr:
    """Reverse a string, for example a FASTQ quality alongside :meth:`revcomp`.

    Equivalent to ``str.reverse()`` for sequence and quality data, but
    much faster: it reverses ASCII bytes directly instead of Unicode
    grapheme clusters. A multi-byte character is kept whole.

    Example:
        ```python
        import polars as pl
        import polars_bio as pb  # registers .seq

        pb.scan_fastq("reads.fastq.gz").with_columns(
            sequence=pl.col("sequence").seq.revcomp(),
            quality_scores=pl.col("quality_scores").seq.reverse(),
        )
        ```
    """
    return _plugin("reverse", self._expr)

complement(alphabet='dna', strict=False)

Complement, without reversing. Same rules as :meth:revcomp.

Source code in polars_bio/seq.py
def complement(self, alphabet: str = "dna", strict: bool = False) -> pl.Expr:
    """Complement, without reversing. Same rules as :meth:`revcomp`."""
    return _plugin(
        "complement",
        self._expr,
        alphabet=_choice("alphabet", alphabet, _ALPHABETS),
        strict=_flag("strict", strict),
    )

gc_content(denominator='length')

GC fraction between 0 and 1, as Float64.

Counts G and C in either case (not S, like every reference tool).

Parameters:

Name Type Description Default
denominator str

"length" divides by the full sequence length in bytes (seqkit fx2tab -B GC, seqkit stats, seqfu); "acgt" divides by the count of A, C, G and T only (seqkit fx2tab -g). A zero denominator gives null.

'length'
Source code in polars_bio/seq.py
def gc_content(self, denominator: str = "length") -> pl.Expr:
    """GC fraction between 0 and 1, as Float64.

    Counts G and C in either case (not S, like every reference tool).

    Parameters:
        denominator: ``"length"`` divides by the full sequence length in
            bytes (seqkit ``fx2tab -B GC``, seqkit ``stats``, seqfu);
            ``"acgt"`` divides by the count of A, C, G and T only
            (seqkit ``fx2tab -g``). A zero denominator gives null.
    """
    return _plugin(
        "gc_content",
        self._expr,
        denominator=_choice("denominator", denominator, _DENOMINATORS),
    )

translate(frame=1, table=1, to_stop=False)

Translate nucleotides to amino acids.

A trailing partial codon is dropped and stops are *. An ambiguous codon gives an amino acid only when every base it can stand for agrees, otherwise X. Three gap characters give -; any other unreadable codon gives X.

Parameters:

Name Type Description Default
frame int

1, 2 or 3, or -1, -2, -3 to read the reverse complement.

1
table int

NCBI translation table id.

1
to_stop bool

End the protein before the first stop codon.

False
Source code in polars_bio/seq.py
def translate(
    self, frame: int = 1, table: int = 1, to_stop: bool = False
) -> pl.Expr:
    """Translate nucleotides to amino acids.

    A trailing partial codon is dropped and stops are ``*``. An ambiguous
    codon gives an amino acid only when every base it can stand for
    agrees, otherwise ``X``. Three gap characters give ``-``; any other
    unreadable codon gives ``X``.

    Parameters:
        frame: 1, 2 or 3, or -1, -2, -3 to read the reverse complement.
        table: NCBI translation table id.
        to_stop: End the protein before the first stop codon.
    """
    return _plugin(
        "translate",
        self._expr,
        frame=_int("frame", frame, allowed=_FRAMES),
        table=_int("table", table, allowed=_CODON_TABLES),
        to_stop=_flag("to_stop", to_stop),
    )

mean_quality(offset=33, method='error_prob')

Mean Phred quality of a quality string, as Float64.

Parameters:

Name Type Description Default
offset int

Phred offset, 33 (Sanger/Illumina 1.8+) or 64. A byte below it raises ComputeError.

33
method str

"error_prob" averages the error probabilities and converts back, -10ยทlog10(mean(10^(-Q/10))), as seqkit does; "arithmetic" averages the Phred scores, as FastQC does. An empty string gives null.

'error_prob'
Source code in polars_bio/seq.py
def mean_quality(self, offset: int = 33, method: str = "error_prob") -> pl.Expr:
    """Mean Phred quality of a quality string, as Float64.

    Parameters:
        offset: Phred offset, 33 (Sanger/Illumina 1.8+) or 64. A byte
            below it raises ``ComputeError``.
        method: ``"error_prob"`` averages the error probabilities and
            converts back, ``-10ยทlog10(mean(10^(-Q/10)))``, as seqkit
            does; ``"arithmetic"`` averages the Phred scores, as FastQC
            does. An empty string gives null.
    """
    return _plugin(
        "mean_quality",
        self._expr,
        offset=_int("offset", offset, lo=0, hi=255),
        method=_choice("method", method, _QUALITY_METHODS),
    )

SQL functions

The same kernels are available in pb.sql as scalar functions. Optional arguments are positional constants.

Function Optional arguments Returns
seq_revcomp(seq) alphabet = 'dna', strict = false the input's string type
seq_reverse(seq) โ€” the input's string type
seq_complement(seq) alphabet = 'dna', strict = false the input's string type
seq_gc_content(seq) denominator = 'length' DOUBLE
seq_translate(seq) frame = 1, table = 1, to_stop = false the input's string type
seq_mean_quality(qual) offset = 33, method = 'error_prob' DOUBLE