smftools.preprocessing.preprocess_umi_annotations

smftools.preprocessing.preprocess_umi_annotations#

smftools.preprocessing.preprocess_umi_annotations(adata, umi_cols=('U1', 'U2'), combined_col='RX', expected_length=None, max_homopolymer_fraction=0.7, min_unique_bases=2, max_homopolymer_run=4, min_entropy=None, cluster_max_edit_distance=1, cluster_directional=True, sample_col='Barcode', reference_col='Reference_strand', cluster_within_groups=True, min_cluster_size=1, uns_flag='preprocess_umi_annotations_performed', bypass=False, force_redo=False)#

Preprocess UMI annotations: validate, filter, and cluster UMIs.

This function: 1. Validates each UMI (filters homopolymers, low complexity, Ns, wrong length) 2. Clusters valid UMIs by edit distance to correct sequencing errors 3. Assigns cluster IDs/consensus sequences 4. Adds cleaned columns to adata.obs

Return type:

AnnData

Parameters#

adataAnnData

AnnData object with UMI columns in obs.

umi_colsSequence[str]

Names of UMI columns to process (default: ["U1", "U2"]).

combined_colstr

Name of combined UMI column (default: "RX").

expected_lengthint, optional

Expected UMI length. If None, inferred from most common length.

max_homopolymer_fractionfloat

Maximum fraction of UMI that can be a single base (default 0.7).

min_unique_basesint

Minimum number of unique bases required (default 2).

max_homopolymer_runint

Maximum allowed homopolymer run length (default 4).

min_entropyfloat, optional

Minimum Shannon entropy (bits) for a UMI to be considered valid. When set, a UMI must pass both validate_umi() checks and have entropy >= min_entropy to be marked valid. Entropy is always computed and stored as {col}_entropy regardless of this setting.

cluster_max_edit_distanceint

Maximum edit distance for clustering UMIs (default 1).

cluster_directionalbool

Use directional clustering where high-count UMIs absorb low-count neighbors.

sample_colstr

Column name for sample/barcode grouping.

reference_colstr

Column name for reference/strand grouping.

cluster_within_groupsbool

If True, cluster UMIs separately within each sample/reference group.

min_cluster_sizeint

Minimum cluster size to keep (default 1, keep all).

uns_flagstr

Key in adata.uns to mark completion.

bypassbool

If True, skip processing entirely.

force_redobool

If True, rerun even if uns_flag is set.

Returns#

AnnData

Modified AnnData with new columns:

  • {umi_col}_entropy: float - Shannon entropy (bits)

  • {umi_col}_valid: bool - whether UMI passed validation

  • {umi_col}_invalid_reason: str - reason for invalidity

  • {umi_col}_cluster: str - clustered/corrected UMI

  • {umi_col}_cluster_size: int - size of the UMI cluster

  • {combined_col}_cluster: str - combined clustered UMI

  • {umi_col}_cluster_is_duplicate: bool - clustered UMI identity is non-unique within the (sample_col, reference_col) group

  • {combined_col}_cluster_is_duplicate: bool - combined clustered UMI identity is non-unique within the (sample_col, reference_col) group

  • any_umi_cluster_is_duplicate: bool - any cluster duplicate flag is True

  • umi_cluster_key: str - combined key for deduplication