fix: external metadata loading and geojson tracking

[NazimMechkouri]

What & why

Geojson validity check & metadata re-formatting/checks for tsv external celltype annotation

Geojson : Add a validity check for region-annotation GeoJSONs before they're consumed by the head blocks, so malformed/empty geometries fail early with a clear message instead of silently producing Unlabeled regions.

metadata :
External cell-type annotation TSVs were being read but never matched, so every cell fell through to Unannotated. Two root causes, both fixed:

1 - Contract key mismatch. In the Xenium5k and Atera heads, the zarr table kept the real cell_id in a column while obs_names stayed a positional integer index. Since every downstream join keys on obs_names, external annotation, region mapping and niche joins matched nothing. The heads now enforce obs_names == obs['cell_id'] (duplicate-safe).

2 - Ragged metadata format. The external TSVs had a 2-name header over 3 data columns (suffixed_id · cell_id · label), so pandas indexed on the suffixed ID, which never matches the plain cell_id. A new helper rewrites each metadata_{sample}.tsv into the 2-column shape annotate_cells expects (barcode label), re-keying on the plain cell_id; correct files pass through unchanged. Originals are backed up write-once to a sibling original_metadata/, and files are rewritten in place. Runs per sample from prepare_input_x5k / prepare_input_ate (no-op when external annotation is off or absent).

Changes
workflow/scripts/normalize_external_metadata.py : new: per-sample metadata normalizer (backup + in-place rewrite, idempotent) with a standalone CLI for one-off directory passes.
workflow/scripts/prepare_input_x5k.py, workflow/scripts/prepare_input_ate.py : enforce obs_names == cell_id; call the normalizer per sample after the contract is written.
(geojson: list the file(s) you changed for the validity check)

Validation

• Workflow lint passes against .test/
• Decoupled .test/ dry-run builds the CoreBlock DAG
• Affected HeadBlock mode was dry-run with a complete mode-specific config and representative inputs, if applicable
• Config validates against workflow/schemas/config.schema.yaml
• mkdocs build --strict passes, if documentation was changed
• Catalogue rule graph was generated before a release, if applicable
• Parameter names match between .smk rules and scripts; documentation was updated if behaviour changed

[Sergio-ote]

Hi @NazimMechkouri, thanks for the help here! I reviewed PR #8 together with PR #9 and prepared a cleanup for PR #8.

The useful cell_id fix is retained, but external metadata is now read without rewriting the user’s files or dropping columns. This was unintended behaviour, not tracked by Snakemake. Metadata containing a separate cell_id column is supported, while empty or duplicate IDs fail explicitly.

GeoJSON validation is now a real dependency of the relevant head rules. It validates the original file, rejects unusable geometries, and writes only a validation report. It is wired upstream in the DAG so it is actually useful for validation.

I also removed PR #8’s pseudobulk wildcard changes so that PR #9 (an implementation I worked on while you were working on these features) remains the later owner of the expanded pseudobulk functionality.