Getting help on an app#

The app_help() function is a top-level import. It provides you with detailed help on an individual app. You pass the name of the app you want information on (see available apps) as a string. Below, I request help for the app omit_degenerates by passing that name as a string.

from cogent3 import app_help

app_help("omit_degenerates")
Overview
--------
Excludes alignment columns with degenerate characters. Can accomodate
reading frame.

Options for making the app
--------------------------
omit_degenerates_app = get_app(
    "omit_degenerates",
    moltype: Optional[str] = None,
    gap_is_degen: bool = True,
    motif_length: int = 1,
)

Parameters
----------
moltype : str
    molecular type, must be either DNA or RNA
gap_is_degen : bool
    include gap character in degenerate character set
motif_length : int
    sequences split into non-overlapping tuples of this size. If a
    tuple contains a degen character at any position the entire tuple
    is excluded

Examples
--------
Degenerate IUPAC base symbols represents a site position that can have
multiple possible nucleotides. For example, "Y" represents
pyrimidines where the site can be either "C" or "T".

Note: In molecular evolutionary and phylogenetic analyses, the gap
character "-" is considered to be any base "N".

Create sample data with degenerate characters

>>> from cogent3 import app_help, get_app, make_aligned_seqs
>>> aln = make_aligned_seqs({"s1": "ACGA-GACG", "s2": "GATGATGYT"}, moltype="dna")

Create an app that omits aligned columns containing a degenerate
character from an alignment

>>> app = get_app("omit_degenerates", moltype="dna")
>>> result = app(aln)
>>> print(result.to_pretty())
s1    ACGAGAG
s2    GATGTGT

Create an app which omits degenerate characters, but retains gaps

>>> app = get_app("omit_degenerates", moltype="dna", gap_is_degen=False)
>>> result = app(aln)
>>> print(result.to_pretty())
s1    ACGA-GAG
s2    GATGATGT

Split sequences into non-overlapping tuples of length 2 and exclude
any tuple that contains a degenerate character

>>> app = get_app("omit_degenerates", moltype="dna", motif_length=2)
>>> result = app(aln)
>>> print(result.to_pretty())
s1    ACGA
s2    GATG

A NotCompleted object (see https://cogent3.org/doc/app/not-completed.html)
is returned if the moltype is not specified in the alignment or app

>>> aln = make_aligned_seqs({"s1": "ACGA-GACG", "s2": "GATGATGYT"})
>>> app = get_app("omit_degenerates")
>>> result = app(aln)
>>> result.message
'Traceback...

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

Output type
-----------
SerialisableType, ArrayAlignment, Alignment

The resulting vignette has multiple of sections.

  1. “Overview” describes the app purpose.

  2. “Options for making the app” shows how to create an app instance using get_app() (Getting an app). It includes the positional and keyword arguments for the app.

  3. “Parameters” lists the documentation describing the arguments.

  4. “Input type” states what data types are acceptable as input to the app.

  5. “Output type” states what data type will be generated by the app.