Marker roles and phase-specific routing

Marker roles let one marker table express different purposes for Phase 1 and Phase 2. The supported roles are:

presence

A Phase 1 marker used to detect whether a group is plausible.

identity

A Phase 2 marker used to distinguish a group from others.

positive

A normal positive marker. Missing or blank roles become positive.

negative

An anti-marker. Only UCell-like Phase 2 scoring directionally interprets negative markers.

Unknown role values raise an error. Negative direction is determined by marker_role, not by the sign of logfoldchanges. Signed values remain signed when they come from signed Scanpy inference.

Presence and identity roles are useful independently of UCell-like scoring. Non-UCell Phase 2 methods exclude negative rows rather than subtracting them. Shared and phase-specific routing are separate concepts from the selected Phase 2 scoring method.

Routing modes

marker_roles="shared"

The default. Without a role column, the same marker table is used for Phase 1 and Phase 2. With a role column, role-aware routing is applied.

marker_roles="phase_specific"

Phase 1 and Phase 2 use role-selected subsets. This is generated automatically only by reference-profile markers, unless you provide a manual role table.

Shared mode routing

Destination	Roles used
Phase 1	positive, presence, identity
UCell-like Phase 2	positive, identity, negative
Non-UCell Phase 2	positive, presence, identity

Phase-specific mode routing

Destination	Roles used
Phase 1	presence
UCell-like Phase 2	positive, identity, negative
Non-UCell Phase 2	positive, identity

For marker_roles="phase_specific", easydecon raises if no Phase 1 presence markers remain when Phase 1 is required, or if no Phase 2 identity-compatible markers remain.

Role generation

Reference-profile marker generation can produce presence, identity, and negative roles with marker_roles="phase_specific".

Scanpy and PyDESeq2 do not automatically generate phase-specific presence/identity roles. Provide a manual marker_role table if you need those roles with Scanpy or PyDESeq2 markers.

marker_role_inference="scanpy_signed" is a separate shared-mode feature for Scanpy-style signed rows. It creates only positive and negative roles and is useful when running the negative-marker-capable method="ucell". It does not create phase-specific presence/identity roles.

Top-N with roles

When roles are present, top_n_genes is applied per group and role during standardization or phase routing. This means positive and negative markers can both retain their own top rows.