Per-unit analyses

PerUnitAnalysis applies a calculation independently to each analysis unit. Each unit can produce zero or more results. run preserves input order with either worker threads or processes.

class ASOkai.Analysis.PerUnitAnalysis

Bases: Analysis

Analyze each unit independently and return results in input order.

One worker runs directly; multiple workers use threads by default. Set uses_worker_processes in a subclass to use forked processes on Linux when the parent has one Python thread and is not itself a multiprocessing worker. Other cases use threads. The parent runs one process-backed analysis at a time so each pool inherits the correct data.

Forked workers inherit the analysis and units through copy-on-write memory. Tasks send only index ranges; results are serialized back to the parent and must be picklable. Analyses must treat context and units as read-only while workers run. Open database connections and other stateful handles in a worker before using them, rather than reusing inherited ones.

uses_worker_processes: ClassVar[bool] = False

Prefer forked processes when supported; otherwise use threads.

worker_chunk_size: ClassVar[int | None] = None

Units per process task, or None to derive a chunk size.

target_tasks_per_worker: ClassVar[int] = 512

Target tasks per process when deriving a chunk size.

show_progress: ClassVar[bool] = True

Show a progress bar while running, on a terminal.

final run(units, *, n_workers=1)

Collect zero or more results per unit in input order.

Parameters:

• units (Iterable[Any])

• n_workers (int)

Return type:

list[Any]

final stream(units, *, n_workers=1)

Yield results in input order as the workers produce them.

Holding the results in an iterator keeps an analysis that returns far more results than units from collecting all of them in memory. The workers stay alive for as long as this context is open, so consume the iterator inside it, and consume it fully to run every unit.

Parameters:

• units (Iterable[Any])

• n_workers (int)

Return type:

Generator[Iterator[Any], None, None]

chunk_size(n_units, n_workers)

Return how many units each worker task receives.

Parameters:

• n_units (int)

• n_workers (int)

Return type:

int

abstractmethod analyze_unit(unit, /)

Return zero or more results for one analysis unit.

Parameters:

unit (Any)

Return type:

Iterable[Any]

class ASOkai.Analysis.IntrinsicFeaturesAnalysis(features=None)

Bases: PerUnitAnalysis

Analyzes intrinsic features for each target site.

Available features:

• GC_content: The proportion of Guanine (G) and Cytosine (C) bases (between 0 and 1).

• AT_content: The proportion of Adenine (A) and Thymine (T) bases (between 0 and 1).

• T_count: The count of Thymine (T) bases.

• CpG_count: The total count of CpG dinucleotides (a Cytosine followed by a Guanine).

• T_content: The proportion of Thymine (T) bases (between 0 and 1).

• CpG_content: CpG count divided by sequence length (between 0 and 1).

Parameters:

features (Iterable[str] | None)

analysis_unit_type: ClassVar[Literal['site', 'therapeutic', 'binding']] = 'site'

supported_features: ClassVar[tuple[str, ...]] = ('GC_content', 'AT_content', 'T_count', 'CpG_count', 'T_content', 'CpG_content')

analyze_unit(site)

Calculate the selected intrinsic features for one site.

Returns:

One complete row containing the site ID and selected features.

Parameters:

site (Site)

Return type:

list[dict[str, str | int | float | bool | None]]

Similar sequences

SimilarSequenceAnalysis searches each target site for sequences that the site’s own gapmer still binds. See Identify potential repeated sites for the search, its identifiers, and its output.

class ASOkai.Analysis.SimilarSequenceAnalysis(left_wing_length, gap_length, right_wing_length, *, max_ddg=5.0, ddg_tolerance=0.5, model_settings=None, energy_parameters=None, energy_parameter_file=None)

Bases: PerUnitAnalysis

Search each target site for sequences its own antisense strand binds.

Every site is searched against the reverse complement of that site, which is the antisense strand of the gapmer designed for it. The search mutates only positions outside the gapmer’s central gap, one position per tree level, and tries every nucleotide there. The gap’s base pairs are enforced while folding, so every sequence is scored in the alignment the gapmer must form. A sequence is reported when its binding energy loss stays within max_ddg, and is explored further while the loss stays within max_ddg + ddg_tolerance, because a later substitution can restore binding. Every other branch is pruned.

A reported sequence is only a potential repeated site. It becomes a repeated site once a later step finds it in a reference.

ViennaRNA holds the interpreter lock while folding, so the search runs on worker processes.

Parameters:

• left_wing_length (int)

• gap_length (int)

• right_wing_length (int)

• max_ddg (float)

• ddg_tolerance (float)

• model_settings (Mapping[str, Any] | None)

• energy_parameters (str | None)

• energy_parameter_file (str | Path | None)

analysis_unit_type: ClassVar[Literal['site', 'therapeutic', 'binding']] = 'site'

uses_worker_processes: ClassVar[bool] = True

Prefer forked processes when supported; otherwise use threads.

analyze_unit(site)

Search one target site for the sequences its gapmer still binds.

Returns:

The unmutated site first, then every distinct sequence ordered by binding-energy loss, each as its identifier and its sequence.

Parameters:

site (Site)

Return type:

list[tuple[str, str]]