How to convert to/from ROOT with Uproot#

Uproot defaults to reading data as Awkward Arrays, so there usually isn’t any extra work to do. But there are caveats, mostly with the legacy version of Uproot (Uproot 3).

To find out which version you’re using:

  • if you import uproot3, then it’s Uproot 3;

  • if you import uproot or import uproot4, then it’s Uproot 4.

import awkward as ak
import numpy as np
import uproot3
import uproot

From ROOT to Awkward with Uproot 4#

By default, Uproot 4 delivers data from ROOT files as Awkward 1 arrays, even though the Awkward library isn’t one of Uproot’s formal dependencies. (If you try to use Uproot 4 without having Awkward, you’ll quickly be presented with an ImportError and suggestions about how to proceed.)

To start, open a file and look at the objects it contains.

up4_file ="")
{'events;1': 'TTree'}

From the above, we learn that "events" is a TTree, so we read its metadata with:

up4_events = up4_file["events"]
<TTree 'events' (51 branches) at 0x7f3d2c413b50>

And then look at its branches and their types.
name                 | typename                 | interpretation                
NJet                 | int32_t                  | AsDtype('>i4')
Jet_Px               | float[]                  | AsJagged(AsDtype('>f4'))
Jet_Py               | float[]                  | AsJagged(AsDtype('>f4'))
Jet_Pz               | float[]                  | AsJagged(AsDtype('>f4'))
Jet_E                | float[]                  | AsJagged(AsDtype('>f4'))
Jet_btag             | float[]                  | AsJagged(AsDtype('>f4'))
Jet_ID               | bool[]                   | AsJagged(AsDtype('bool'))
NMuon                | int32_t                  | AsDtype('>i4')
Muon_Px              | float[]                  | AsJagged(AsDtype('>f4'))
Muon_Py              | float[]                  | AsJagged(AsDtype('>f4'))
Muon_Pz              | float[]                  | AsJagged(AsDtype('>f4'))
Muon_E               | float[]                  | AsJagged(AsDtype('>f4'))
Muon_Charge          | int32_t[]                | AsJagged(AsDtype('>i4'))
Muon_Iso             | float[]                  | AsJagged(AsDtype('>f4'))
NElectron            | int32_t                  | AsDtype('>i4')
Electron_Px          | float[]                  | AsJagged(AsDtype('>f4'))
Electron_Py          | float[]                  | AsJagged(AsDtype('>f4'))
Electron_Pz          | float[]                  | AsJagged(AsDtype('>f4'))
Electron_E           | float[]                  | AsJagged(AsDtype('>f4'))
Electron_Charge      | int32_t[]                | AsJagged(AsDtype('>i4'))
Electron_Iso         | float[]                  | AsJagged(AsDtype('>f4'))
NPhoton              | int32_t                  | AsDtype('>i4')
Photon_Px            | float[]                  | AsJagged(AsDtype('>f4'))
Photon_Py            | float[]                  | AsJagged(AsDtype('>f4'))
Photon_Pz            | float[]                  | AsJagged(AsDtype('>f4'))
Photon_E             | float[]                  | AsJagged(AsDtype('>f4'))
Photon_Iso           | float[]                  | AsJagged(AsDtype('>f4'))
MET_px               | float                    | AsDtype('>f4')
MET_py               | float                    | AsDtype('>f4')
MChadronicBottom_px  | float                    | AsDtype('>f4')
MChadronicBottom_py  | float                    | AsDtype('>f4')
MChadronicBottom_pz  | float                    | AsDtype('>f4')
MCleptonicBottom_px  | float                    | AsDtype('>f4')
MCleptonicBottom_py  | float                    | AsDtype('>f4')
MCleptonicBottom_pz  | float                    | AsDtype('>f4')
MChadronicWDecayQ... | float                    | AsDtype('>f4')
MChadronicWDecayQ... | float                    | AsDtype('>f4')
MChadronicWDecayQ... | float                    | AsDtype('>f4')
MChadronicWDecayQ... | float                    | AsDtype('>f4')
MChadronicWDecayQ... | float                    | AsDtype('>f4')
MChadronicWDecayQ... | float                    | AsDtype('>f4')
MClepton_px          | float                    | AsDtype('>f4')
MClepton_py          | float                    | AsDtype('>f4')
MClepton_pz          | float                    | AsDtype('>f4')
MCleptonPDGid        | int32_t                  | AsDtype('>i4')
MCneutrino_px        | float                    | AsDtype('>f4')
MCneutrino_py        | float                    | AsDtype('>f4')
MCneutrino_pz        | float                    | AsDtype('>f4')
NPrimaryVertices     | int32_t                  | AsDtype('>i4')
triggerIsoMu24       | bool                     | AsDtype('bool')
EventWeight          | float                    | AsDtype('>f4')

Some of these branches have a single value per event (e.g. "MET_px" has type float) and some have multiple values per event (e.g. "Muon_Px" has type float[]).

Regardless of type, they would all be returned as Awkward Arrays:

array = up4_events["MET_px"].array()
<Array [5.91, 24.8, -25.8, 8.62, ..., 18.1, 79.9, 19.7] type='2421 * float32'>
array = up4_events["Muon_Px"].array()
<Array [[-52.9, 37.7], [-0.816], ..., [23.9]] type='2421 * var * float32'>

Because library="ak" is the default. Setting it to another value, like library="np", returns non-Awkward arrays.

array = up4_events["MET_px"].array(library="np")
array([  5.912771,  24.765203, -25.785088, ...,  18.101646,  79.87519 ,
        19.713749], dtype=float32)
array = up4_events["Muon_Px"].array(library="np")
array([array([-52.899456,  37.73778 ], dtype=float32),
       array([-0.81645936], dtype=float32),
       array([48.98783  ,  0.8275667], dtype=float32), ...,
       array([-29.756786], dtype=float32),
       array([1.1418698], dtype=float32),
       array([23.913206], dtype=float32)], dtype=object)

Uproot’s arrays method (plural) returns a “package” of related arrays, which for the Awkward library means arrays presented as records.

arrays = up4_events.arrays(["Muon_Px", "Muon_Py", "Muon_Pz"])
<Array [{Muon_Px: [...], ...}, ..., {...}] type='2421 * {Muon_Px: var * flo...'>
TypeError                                 Traceback (most recent call last)
Cell In [14], line 1
----> 1 ak.type(arrays)

File ~/python3.8/lib/python3.8/site-packages/awkward/operations/, in type(array)
    187     return array.type(ak._util.typestrs(None))
    189 else:
--> 190     raise TypeError(
    191         f"unrecognized array type: {array!r}" + ak._util.exception_suffix(__file__)
    192     )

TypeError: unrecognized array type: <Array [{Muon_Px: [...], ...}, ..., {...}] type='2421 * {Muon_Px: var * flo...'>


With arrays, the how="zip" option attempts to lists with common list lengths.

Note that the ak.type below is var * {all fields}, rather than {field: var, field: var, ...}.

arrays = up4_events.arrays(["Muon_Px", "Muon_Py", "Muon_Pz"], how="zip")

If some of the branches cannot be combined because they have different multiplicities, they are kept separate.

arrays = up4_events.arrays(["Muon_Px", "Muon_Py", "Muon_Pz", "Jet_Px", "Jet_Py", "Jet_Pz"], how="zip")

From Awkward to ROOT with Uproot 4#

Not implemented yet: see the bottom of this page for writing files with Uproot 3.

From ROOT to Awkward with Uproot 3#

Some of the arrays returned by Uproot 3 are NumPy arrays and others are Awkward 0 (i.e. “old library”) arrays, depending on whether Awkward is needed.

Uproot 4 is recommended unless you’re dealing with legacy software built on Uproot 3.

To start, open a file and look at the objects it contains.

up3_file ="")

From the above, we learn that "events" is a TTree, so we read its metadata with:

up3_events = up3_file["events"]

And then look at its branches and their types.

Some of these branches have a single value per event (e.g. "MET_px" has interpretation asdtype('>f4')) and some have multiple values per event (e.g. "Muon_Px" has interpretation asjagged(asdtype('>f4'))).

Data that can be interpreted asdtype are returned as NumPy arrays:

array = up3_events.array("MET_px")

NumPy arrays can be converted to Awkward 1 (i.e. “new library”) by passing them to the ak.Array constructor or the ak.from_numpy function.


And data that require asjagged or other specialized interpretations are returned as Awkward Arrays:

array = up3_events.array("Muon_Px")

Awkward 0 arrays can be converted to Awkward 1 by passing them to the ak.from_awkward0 function. (There’s also an ak.to_awkward0 for the other direction; conversions are usually zero-copy and quick.)


(Unlike Uproot 4, there isn’t a way to specify which library you want for returning output.)

Uproot 3’s arrays method (plural) returns “packages” of related arrays as Python dicts:

arrays = up3_events.arrays(["Muon_Px", "Muon_Py", "Muon_Pz"])

Be careful of the bytestring keys (dict key type is bytes, rather than str) and note that you can only convert all of the arrays with a loop: they are separate entities.

{name.decode(): ak.from_awkward0(array) for name, array in arrays.items()}

From Awkward to ROOT with Uproot 3#

Since ROOT file-writing is only implemented in Uproot 3, you’ll need to take into consideration whether an array is flat, and therefore NumPy, or jagged, and therefore Awkward 0 (i.e. “old library”).

To open a flie for writing, use uproot.recreate, rather than

file = uproot3.recreate("/tmp/example.root")

The uproot3.newtree function creates a tree that can be written. The data types for each branch have to be specified.

file["tree1"] = uproot3.newtree({"branch1": int, "branch2": np.float32})

The method for writing is extend, which can be called as many times as needed to write array chunks to the file.

The chunks should be large (each represents a ROOT TBasket) and must include equal-length arrays for each branch.

file["tree1"].extend({"branch1": np.array([0, 1, 2, 3, 4]),
                      "branch2": np.array([0.0, 1.1, 2.2, 3.3, 4.4], dtype=np.float32)})
file["tree1"].extend({"branch1": np.array([5, 6, 7, 8, 9]),
                      "branch2": np.array([5.5, 6.6, 7.7, 8.8, 9.9], dtype=np.float32)})

To write a jagged array, it must be in Awkward 0 format. You may need to use ak.to_awkward0.

ak0_array = ak.to_awkward0(ak.Array([[1.1, 2.2, 3.3], [], [4.4, 5.5]]))

And you will need its counts. (This is the Awkward 0 equivalent of ak.num.


The branch’s type has to be constructed with the uproot3.newbranch function and has to include a size, into which the counts will be written.

file["tree2"] = uproot3.newtree({"branch3": uproot3.newbranch(np.dtype("f8"), size="n")})

Fill each chunk by assigning the branch data and the counts in each extend.

file["tree2"].extend({"branch3": ak0_array, "n": ak0_array.counts})

File-closure could also be enforced by putting uproot3.recreate in a context manager (Python with statement).