Skip to main content
`Ctrl`+`K`

# 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.