docs: advanced use case — per-sample BED refined with mosdepth coverage

[dlopez-bioinfo]

Motivación

El criterio actual para considerar una muestra como homocigoto referencia en una posición es que dicha posición esté dentro del BED de captura asignado a su tecnología (src/afquery/query.py:178, _compute_eligible). Esto es una aproximación cohorte-técnica: asume que todas las muestras de la misma tecnología tienen cobertura real en las regiones del BED.

En la práctica, muestras individuales pueden tener huecos de cobertura dentro del BED teórico (reads fallidas, regiones de baja complejidad, sesgos de captura). Contar esas posiciones como hom-ref infla AN y subestima AF.

Existe una forma de obtener control total por muestra sin modificar afquery: generar, para cada muestra, un BED refinado por cobertura real con mosdepth, y declarar cada muestra como su propia "tecnología" en el manifest apuntando a ese BED. De este modo, la lógica de elegibilidad existente (CaptureIndex.covers) ya resuelve el problema.

Esta issue propone documentar ese flujo como caso de uso avanzado.

Propuesta

Añadir un nuevo documento en docs/use-cases/ (p. ej. coverage-refined-bed.md) que explique el flujo completo.

Estructura sugerida del documento

1. Problem statement — por qué el BED de captura nominal puede ser demasiado optimista para hom-ref, con ejemplo numérico del sesgo en AF.
2. Solución: BED por muestra refinado por cobertura — cada muestra actúa como su propia tecnología; su BED es la intersección del BED de captura nominal con las regiones donde su BAM/CRAM tiene cobertura ≥ umbral.
3. Preprocesado con mosdepth — comando de referencia:

   mosdepth \
     --by capture.bed \
     --thresholds 10 \
     --no-per-base \
     -t 4 \
     sample_001 sample_001.bam

   y cómo derivar el BED filtrado a partir del output (--quantize o filtrado de *.regions.bed.gz / *.thresholds.bed.gz).
4. Construcción del manifest — una tecnología por muestra (tech_name = sample_001, etc.), cada una apuntando a su BED refinado en --bed-dir. Incluir advertencia sobre el impacto en el número de entradas en technologies y el tamaño de los interval trees en memoria.
5. Ejecución de afquery create-db — sin cambios respecto al flujo estándar; el soporte para N tecnologías ya existe.
6. Validación — consultas de verificación para confirmar que AN se reduce en posiciones esperadas, y comparativa AF antes/después.
7. Trade-offs:
   • Pros: control total, exactitud máxima de hom-ref sin cambios en el core.
   • Contras: coste de ingesta (mosdepth por muestra), BD con muchas tecnologías, mayor uso de memoria por los interval trees, ingesta más lenta.
8. Cuándo usarlo: cohortes donde la precisión de AF es crítica (ACMG BA1/PM2, asociación caso-control, etc.) y se dispone de BAM/CRAM accesibles.

Integración con el resto de la documentación

• Enlazar desde docs/use-cases/technology-integration.md como variante avanzada (una tecnología por muestra).
• Enlazar desde docs/advanced/pipeline-integration.md como paso opcional de preprocesado.
• Añadir entrada en mkdocs.yml bajo Advanced o Clinical Workflows (a decidir durante la implementación).

Referencias

• Issue feat: customizable homozygous reference sample selection #28 — estudio de alternativas para customizar hom-ref en el core de afquery (esta vía externa es complementaria a lo que se decida allí).
• mosdepth — cálculo rápido de profundidad por región.