foapy 0.0.20

Formal order analysis library

foapy

Python library for Formal Order Analysis (FOA) of symbolic sequences.

What is FOA?

Formal Order Analysis (FOA) studies the structure of symbolic sequences by:

• Mapping a sequence to its order and alphabet (the set of unique symbols in order of first appearance).
• Extracting intervals between repeated occurrences of the same symbol under different boundary modes.
• Quantifying structure with characteristics (e.g., arithmetic/geometric means, volume, average remoteness, depth, descriptive/identifying information, regularity, uniformity).

This enables robust analysis for text, biological sequences, musical motifs, logs, and any categorical time series.

Features

• Alphabets and Orders: Define alphabets and compute orders of sequences.
• Intervals and Chains: Extract intervals for multiple binding and boundary modes.
• Congeneric Decomposition: Decompose sequences into congeneric components.
• Mathematical Characteristics: Arithmetic mean, geometric mean, volume, average remoteness, depth, descriptive and identifying information, regularity, uniformity.
• Masked-array Support: FOA on partially observed sequences via foapy.ma.
• Extensive Documentation: Theory, algorithms, and examples.

Installation

• From PyPI:

pip install foapy

• From source (with tox workflows):

git clone https://github.com/intervals-mining-lab/foapy.git
cd foapy
python -m pip install --upgrade pip
python -m pip install tox

# Run tests (isolated env)
tox -e default

# Build distribution artifacts (sdist and wheel)
tox -e build

# Optionally clean build artifacts
tox -e clean

Quick start

Compute order, intervals, and a characteristic:

import foapy

# 1) Order and alphabet
source = ['a', 'b', 'a', 'c', 'd']
order = foapy.order(source)
print(order)  # [0 1 0 2 3]

order_arr, alphabet = foapy.order(source, True)
print(order_arr, alphabet)  # [0 1 0 2 3] ['a' 'b' 'c' 'd']

# 2) Intervals (binding to start, normal mode)
from foapy import binding, mode
intervals = foapy.intervals(['a', 'b', 'a', 'c', 'a', 'd'], binding.start, mode.normal)
print(intervals)  # [1 2 2 3 2 5]

# 3) A characteristic (volume = product of intervals)
val = foapy.characteristics.volume(intervals)
print(val)  # 192

Masked arrays (optional):

import numpy as np
import numpy.ma as ma
import foapy

seq = ma.masked_array(['a', 'b', 'a', 'c', 'd'], mask=[0, 1, 0, 0, 0])
order_ma = foapy.ma.order(seq)
intervals_grouped = foapy.ma.intervals(order_ma, foapy.binding.start, foapy.mode.normal)
u = foapy.characteristics.uniformity(intervals_grouped)
print(u)

Project Structure

• Source Code: ./src
• Documentation: ./docs
• Tests: ./tests

Documentation

Online documentation: intervals-mining-lab.github.io/foapy.

The documentation in ./docs covers fundamentals, algorithms, characteristics, applications, and development notes.

Build and serve the docs locally (via tox):

# Build docs into docs/_build
tox -e docs

# Serve docs with live-reload for development
tox -e docsserve

Testing

Run the test suite (via tox):

tox -e default

# Pass arguments to pytest after --, e.g. run a subset:
tox -e default -- -k order -q