From 428da9c69842a724e024a1efeeb94ff5c1ae5275 Mon Sep 17 00:00:00 2001 From: Nils Homer Date: Fri, 10 Jan 2025 19:43:46 -0700 Subject: [PATCH] adding some more docs --- pybwa/libbwaaln.pyx | 13 +++++++++++-- pybwa/libbwaindex.pyx | 2 +- pybwa/libbwamem.pyx | 15 +++++++++++++-- 3 files changed, 25 insertions(+), 5 deletions(-) diff --git a/pybwa/libbwaaln.pyx b/pybwa/libbwaaln.pyx index ba495b8..19e164f 100644 --- a/pybwa/libbwaaln.pyx +++ b/pybwa/libbwaaln.pyx @@ -33,6 +33,7 @@ cdef class BwaAlnOptions: free(self._delegate) cdef gap_opt_t* gap_opt(self): + """Returns the options struct to use with the bwa C library methods""" return self._delegate property max_mismatches: @@ -138,6 +139,14 @@ cdef class BwaAln: cdef BwaIndex _index def __init__(self, prefix: str | Path | None = None, index: BwaIndex | None = None): + """Constructs the :code:`bwa aln` aligner. + + One of `prefix` or `index` must be specified. + + Args: + prefix: the path prefix for the BWA index (typically a FASTA) + index: the index to use + """ if prefix is not None: assert Path(prefix).exists() self._index = BwaIndex(prefix=prefix) @@ -148,7 +157,6 @@ cdef class BwaAln: bwase_initialize() - # TODO: a list of records... def align(self, queries: List[FastxRecord] | List[str], opt: BwaAlnOptions | None = None) -> List[AlignedSegment]: """Align one or more queries with `bwa aln`. @@ -157,7 +165,8 @@ cdef class BwaAln: opt: the alignment options, or None to use the default options Returns: - one alignment per query + one alignment (:class:`~pysam.AlignedSegment`) per query + :code:`List[List[AlignedSegment]]`. """ if len(queries) == 0: return [] diff --git a/pybwa/libbwaindex.pyx b/pybwa/libbwaindex.pyx index 86144ff..aefd3c2 100644 --- a/pybwa/libbwaindex.pyx +++ b/pybwa/libbwaindex.pyx @@ -41,7 +41,7 @@ cdef class BwaIndex: with :code:`samtools dict `). Args: - prefix (str | Path): the path prefix for teh BWA index + prefix (str | Path): the path prefix for the BWA index (typically a FASTA) bwt (bool): load the BWT (FM-index) bns (bool): load the BNS (reference sequence metadata) pac (bool): load the PAC (the actual 2-bit encoded reference sequences with 'N' converted to a diff --git a/pybwa/libbwamem.pyx b/pybwa/libbwamem.pyx index 8e1f68a..5b27140 100644 --- a/pybwa/libbwamem.pyx +++ b/pybwa/libbwamem.pyx @@ -38,7 +38,9 @@ cdef class BwaMemOptions: def _assert_not_finalized(self, attr_name: str) -> None: """Raises an AttributeError if the options have been finalized. - This is used in each setter below, as cython does not support decorating properties. + This is used in each setter below to enforce that setters are not used after + :meth:`~pybwa.BwaMemOptions.finalize` is called. This could be a property decorator, + but cython does not support decorating properties. """ if self._finalized: raise AttributeError(f"can't set attribute: {attr_name}") @@ -547,6 +549,14 @@ cdef class BwaMem: cdef BwaIndex _index def __init__(self, prefix: str | Path | None = None, index: BwaIndex | None = None): + """Constructs the :code:`bwa mem` aligner. + + One of `prefix` or `index` must be specified. + + Args: + prefix: the path prefix for the BWA index (typically a FASTA) + index: the index to use + """ if prefix is not None: assert Path(prefix).exists() self._index = BwaIndex(prefix=prefix) @@ -564,7 +574,8 @@ cdef class BwaMem: opt: the alignment options, or None to use the default options Returns: - one alignment per query + a list of alignments (:class:`~pysam.AlignedSegment`) per query + :code:`List[List[AlignedSegment]]`. """ if opt is None: opt = BwaMemOptions().finalize()