Bgc Feature Vector Normalization

---
name: bgc-feature-vector-normalization
description: Use when when you have pre-computed BGC feature vectors (from domain
  architecture extraction) and need to cluster them into GCFs using BiG-SLiCE v2.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3432
  edam_topics:
  - http://edamontology.org/topic_0160
  - http://edamontology.org/topic_3373
  tools:
  - BiG-SLiCE
  - antiSMASH v7.0.0
  - PFAM 35.0
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1093/gigascience/giaa154
  title: BiG-SLiCE
evidence_spans: []
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_big_slice_cq
    doi: 10.1093/gigascience/giaa154
    title: BiG-SLiCE
  dedup_kept_from: coll_big_slice_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1093/gigascience/giaa154
  all_source_dois:
  - 10.1093/gigascience/giaa154
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# bgc-feature-vector-normalization

## Summary

Apply l2-normalization to BGC feature vectors to enable cosine-like distance computation during Gene Cluster Family (GCF) clustering in BiG-SLiCE v2. This preprocessing step transforms raw or pre-computed feature vectors into a normalized vector space where Euclidean distance approximates cosine similarity.

## When to use

When you have pre-computed BGC feature vectors (from domain architecture extraction) and need to cluster them into GCFs using BiG-SLiCE v2. The normalization is required specifically because BiG-SLiCE v2 replaced its distance metric with cosine-like distances via l2-normalization, making it incompatible with raw (unnormalized) feature vectors used in previous versions.

## When NOT to use

- Input feature vectors are already l2-normalized or were generated by a tool that applies its own normalization scheme — double normalization may distort the similarity structure.
- You are using BiG-SLiCE v1.x, which uses a different distance metric and does not require explicit l2-normalization as a preprocessing step.
- Feature vectors are categorical or binary domain presence/absence encodings rather than continuous-valued domain architecture scores — cosine-like distances may not be appropriate for sparse, discrete representations.

## Inputs

- Pre-computed BGC feature vectors (array or matrix format, normalized or raw)
- BGC identifiers (mapping to preserve BGC-to-vector correspondence)

## Outputs

- l2-normalized BGC feature vectors (unit-norm vectors)
- BGC-to-GCF mapping table (TSV with BGC identifier and GCF cluster ID columns)

## How to apply

Load all BGC feature vectors into memory. Apply l2-normalization to each vector by dividing each component by the vector's Euclidean norm (L2 norm), ensuring all vectors lie on the unit hypersphere. After normalization, Euclidean distance between any two normalized vectors approximates their cosine distance. Pass the normalized vectors to BiG-SLiCE v2's hierarchical or flat clustering algorithm, which will then assign each BGC to a GCF based on cosine-like distance thresholds. The rationale is that l2-normalized vectors preserve similarity structure in a scale-invariant manner, making domain architecture comparisons robust to differences in BGC size or domain count.

## Related tools

- **BiG-SLiCE** (Performs hierarchical or flat clustering on l2-normalized BGC feature vectors using cosine distance metric to assign BGCs to GCFs) — https://github.com/medema-group/bigslice
- **antiSMASH v7.0.0** (Extracts and annotates BGC domain architectures that serve as input for feature vector generation)
- **PFAM 35.0** (Provides pHMM database used by BiG-SLiCE to profile domains within BGCs)

## Evaluation signals

- Verify that all normalized vectors have Euclidean norm = 1.0 (within floating-point tolerance, typically ±1e-6)
- Confirm that cosine distances between normalized vectors are in the range [0, 2] (or [0, 1] if only computing similarity), as expected from the definition of cosine distance on the unit sphere
- Check that the BGC-to-GCF TSV output contains no missing BGC identifiers and that GCF cluster IDs are contiguous or sequential
- Validate that clustering results are reproducible across multiple runs with identical inputs (deterministic behavior)
- Cross-check that BGCs with similar domain architectures are assigned to the same or neighboring GCFs by manually inspecting a small sample of the output

## Limitations

- l2-normalization assumes feature vectors are continuous-valued and Euclidean; binary or categorical domain encodings may yield uninformative normalized vectors.
- Normalization erases absolute magnitudes of feature vectors; BGCs with very few domains and BGCs with many domains are treated equivalently if their domain ratios are similar.
- No changelog documented in the source material; the exact normalization formula and any special handling of zero vectors or sparse vectors in BiG-SLiCE v2 is not explicitly specified.
- Performance depends on the quality and coverage of the PFAM 35.0 HMM database; domains not in the database will be absent from feature vectors regardless of normalization.

## Evidence

- [intro] BiG-SLiCE v2 applies l2-normalization for cosine-like distance computation: "Clustering now uses __cosine-like__ (via l2-normalization) distances"
- [other] The workflow requires loading vectors, applying l2-norm, clustering, and exporting results: "1. Load pre-computed BGC feature vectors (normalized or raw) into memory. 2. Apply l2-normalization to all feature vectors to enable cosine-like distance computation. 3. Perform hierarchical or flat"
- [readme] TSV export capability for BGC-to-GCF mappings: "Ability to __export pre-calculated BGCs and GCFs table into TSVs__ (use __--export-csv__ parameter)"
- [other] Normalization replaces the distance metric used in previous versions: "replacing the distance metric used in previous versions"