¿Qué hace datalad?
Resumen
DataLad es una capa de gestión de datos sobre Git y git-annex. Git rastrea la estructura del conjunto de datos, los archivos de texto pequeños y el historial. git-annex rastrea el contenido de los archivos grandes, almacenando cada archivo como una clave y manteniendo los bytes en algún lugar que no es necesariamente el repositorio local.
Esa división es lo más importante a internalizar, porque significa que un conjunto de datos recién clonado contiene el historial completo y la lista completa de archivos, mientras contiene casi ninguno de los datos. Un conjunto de datos de 100 TB se clona en segundos y ocupa unos pocos megabytes. Los bytes llegan solo cuando se solicitan, por archivo, con datalad get.
Lo segundo que añade DataLad es procedencia. datalad run ejecuta un comando y confirma el resultado junto con un registro legible por máquina del comando, sus entradas y sus salidas. datalad rerun lee ese registro y lo re-ejecuta. Esto transforma "cómo se produjo esta figura" de un problema de arqueología a un comando.
Cuándo usar DataLad en lugar de Git simple
Use DataLad cuando se cumpla alguna de las siguientes condiciones:
- Los archivos son demasiado grandes para que Git los maneje cómodamente, o el total supera lo que cada colaborador desea tener en disco.
- Los datos residen en más de un lugar (un servidor de laboratorio, un clúster scratch, S3, un superordenador) y necesita saber qué copias existen.
- El análisis debe ser re-ejecutable, y un mensaje de commit simple no es suficiente evidencia.
- Está consumiendo conjuntos de datos publicados de OpenNeuro, DANDI o
datasets.datalad.org, que se distribuyen como conjuntos de datos de DataLad. - El proyecto anida otros conjuntos de datos dentro y desea que cada uno mantenga su propio historial independiente.
Use Git simple cuando el repositorio sea solo código y texto, todo quepa cómodamente en Git, y nadie necesite descargas parciales. DataLad sobre un repositorio pequeño de solo código añade indirección sin aportar nada.
Instalación
# git-annex NO está escrito en Python pero está disponible desde PyPI si ya tiene
# git instalado:
uv pip install git-annex
# También puede instalarlo primero desde el sistema
# (Debian/Ubuntu: apt install git-annex; macOS: brew install git-annex;
# conda-forge: conda install -c conda-forge git-annex)
uv pip install datalad
uv pip install datalad-container # solo para containers-run
datalad wtf --section dependencies # confirme que la versión de git-annex es visible
El paquete git-annex de PyPI envía el binario precompilado como una rueda para Linux, macOS y Windows en lugar de compilar las fuentes de Haskell, por lo que se instala como cualquier otra dependencia de Python y puede fijarse en el mismo entorno que DataLad. No incluye git consigo mismo.
datalad wtf imprime el entorno resuelto y es lo primero que debe ejecutar cuando el comportamiento parezca imposible. Una versión antigua o faltante de git-annex está detrás de una gran parte de los errores confusos.
DataLad en sí tiene licencia MIT. git-annex es una herramienta separada bajo AGPL, lo que importa solo si redistribuye un git-annex modificado en lugar de llamarlo.
El fallo que muerde primero: los punteros no son datos
Después de datalad clone, los archivos anexados existen como enlaces simbólicos a .git/annex/objects/ (o como pequeños archivos puntero donde los enlaces simbólicos no están disponibles, como en Windows o en un sistema de archivos incapacitado). Nada ha descargado el contenido todavía.
datalad clone https://github.com/OpenNeuroDatasets/ds000001.git
cd ds000001
ls sub-01/anat/ # el archivo está listado
python -c "import nibabel; nibabel.load('sub-01/anat/sub-01_T1w.nii.gz')" # falla
datalad get sub-01/anat/sub-01_T1w.nii.gz # ahora funciona
El modo de fallo a reconocer: una herramienta reporta el archivo como vacío, truncado, corrupto, "no es un archivo gzip" o un enlace simbólico roto, y el tamaño del archivo en disco es de unos pocos cientos de bytes. Eso es un puntero, no una descarga corrupta. Ejecute datalad get antes de leer datos y trate "el archivo existe" como evidencia insuficiente de que su contenido está presente.
Antes de que un análisis toque un directorio, obténgalo explícitamente:
datalad get sub-01/ # todo lo que está bajo una ruta
datalad get -r . # todo, incluidos subconjuntos de datos
datalad get -n -r . # solo estructura de subconjuntos, sin contenido de archivos
datalad status --annex reporta cuánto contenido está presente localmente, y git annex whereis <ruta> reporta qué repositorios contienen un archivo dado. whereis lee el estado registrado y no contacta a los remotos, por lo que le dice lo que git-annex aprendió por última vez, no lo que es verdad en este momento.
Consulte data-access.md para encontrar conjuntos de datos, comportamiento de subconjuntos, eliminar contenido de forma segura y reparar un conjunto de datos.
Registro de procedencia con datalad run
datalad run es la razón para recurrir a DataLad en un contexto de métodos. Guarda el comando junto con su efecto, en el mismo commit:
datalad run -m "extraer máscara cerebral" \
--input "sub-01/anat/sub-01_T1w.nii.gz" \
--output "derivatives/sub-01_brain.nii.gz" \
"bet {inputs} {outputs} -m"
Qué hace cada parte y por qué omitirla duele:
--inputrecupera el contenido antes de ejecutar, para que el comando no falle en un puntero. También registra la dependencia, que es lo que permite quererunobtenga las mismas entradas en una máquina diferente.--outputdesbloquea o elimina el destino primero, para que git-annex no se niegue a sobrescribir contenido que está protegiendo. Sin esto, una segunda ejecución del mismo comando falla comúnmente con un error de permiso en un archivo anexado que parece de solo lectura.{inputs}y{outputs}se expanden a esos valores.{pwd},{dspath}y{tmpdir}también están disponibles, y{inputs[0]}indexa entradas individuales.- El mensaje de commit lleva un registro JSON de ejecución entre
=== No cambiar las líneas siguientes ===y^^^ No cambiar las líneas anteriores ^^^. No edite ese bloque a mano;rerunlo analiza.
datalad run se niega a iniciar cuando el conjunto de datos tiene modificaciones no guardadas, porque un estado de inicio sucio hace que el registro no sea confiable. Guarde o descarte primero, o pase --explicit para declarar que las entradas y salidas listadas son la historia completa. Verifique un comando antes de confirmarlo con --dry-run basic o --dry-run command.
Una ejecución que no cambia nada no produce ningún commit, exactamente como lo hace datalad save.
Re-ejecución
datalad rerun # rehacer la ejecución registrada en HEAD
datalad rerun --report # mostrar lo que se haría, no cambiar nada
datalad rerun --script recompute.sh # extraer los comandos en lugar de ejecutarlos
datalad rerun --since <commit> -b check <revision> # reproducir un rango en una nueva rama
Re-ejecutar en una rama (-b) es la forma segura de probar la reproducibilidad: la reproducción termina en otro lugar, y un diff contra la rama original responde si las salidas regresaron idénticas.
Contenedores
Con la extensión datalad-container, registre una imagen una vez y cada ejecución posterior registra qué imagen produjo las salidas:
datalad containers-add fsl --url docker://brainlife/fsl:6.0.4
datalad containers-run -n fsl -m "máscara cerebral en contenedor" \
--input "sub-01/anat/sub-01_T1w.nii.gz" \
--output "derivatives/sub-01_brain.nii.gz" \
"bet {inputs} {outputs} -m"
La imagen en sí misma se rastrea en el conjunto de datos, por lo que el entorno de software viaja con los datos y el registro de procedencia en lugar de vivir en el historial de shell de alguien. Cuando solo hay un contenedor configurado, -n puede omitirse.
Consulte provenance.md para conocer los principios STAMPED y la disposición del proyecto YODA, el formato del registro de ejecución, las semánticas de --explicit y --assume-ready, y la exportación de procedencia hacia W3C PROV.
Guardar e inspeccionar cambios
datalad status # qué cambió, incluido el estado del subconjunto de datos
datalad save -m "añadir informe QC" ruta/al/archivo
datalad save -m "punto de control" -r # recurrir en subconjuntos de datos
datalad save -m "archivo de texto pequeño" --to-git notes.md
datalad save decide por archivo si el contenido va a Git o a git-annex, siguiendo el .gitattributes del conjunto de datos. Fuerce un archivo a Git con --to-git, que es la decisión correcta para código y archivos de texto pequeños que deben permanecer directamente legibles. El procedimiento yoda (datalad create -c yoda) configura esto para code/, README.md y CHANGELOG.md automáticamente.
Creación de un conjunto de datos
datalad create my_dataset # conjunto de datos simple
datalad create -c yoda my_analysis # diseño de análisis (code/ rastreado en Git,
# README.md y CHANGELOG.md preconfigurados)
datalad create -d . inputs/raw # registrar un nuevo subconjunto de datos bajo uno existente
-c yoda aplica la disposición del proyecto de análisis descrita en provenance.md. -d . es lo que registra un nuevo conjunto de datos como subconjunto del padre en lugar de dejar un repositorio no relacionado dentro de él.
Publicación
Un conjunto de datos de DataLad generalmente se publica en dos lugares a la vez: un servicio de alojamiento Git para el historial y un remoto de almacenamiento para el contenido anexado.
datalad create-sibling-github myaccount/mydataset
git annex initremote store type=S3 bucket=my-bucket encryption=none autoenable=true
datalad siblings configure -s github --publish-depends store
datalad push --to github
El hermano Git y el hermano de almacenamiento se crean con diferentes herramientas a propósito. Un hermano Git es un remoto Git, y datalad create-sibling-* maneja los del servicio de alojamiento. Un bucket S3 (o WebDAV, o un directorio SSH) es un remoto especial de git-annex, no un remoto Git, por lo que se crea con git annex initremote. datalad siblings recoge el remoto especial después y lo trata como cualquier otro. Usar datalad siblings add --url s3://... aquí es el error que esta sección existe para prevenir: --url es una URL de remoto Git, S3 no lo es, y el push --to github debajo entonces falla en el salto --publish-depends.
--publish-depends es lo que detiene la publicación rota común: un repositorio Git cuyo historial referencia contenido que nunca se subió, por lo que los colaboradores clonan con éxito y luego encuentran que cada datalad get falla. Declarar la dependencia hace que el hermano de almacenamiento publique primero, cada vez.
datalad push envía tanto el historial Git como, por defecto (--data auto-if-wanted), el contenido anexado que el destino está configurado para querer. Pase --data anything para enviar todo el contenido independientemente de las preferencias del destino.
Consulte publishing.md para almacenes RIA, remotos especiales, manejo de credenciales y configuración de qué hermano contiene qué.
Liberación de espacio en disco
git annex whereis sub-01/ # confirme primero que existe otra copia
datalad drop sub-01/ # eliminar contenido local, mantener el puntero
datalad drop --what all --reckless kill <ruta> # último recurso, destruye datos
datalad drop se niega por defecto cuando no puede verificar que existe otra copia del contenido, lo cual es una verificación de seguridad más que un obstáculo. --nocheck y --if-dirty están obsoletos; la ortografía actual es --reckless availability, y significa lo que dice. --what selecciona entre filecontent (el predeterminado), allkeys, datasets y all.
Modos de fallo que vale la pena conocer
| Síntoma | Causa | Solución |
|---|---|---|
| El archivo se lee como vacío, truncado o un enlace simbólico roto | El contenido no se recuperó; solo está presente el puntero | datalad get <ruta> |
| "Permiso denegado" al escribir una salida existente | git-annex protege contra escritura el contenido anexado | Declárelo con --output, o datalad unlock <ruta> |
datalad run se niega a iniciar | El conjunto de datos tiene cambios no guardados | datalad save primero, o pase --explicit |
datalad drop se niega | No hay una segunda copia verificada del contenido | Envíe a un hermano primero, o acepte --reckless availability |
El colaborador clona pero cada get falla | El historial se publicó sin el contenido | Publique el hermano de almacenamiento y establezca --publish-depends |
| La clonación tiene éxito, los directorios del subconjunto están vacíos | Los subconjuntos no se instalan por defecto | datalad get -n -r ., luego get las rutas que necesita |
| Los comandos se comportan de manera imposible | git-annex faltante o demasiado antiguo | datalad wtf --section dependencies |
Referencias detalladas
- data-access.md: encontrar conjuntos de datos publicados
(
registry.datalad.org, OpenNeuro, DANDI,datasets.datalad.orgy el atajo///), opciones de clonación y obtención, manejo de subconjuntos, estados de contenido de anexo, eliminación y remoción, y reparaciónfsck. - provenance.md: los principios STAMPED y la disposición
YODA, el formato del registro de ejecución, opciones completas de
runyrerun,containers-run, y el estado actual de exportación de procedencia de DataLad hacia W3C PROV. - publishing.md: hermanos y sus acciones,
variantes de
create-sibling-*, almacenes RIA, remotos especiales, semántica depushy manejo de credenciales.
Habilidades relacionadas
La habilidad bids cubre la Estructura de Datos de Imágenes Cerebrales (BIDS) en la que
se organizan la mayoría de los conjuntos de datos de neuroimagen distribuidos a través
de DataLad. Un flujo de trabajo típico clona un conjunto de datos BIDS con DataLad, lo
valida con las herramientas BIDS, y luego ejecuta una aplicación BIDS bajo
datalad containers-run para que los derivados lleven procedencia.
Fuentes primarias
- Documentación de DataLad: https://docs.datalad.org/en/stable/
- Manual de DataLad: https://handbook.datalad.org/en/latest/
- Capítulo
datalad run: https://handbook.datalad.org/en/latest/basics/101-108-run.html - Principios YODA: https://handbook.datalad.org/en/latest/basics/101-127-yoda.html
- Principios STAMPED (operacionalizados desde YODA): https://stamped-principles.org
- datalad-container: https://docs.datalad.org/projects/container/en/stable/
- git-annex: https://git-annex.branchable.com/
- Registro de conjuntos de datos: https://registry.datalad.org
Agradecimiento
El alcance del tema para esta habilidad fue informado en parte por el datalad-cli con licencia MIT de @bcmcpher.