template<
typename T>
class ROOT::VecOps::RVec< T >
A "std::vector"-like collection of values implementing handy operation to analyse them.
- Template Parameters
-
T | The type of the contained objects |
A RVec is a container designed to make analysis of values' collections fast and easy. Its storage is contiguous in memory and its interface is designed such to resemble to the one of the stl vector. In addition the interface features methods and external functions to ease the manipulation and analysis of the data in the RVec.
- Note
- ROOT::VecOps::RVec can also be spelled simply ROOT::RVec. Shorthand aliases such as ROOT::RVecI or ROOT::RVecD are also available as template instantiations of RVec of fundamental types. The full list of available aliases:
- RVecB (
bool
)
- RVecC (
char
)
- RVecD (
double
)
- RVecF (
float
)
- RVecI (
int
)
- RVecL (
long
)
- RVecLL (
long long
)
- RVecU (
unsigned
)
- RVecUL (
unsigned long
)
- RVecULL (
unsigned long long
)
-
RVec does not attempt to be exception safe. Exceptions thrown by element constructors during insertions, swaps or other operations will be propagated potentially leaving the RVec object in an invalid state.
-
RVec methods (e.g.
at
or size
) follow the STL naming convention instead of the ROOT naming convention in order to make RVec a drop-in replacement for std::vector
.
Table of Contents
Example
Suppose to have an event featuring a collection of muons with a certain pseudorapidity, momentum and charge, e.g.:
std::vector<short>
mu_charge {1, 1, -1, -1, -1, 1, 1, -1};
std::vector<float>
mu_pt {56, 45, 32, 24, 12, 8, 7, 6.2};
std::vector<float>
mu_eta {3.1, -.2, -1.1, 1, 4.1, 1.6, 2.4, -.5};
Suppose you want to extract the transverse momenta of the muons satisfying certain criteria, for example consider only negatively charged muons with a pseudorapidity smaller or equal to 2 and with a transverse momentum greater than 10 GeV. Such a selection would require, among the other things, the management of an explicit loop, for example:
for (
size_t i=0; i <
size; ++i) {
}
}
ROOT::Detail::TRangeCast< T, true > TRangeDynCast
TRangeDynCast is an adapter class that allows the typed iteration through a TCollection.
RVec< PromoteType< T > > abs(const RVec< T > &v)
These operations become straightforward with RVec - we just need to write what we mean:
Now the clean collection of transverse momenta can be used within the rest of the data analysis, for example to fill a histogram.
Arithmetic operations, logical operations and mathematical functions
Arithmetic operations on RVec instances can be performed: for example, they can be added, subtracted, multiplied.
The supported operators are
- +, -, *, /
- +=, -=, *=, /=
- <, >, ==, !=, <=, >=, &&, ||
- ~, !
- &, |, ^
- &=, |=, ^=
- <<=, >>=
The most common mathematical functions are supported. It is possible to invoke them passing RVecs as arguments.
- abs, fdim, fmod, remainder
- floor, ceil, trunc, round, lround, llround
- exp, exp2, expm1
- log, log10, log2, log1p
- pow
- sqrt, cbrt
- sin, cos, tan, asin, acos, atan, atan2, hypot
- sinh, cosh, tanh, asinh, acosh
- erf, erfc
- lgamma, tgamma
If the VDT library is available, the following functions can be invoked. Internally the calculations are vectorized:
- fast_expf, fast_logf, fast_sinf, fast_cosf, fast_tanf, fast_asinf, fast_acosf, fast_atanf
- fast_exp, fast_log, fast_sin, fast_cos, fast_tan, fast_asin, fast_acos, fast_atan
Owning and adopting memory
RVec has contiguous memory associated to it. It can own it or simply adopt it. In the latter case, it can be constructed with the address of the memory associated to it and its length. For example:
In this case, the memory associated to myStlVec and myRVec is the same, myRVec simply "adopted it". If any method which implies a re-allocation is called, e.g. emplace_back or resize, the adopted memory is released and new one is allocated. The previous content is copied in the new memory and preserved.
Sorting and manipulation of indices
Sorting
RVec complies to the STL interfaces when it comes to iterations. As a result, standard algorithms can be used, for example sorting:
std::sort(
v.begin(),
v.end());
For convenience, helpers are provided too:
RVec< T > Reverse(const RVec< T > &v)
Return copy of reversed vector.
RVec< T > Sort(const RVec< T > &v)
Return copy of RVec with elements sorted in ascending order.
Manipulation of indices
It is also possible to manipulated the RVecs acting on their indices. For example, the following syntax
RVec< T > Take(const RVec< T > &v, const RVec< typename RVec< T >::size_type > &i)
Return elements of a vector at given indices.
will yield a new RVec<double> the content of which is the first, second and zeroth element of v0, i.e. {7., 8., 9.}
.
The Argsort
and StableArgsort
helper extracts the indices which order the content of a RVec
. For example, this snippet accomplishes in a more expressive way what we just achieved:
RVec< typename RVec< T >::size_type > Argsort(const RVec< T > &v)
Return an RVec of indices that sort the input RVec.
The Take
utility allows to extract portions of the RVec
. The content to be taken can be specified with an RVec
of indices or an integer. If the integer is negative, elements will be picked starting from the end of the container:
Usage in combination with RDataFrame
RDataFrame leverages internally RVecs. Suppose to have a dataset stored in a TTree which holds these columns (here we choose C arrays to represent the collections, they could be as well std::vector instances):
nPart "nPart/I" An integer representing the number of particles
px "px[nPart]/D" The C array of the particles' x component of the momentum
py "py[nPart]/D" The C array of the particles' y component of the momentum
E "E[nPart]/D" The C array of the particles' Energy
Suppose you'd like to plot in a histogram the transverse momenta of all particles for which the energy is greater than 200 MeV. The code required would just be:
};
auto hpt =
d.Define(
"pt",
cutPt, {
"px",
"py",
"E"})
.Histo1D("pt");
ROOT's RDataFrame offers a modern, high-level interface for analysis of data stored in TTree ,...
RVec< PromoteType< T > > sqrt(const RVec< T > &v)
And if you'd like to express your selection as a string:
auto hpt =
d.Define(
"pt",
"sqrt(pxs * pxs + pys * pys)[E>200]")
.Histo1D("pt");
PyROOT
The ROOT::RVec class has additional features in Python, which allow to adopt memory from Numpy arrays and vice versa. The purpose of these features is the copyless interfacing of Python and C++ using their most common data containers, Numpy arrays and RVec with a std::vector interface.
Conversion of RVecs to Numpy arrays
RVecs of fundamental types (int, float, ...) have in Python the __array_interface__
attribute attached. This information allows Numpy to adopt the memory of RVecs without copying the content. You can find further documentation regarding the Numpy array interface here. The following code example demonstrates the memory adoption mechanism using numpy.asarray
.
print(rvec)
print(npy)
rvec[0] = 42
print(npy)
Conversion of Numpy arrays to RVecs
Data owned by Numpy arrays with fundamental types (int, float, ...) can be adopted by RVecs. To create an RVec from a Numpy array, ROOT offers the facility ROOT.VecOps.AsRVec, which performs a similar operation to numpy.asarray
, but vice versa. A code example demonstrating the feature and the adoption of the data owned by the Numpy array is shown below.
print(npy)
print(rvec)
npy[0] = 42
print(rvec)
Definition at line 1529 of file RVec.hxx.