Operaciones básicas de entrada/salida de archivos con Uproot

¿Qué es Uproot?¶

Uproot es un paquete de Python que lee y escribe archivos ROOT, y está únicamente enfocado en la lectura y escritura (sin análisis, sin gráficos, etc.). Interactúa con NumPy, Awkward Array y Pandas para cálculos, boost-histogram/hist para manipulación y visualización de histogramas, Vector para funciones y transformaciones de vectores de Lorentz, Coffea para escalar el análisis, etc.

Uproot está implementado solo con Python y librerías de Python. No tiene una parte compilada ni requiere una versión específica de ROOT. (Esto significa que si usas ROOT para algo más que entrada/salida, tu elección de versión de ROOT no estará limitada por la entrada/salida).

Como consecuencia de ser una implementación independiente de la entrada/salida de ROOT, Uproot podría no ser capaz de leer/escribir ciertos tipos de datos. Cuáles tipos de datos no están implementados cambia constantemente, ya que siempre se están agregando nuevos. Una buena forma de leer datos es simplemente intentarlo y ver si Uproot se queja. Para la escritura, consulta las listas de tipos compatibles en la documentación de Uproot (cajas azules en el texto).

Leer datos desde un archivo¶

Abrir el archivo¶

Para abrir un archivo para lectura, pasa el nombre del archivo a uproot.open. En los scripts, es una buena práctica usar la instrucción with de Python para cerrar el archivo cuando termines, pero si estás trabajando de forma interactiva, puedes usar una asignación directa.

Para acceder a un archivo remoto mediante HTTP o XRootD, utiliza una URL que comience con "http://...", "https://..." o "root://...". Si la interfaz de Python para XRootD no está instalada, el mensaje de error explicará cómo instalarla.

Listar contenidos¶

Este objeto “archivo” en realidad representa un directorio, y los objetos nombrados en ese directorio son accesibles a través de una interfaz similar a un diccionario. Por lo tanto, keys, values e items devuelven los nombres de las claves y/o leen los datos. Si solo quieres listar los objetos sin leerlos, utiliza keys. (Esto es similar a ls() de ROOT, excepto que obtienes una lista de Python).

A menudo también querrás conocer el tipo de cada objeto, por lo que los objetos uproot.ReadOnlyDirectory también tienen un método classnames, que devuelve un diccionario de nombres de objetos a nombres de clases (sin leerlos).

Lectura de un histograma¶

Si estás familiarizado/a con ROOT, reconocerás TH1F como histogramas y TTree como un conjunto de datos. Para leer uno de los histogramas, coloca su nombre entre corchetes:

Uproot no realiza ningún tipo de graficación ni manipulación de histogramas, por lo que los métodos más útiles de h comienzan con “to”: to_boost (boost-histogram), to_hist (hist), to_numpy (la tupla de 2 elementos de NumPy que contiene el contenido y los bordes), to_pyroot (PyROOT), etc.

Los histogramas de Uproot también cumplen con el protocolo de graficación UHI, por lo que tienen métodos como values (contenidos de los bins), variances (errores al cuadrado) y axes.

Lectura de un TTree¶

Un TTree representa un conjunto de datos potencialmente grande. Obtenerlo del uproot.ReadOnlyDirectory solo devuelve los nombres y tipos de sus TBranch. El método show es una forma conveniente de listar su contenido:

Ten en cuenta que puedes obtener la misma información de keys (un uproot.TTree es similar a un diccionario), typename e interpretation.

(Si un uproot.TBranch no tiene interpretation, no se puede leer con Uproot).

La forma más directa de leer datos de un uproot.TBranch es llamando a su método array.

Consideraremos otros métodos en la próxima lección.

Lectura de un... ¿qué es eso?¶

Este archivo también contiene una instancia del tipo TProcessID. Estos objetos no suelen ser útiles en el análisis de datos, pero Uproot logra leerlo de todos modos porque sigue ciertas convenciones (tiene “streamers de clase”). Se presenta como un objeto genérico con una propiedad all_members para sus miembros de datos (a través de todas las superclases).

Aquí hay un ejemplo más útil de eso: una búsqueda de supernovas con el experimento IceCube tiene clases personalizadas para sus datos, que Uproot lee y representa como objetos con all_members.

Escribir datos en un archivo¶

La capacidad de Uproot para escribir datos es más limitada que su capacidad para leer datos, pero algunos casos útiles son posibles.

Abrir archivos para escritura¶

Primero que nada, un archivo debe abrirse para escritura, ya sea creando un archivo completamente nuevo o actualizando uno existente.

archivo_existente = uproot.update("archivo-existente.root")

(Uproot no puede escribir a través de una red; los archivos de salida deben ser locales).

Escribir cadenas e histogramas¶

Estos objetos uproot.WritableDirectory tienen una interfaz similar a un diccionario: puedes poner datos en ellos asignándolos a corchetes.

En ROOT, el nombre de un objeto es una propiedad del objeto, pero en Uproot es una clave en el TDirectory que contiene el objeto, por eso el nombre está en el lado izquierdo de la asignación, entre corchetes. Solo se admiten los tipos de datos enumerados en la caja azul de la documentación: principalmente solo histogramas.

Escribir TTrees¶

Los TTrees son potencialmente grandes y pueden no caber en la memoria. Generalmente, necesitarás escribirlos en lotes.

Una forma de hacerlo es crear el TTree con uproot.WritableDirectory.mktree, pasándole el primer lote de datos, y extenderlo con extend usando los lotes siguientes:

otra es pasar los tipos de datos en lugar de los datos mismos, lo que crea un TTree vacío, de modo que cada escritura sea una extensión.

En la próxima lección se dan consejos de rendimiento, pero en general vale la pena escribir pocos lotes grandes en lugar de muchos lotes pequeños.

Los únicos tipos de datos que se pueden pasar a mktree y extend están listados en la caja azul de esta documentación. Esto incluye arrays irregulares (descritos dos lecciones más adelante), pero no tipos más complejos.

Leer y escribir RNTuples¶

Durante décadas, TTree ha sido el formato predeterminado para almacenar conjuntos de datos grandes en archivos ROOT. Sin embargo, poco a poco ha quedado desactualizado y no está optimizado para los sistemas modernos. Ahí es donde entra el formato RNTuple. Es un formato de serialización moderno, diseñado pensando en los sistemas actuales, y está previsto que reemplace a TTree en los próximos años. La versión 1.0.0.0 ya salió y va a tener soporte “para siempre”.

Los RNTuples son mucho más simples que los TTrees por diseño, y esta vez hay una especificación oficial, lo que hace mucho más fácil que paquetes de entrada/salida de terceros como Uproot puedan admitirlos. Uproot ya permite leer la especificación completa de RNTuple, lo que significa que puedes leer cualquier RNTuple que encuentres en la práctica. También permite escribir una gran parte de la especificación, y la intención es admitir todo lo que tenga sentido para el análisis de datos.

Para facilitar la transición a los RNTuples, estamos diseñando la interfaz para que se parezca lo más posible a la de los TTrees. Veamos un ejemplo simple de lectura y escritura de RNTuples.

De nuevo, usaremos un archivo de ejemplo del paquete scikit-hep-testdata.

Esta vez, si imprimimos los nombres de las clases, vemos que hay un RNTuple en lugar de un TTree.

Veamos las claves disponibles con .keys, pero restringiéndonos solo a las del nivel superior usando recursive=False.

Podemos mostrar la estructura del RNTuple más claramente usando .show, que funciona de manera similar a como lo hace con los TTrees, pero es más completo y muestra mejor la estructura, ya que los RNTuples son completamente legibles por Uproot.

Leer datos en arrays funciona exactamente igual que para los TTrees, así que no tienes que preocuparte por distinguir si estás leyendo un TTree o un RNTuple.

Escribir es incluso más simple que para los TTrees: basta con asignar los datos a una clave del archivo, de la misma manera pythónica que para las cadenas y los histogramas. A partir de Uproot 5.7, esto escribe un RNTuple (en versiones anteriores escribía un TTree), y el objeto resultante se puede extender con más lotes, igual que un TTree.

Si prefieres declarar los campos por adelantado y hacer que cada escritura sea una extensión, uproot.WritableDirectory.mkrntuple es la contraparte de mktree para RNTuples.

Para el resto del tutorial nos quedaremos principalmente con los TTrees, ya que este sigue siendo el formato de datos principal que te vas a encontrar en el futuro cercano.