root_numpy

root_numpy is a python library for converting ROOT TTree to numpy structure array or record array. The library is written in C++ and Cython and is much faster than PyROOT. It supports scalar, array of scalar and vector of basic types(int float double etc.).

Download and Install

easy_install root_numpy

or

pip install root_numpy

Obtaining Source Code

Download it from http://pypi.python.org/pypi/root_numpy/ or

Clone it from github git clone https://github.com/rootpy/root_numpy.

Then do the usual python setup.py install

Typical Usage

from root_numpy import *
#load to numpy structured array
#treename is always optional if there is 1 tree in the file
a = root2array('a.root','treename')
#load to numpy
a_rec = root2rec('a.root','treename')

Full Documentation

root2array(fnames, treename=None, branches=None, entries=None, offset=0)

convert tree treename in root files specified in fnames to numpy structured array. Type conversion table is given here

Arguments:

fnames: Root file name pattern. Wildcard is also supported by Python glob (not ROOT semi-broken wildcard) fnames can be string or list of string.

treename: name of tree to convert to numpy array. This is optional if the file contains exactly 1 tree.

branches (optional): list of string for branch name to be extracted from tree.

• If branches is not specified or is None or is empty, all from the first treebranches are extracted
• If branches contains duplicate branches, only the first one is used.

entries (optional): maximum number of data that it should load useful for testing out stuff

offset (optional): start index (first one is 0)

Example

# read all branches from tree named mytree from a.root
# remember that 'mytree' is optional if a.root has 1 tree
root2array('a.root', 'mytree')

# read all branches starting from record 5 for 10 records
# or the end of file.
root2array('a.root', 'mytree', entries=10, offset=5)

# read all branches from tree named mytree from a*.root
root2array('a*.root', 'mytree')

# read all branches from tree named mytree from a*.root and b*.root
root2array(['a*.root', 'b*.root'], 'mytree')

# read branch x and y from tree named mytree from a.root
root2array('a.root', 'mytree', ['x', 'y'])

Note

Due to the way TChain works, if the trees specified in the input files have different structures, only the branch in the first tree will be automatically extracted. You can work around this by either reordering the input file or specifying the branches manually.

root2rec(fnames, treename=None, branches=None, entries=None, offset=0)

read branches in tree treename in file(s) given by fnames can convert it to numpy recarray

This is equivalent to root2array(fnames, treename, branches).view(np.recarray)

See also

root2array()

list_trees(fname)

list trees in rootfile fname

list_branches(fname, treename=None)

get a list of branches for given fname and treename. treename is optional if fname has only one tree

lt(fname)

shorthand for list_trees()

lst(fname, treename=None)

return tree structures. treename is optional if fname has only one tree

lb(fname, treename=None)

shorthand for list_branches()

tree2array(tree, branches=None, entries=None, offset=0, include_weight=False, weight_name='weight', weight_dtype='f4')

convert PyROOT TTree tree to numpy structured array see root2array() for details on parameter

tree2rec(tree, branches=None, entries=None, offset=0, include_weight=False, weight_name='weight', weight_dtype='f4')

convert PyROOT TTree tree to numpy structured array see root2array() for details on parameters.

fill_array(hist, array, weights=None)

Fill a ROOT histogram with a NumPy array

stretch(arr, col_names, asrecarray=True)

Stretch array. hstack multiple array fields and preserving column names and rec array structure. If scalar field is specified, it’s stretched along with array field.

Arguments*

• arr numpy structured array or recarray
• colnames list of column names to stretch
• asrecarray optional boolean. If True return recarray, False returns structured array. Default True

Type Conversion Table

List of primitive type converion is given this table:

ROOT type	numpy type
Char_t	np.int8
UChar_t	np.uint8
Short_t	np.int16
UShort_t	np.uint16
Int_t	np.int32
UInt_t	np.uint32
Float_t	np.float32
Double_t	np.float64
Long64_t	np.int64
ULong64_t	np.uint64
Bool_t	np.bool
x[10]	(np.primitivetype, (10,))
x[nx]	np.object
vector<t>	np.object

Variable length array (particletype[nparticle]) and vector (vector<int>) are converted to object of numpy array of corresponding types. Fixed length array is converted to fixed length array field in numpy.