Ctrl+K

Overview of cogent3 apps

8.8. Overview of cogent3 apps#

cogent3.apps can be though of as customised functions that have some special capabilities. The approach to using an existing app is to construct a configured instance, typically by calling the app with some argument values tuned for your particular case. You then apply it to input data by simply calling, without specifying any arguments.

There are quite a few apps and you can see an overview of what’s available as follows

from cogent3 import available_apps

apps = available_apps()

apps.head()
modulenamecomposabledocinput typeoutput type
cogent3.app.alignalign_to_refTrueAligns sequences to a nominated reference in the unaligned collection.SequenceCollectionAlignment, ArrayAlignment, SerialisableType
cogent3.app.evoancestral_statesTrueComputes ancestral state probabilities from a model result.model_resultSerialisableType, tabular_result
cogent3.app.distapprox_jc69TrueConverts p-distances and returns pairwise JC69 distancesDistanceMatrixDistanceMatrix
cogent3.app.distapprox_pdistTrueCalculates an approximation of the p-distance between sequences based on Jaccard distances (see Notes for details).DistanceMatrixDistanceMatrix
cogent3.app.evobootstrapTrueParametric bootstrap for a provided hypothesis.Alignment, ArrayAlignmentSerialisableType, bootstrap_result

Top 5 rows from 54 rows x 6 columns

That function returns a cogent3 table, so I’m just displaying the first few rows.

See the cogent3 apps documentation for more details.

8.9. Getting help on an app#

To get information on a particular app, use the special app_help() function, passing the name of the app as a string.

from cogent3 import app_help

app_help("model")

Overview
--------
Define a substitution model + tree for maximum likelihood evaluation.
Options for making the app
--------------------------
model_app = get_app(
    "model",
    sm,
    tree=None,
    unique_trees=False,
    tree_func=None,
    name=None,
    optimise_motif_probs=False,
    sm_args=None,
    lf_args=None,
    time_het=None,
    param_rules=None,
    opt_args=None,
    lower=1e-06,
    upper=50,
    split_codons=False,
    show_progress=False,
    verbose=False,
)

Parameters
----------
sm : str or instance
    substitution model if string must be available via get_model()
tree
    if None, assumes a star phylogeny (only valid for 3 taxa). Can be a
    newick formatted tree, a path to a file containing one, or a Tree
    instance.
unique_trees : bool
    whether to specify a unique tree per alignment. Only applies if
    number of sequences equals 3.
tree_func: callable
    a callable that takes an alignment and returns a Tree instance.
    Overrides tree and unique_tree settings.
name : str
    name of the model
optimise_motif_probs : bool
    whether the motif probabilities are free parameters. If False,
    takes the average of frequencies from the alignment. Overrides
    the setting of a sub model instance, or any value provided in
    sm_args.
sm_args : dict
    arguments to be passed to the substitution model constructor
lf_args : dict
    arguments to be passed to the likelihood function constructor
time_het
    Affects whether substitution model rate parameters are
    heterogeneous between branches on the tree. To define a maximally
    time-heterogeneous model, set the string value 'max', which
    makes all rate matrix exchangeability parameters unique for all
    edges. More restricted time-heterogeneity can be specified
    using a list of dicts corresponding to edge_sets, e.g.
    ``[dict(edges=['Human', 'Chimp'], is_independent=False, upper=10)]``.
    This value is passed to <likelihood function>.set_time_heterogeneity()
param_rules : list
    other parameter rules, passed to
    <likelihood function>.set_param_rule()
opt_args : dict
    arguments for the numerical optimiser, e.g.
    dict(max_restarts=5, tolerance=1e-6, max_evaluations=1000,
    limit_action='ignore')
lower, upper
    bounds for all rate and length parameters. Ignored if a
    rule in ``param_rules`` or ``time_het`` has a value defined.
split_codons : bool
    if True, incoming alignments are split into the 3 frames and each
    frame is fit separately
show_progress : bool
    show progress bars during numerical optimisation
verbose : bool
    prints intermediate states to screen during fitting

Returns
-------
Calling an instance with an alignment returns a model_result instance
with the optimised likelihood function. In the case of split_codons,
the result object has a separate entry for each codon position.

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

Output type
-----------
SerialisableType, model_result
Contents