Skip to content

improve app docstring generation for decorated functions #2004

@GavinHuttley

Description

@GavinHuttley

we should provide advice to developers to NOT include a parameter listing of the first argument to a function that is decorated with define_app. It's confusing to users.

Alternately, is there a way to strip that out?

For example

import cogent3

cogent3.app_help("cogent3_score")

produces

Overview
--------
returns the cogent3 log-likelihood as an alignment quality score

Options for making the app
--------------------------
cogent3_score_app = get_app('cogent3_score', *args, **kwargs)

    Parameters
    ----------
    aln
An alignment instance.

    Returns
    -------
    returns the log-likelihood, or 0.0 if the alignment does not have the
    score

    Notes
    -----
    The cogent3 tree_align algorithm is a progressive-HMM. It records
    the log-likelihood of the alignment (in addition to all other
    the parameter values, including the guide tree) in
    ``alignment.info['align_params']``. This can be used as a measure of
    alignment quality.

    The instance must have been aligned using cogent3 tree_align. In addition,
    if the alignment has been saved, it has must have been serialised
    using a format that preserves the score.

    Examples
    --------

    Prepare an alignment of BRCA1 genes from 4 species. Create an unaligned
    sequence collection, guide tree, and an app for alignment using cogent3
    ``progressive_align()``.

    >>> from cogent3 import make_unaligned_seqs, get_app
    >>> aln = make_unaligned_seqs(
    ...     {
    ...         "Human": "GCCAGCTCATTACAGCATGAGAACAGCAGTTTATTACTCACT",
    ...         "Bandicoot": "NACTCATTAATGCTTGAAACCAGCAGTTTATTGTCCAAC",
    ...         "Rhesus": "GCCAGCTCATTACAGCATGAGAACAGTTTGTTACTCACT",
    ...         "FlyingFox": "GCCAGCTCTTTACAGCATGAGAACAGTTTATTATACACT",
    ...     },
    ...     moltype="dna",
    ... )
    >>> newick = "(Bandicoot:0.4,FlyingFox:0.05,(Rhesus:0.06,Human:0.0):0.04);"
    >>> aligner = get_app("progressive_align", model="HKY85")

    Create a composable app that aligns the sequences and returns the
    cogent3 log-likelihood alignment score.

    >>> scorer = get_app("cogent3_score")
    >>> app = aligner + score
    >>> result = app(aln)
    >>> print(result)
    -130.47375615734916

Input type
----------
Alignment, ArrayAlignment

Output type
-----------
float

The parameters section in this case is unecessary and screws up the rest of the formatting.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions