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.

from cogent3.app.typing import defined_types

defined_types()

To use a type hint, from cogent3.app import typing
An app which uses one of these hints is compatible with the indicated types.
type hint	includes
UnionType	UnionType
AlignedSeqsType	Alignment
UnalignedSeqsType	SequenceCollection
SeqsCollectionType	Alignment, SequenceCollection
SeqType	ByteSequence, DnaSequence, ProteinSequence, ProteinWithStopSequence, RnaSequence, Sequence
PairwiseDistanceType	DistanceMatrix
TabularType	DictArray, DistanceMatrix, Table
TreeType	PhyloNode
BootstrapResultType	bootstrap_result
HypothesisResultType	hypothesis_result
ModelCollectionResultType	model_collection_result
ModelResultType	model_result
TabularResultType	tabular_result
GenericResultType	generic_result
ResultType	bootstrap_result, generic_result, hypothesis_result, model_result, tabular_result
SerialisableType	SerialisableType
IdentifierType	DataMemberABC, Path, str

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.

from scinexus.composable import define_app
from cogent3.app.typing import AlignedSeqsType

@define_app
def n_positions(val: AlignedSeqsType, n=2) -> AlignedSeqsType:
    return val[:n]

The critical elements are:

The define_app decorator is used.
Type hints are specified for the function’s first argument and its return type.

Defining a cogent3 app from a class#

from scinexus.composable import define_app
from cogent3.app.typing import AlignedSeqsType

@define_app
class n_positions:
    def __init__(self, n=2):
        self.n = n

    def main(self, val: AlignedSeqsType) -> AlignedSeqsType:
        return val[:self.n]

The critical elements are:

The define_app decorator is used.
The class has a main() method.
Type hints are specified for the main() method’s first argument and its return type.

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.

app = some_app()
app.citations

(Software(
     author=['Doe, J', 'Smith, A'],
     title='My Sequence Filter',
     year=2025,
     version='0.1.0',
     url='https://example.com/my-filter',
 ),)

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

print(app.bib)

@software{Doe.2025,
  author    = {Doe, J and Smith, A},
  title     = {My Sequence Filter},
  year      = {2025},
  version   = {0.1.0},
  url       = {https://example.com/my-filter},
}

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.

	0
a	GCAA
b	..TT

	0
a	GCAA
b	..TT