Writing your own apps#

The app infrastructure is provided by the scinexus package. See the scinexus documentation for full details on define_app, app types, handling NotCompleted, and citations.

Below are cogent3-specific examples showing how to write apps that work with cogent3 data types.

Available cogent3 types#

You can use existing type hints if your function takes or returns cogent3 types.

Note

You don’t have to use cogent3 types. You can also use standard Python types.

Defining a cogent3 app from a function#

We write a function that takes a cogent3 alignment and returns the first n positions.

The critical elements are:

  1. The define_app decorator is used.

  2. Type hints are specified for the function’s first argument and its return type.

Using the custom app

We create an app instance for a specific value of n.

The instance’s repr() indicates the wrapped function and the argument values. You use first4() like all composable apps, e.g.

Defining a cogent3 app from a class#

The critical elements are:

  1. The define_app decorator is used.

  2. The class has a main() method.

  3. Type hints are specified for the main() method’s first argument and its return type.

Using the custom app

This is identical to what we did above.

App naming conventions#

Use words in lower case separated by underscores (e.g. lower_case) to name your apps. Apps are callable, just like functions, and the PEP8 guidelines specify this naming style.

If you will make your app available on the Python package index, we recommend prefixing each app with your package name. For example, the piqtree2 library distributes apps with names such as piqtree_phylo.

See scinexus documentation for how to add a citation to your app.

How to get the citations for the apps you use#

Correctly attributing the authors of algorithms and software is a requirement of good scientific practice. The .citations property on an app instance returns its citations as a tuple.

You can get the BibTeX string directly via the .bib property.

Citations in a composed pipeline

When apps are composed into a pipeline, .citations collects unique citations from all apps in the chain.

The .bib property gives the combined BibTeX for the whole pipeline.

Note

When a composed pipeline is run via apply_to(), citations are automatically saved in the output data store. See data store citations for how to inspect and export them.