Metadata-Version: 2.1
Name: uproot
Version: 3.13.0
Summary: ROOT I/O in pure Python and Numpy.
Home-page: https://github.com/scikit-hep/uproot
Author: Jim Pivarski (IRIS-HEP)
Author-email: pivarski@princeton.edu
Maintainer: Jim Pivarski (IRIS-HEP)
Maintainer-email: pivarski@princeton.edu
License: BSD 3-clause
Download-URL: https://github.com/scikit-hep/uproot/releases
Platform: Any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*
Requires-Dist: numpy (>=1.13.1)
Requires-Dist: awkward (<1.0,>=0.12.0)
Requires-Dist: uproot-methods (>=0.7.0)
Requires-Dist: cachetools
Provides-Extra: compress
Requires-Dist: lz4 ; extra == 'compress'
Requires-Dist: zstandard ; extra == 'compress'
Requires-Dist: xxhash ; extra == 'compress'
Requires-Dist: backports.lzma ; (python_version < "3.3") and extra == 'compress'
Provides-Extra: testing
Requires-Dist: pytest (>=3.9) ; extra == 'testing'
Requires-Dist: pkgconfig ; extra == 'testing'
Requires-Dist: lz4 ; extra == 'testing'
Requires-Dist: zstandard ; extra == 'testing'
Requires-Dist: xxhash ; extra == 'testing'
Requires-Dist: mock ; extra == 'testing'
Requires-Dist: requests ; extra == 'testing'
Requires-Dist: backports.lzma ; (python_version < "3.3") and extra == 'testing'

.. image:: https://raw.githubusercontent.com/scikit-hep/uproot/master/docs/source/logo-300px.png
   :alt: uproot
   :target: https://github.com/scikit-hep/uproot

.. inclusion-marker-1-5-do-not-remove

uproot (originally μproot, for "micro-Python ROOT") is a reader and a writer of the `ROOT file format <https://root.cern/>`__ using only Python and Numpy. Unlike the standard C++ ROOT implementation, uproot is only an I/O library, primarily intended to stream data into machine learning libraries in Python. Unlike PyROOT and root_numpy, uproot does not depend on C++ ROOT. Instead, it uses Numpy to cast blocks of data from the ROOT file as Numpy arrays.

Python does not necessarily mean slow. As long as the data blocks ("baskets") are large, this "array at a time" approach can even be faster than "event at a time" C++. Below, the rate of reading data into arrays with uproot is shown to be faster than C++ ROOT (left) and root_numpy (right), as long as the baskets are tens of kilobytes or larger (for a variable number of muons per event in an ensemble of different physics samples; higher is better).


.. image:: https://raw.githubusercontent.com/scikit-hep/uproot/master/docs/root-none-muon.png
   :width: 350 px
.. image:: https://raw.githubusercontent.com/scikit-hep/uproot/master/docs/rootnumpy-none-muon.png
   :width: 350 px


uproot is not maintained by the ROOT project team, so post bug reports here as `GitHub issues <https://github.com/scikit-hep/uproot/issues>`__, not on a ROOT forum. Thanks!

.. inclusion-marker-2-do-not-remove

Installation
============

Install uproot like any other Python package:

.. code-block:: bash

    pip install uproot                       # maybe with sudo or --user, or in virtualenv

or install with `conda <https://conda.io/en/latest/miniconda.html>`__:

.. code-block:: bash

    conda config --add channels conda-forge  # if you haven't added conda-forge already
    conda install uproot

The pip installer automatically installs strict dependencies; the conda installer also installs optional dependencies (except for Pandas).

Strict dependencies:
--------------------

- `numpy <https://scipy.org/install.html>`__ (1.13.1+)
- `awkward-array <https://github.com/scikit-hep/awkward-array>`__ (0.12.0+)
- `uproot-methods <https://github.com/scikit-hep/uproot-methods>`__ (0.7.0+)
- `cachetools <https://pypi.org/project/cachetools>`__

Optional dependencies:
----------------------

- `lz4 <https://pypi.org/project/lz4>`__ to read/write lz4-compressed ROOT files
- `xxhash <https://pypi.org/project/xxhash/>`__ to read/write lz4-compressed ROOT files
- `lzma <https://pypi.org/project/backports.lzma>`__ to read/write lzma-compressed ROOT files in Python 2
- `xrootd <https://anaconda.org/conda-forge/xrootd>`__ to access remote files through XRootD
- `requests <https://pypi.org/project/requests>`__ to access remote files through HTTP
- `pandas <https://pandas.pydata.org>`__ to fill Pandas DataFrames instead of Numpy arrays

**Reminder: you do not need C++ ROOT to run uproot.**

Testing and development requirements
------------------------------------

The packages need to run the test suite can be installed via ``pip install
"uproot[testing]"``. Here is an example how to set up a development

.. code-block:: bash

    git clone https://github.com/scikit-hep/uproot.git  # alternatively your own fork
    cd uproot
    python -m venv venv  # create a virtual environment in the folder venv
    . venv/bin/activate  # activate the Python environment
    pip install -e ".[testing]"   # installs uproot in editable mode with all packages required for testing
    pytest               # run the test suite

Tutorial
========

See the `project homepage <https://github.com/scikit-hep/uproot>`__ for a `tutorial <https://github.com/scikit-hep/uproot#tutorial>`__.

Run `that tutorial <https://mybinder.org/v2/gh/scikit-hep/uproot/master?urlpath=lab/tree/binder%2Ftutorial.ipynb>`__ on Binder.

**Tutorial contents:**

* `Introduction <https://github.com/scikit-hep/uproot#introduction>`__
* `What is uproot? <https://github.com/scikit-hep/uproot#what-is-uproot>`__
* `Exploring a file <https://github.com/scikit-hep/uproot#exploring-a-file>`__

  - `Compressed objects in ROOT files <https://github.com/scikit-hep/uproot#compressed-objects-in-root-files>`__
  - `Exploring a TTree <https://github.com/scikit-hep/uproot#exploring-a-ttree>`__
  - `Some terminology <https://github.com/scikit-hep/uproot#some-terminology>`__

* `Reading arrays from a TTree <https://github.com/scikit-hep/uproot#reading-arrays-from-a-ttree>`__
* `Caching data <https://github.com/scikit-hep/uproot#caching-data>`__

  - `Automatically managed caches <https://github.com/scikit-hep/uproot#automatically-managed-caches>`__
  - `Caching at all levels of abstraction <https://github.com/scikit-hep/uproot#caching-at-all-levels-of-abstraction>`__

* `Lazy arrays <https://github.com/scikit-hep/uproot#lazy-arrays>`__

  - `Lazy array of many files <https://github.com/scikit-hep/uproot#lazy-array-of-many-files>`__
  - `Lazy arrays with caching <https://github.com/scikit-hep/uproot#lazy-arrays-with-caching>`__
  - `Lazy arrays as lightweight skims <https://github.com/scikit-hep/uproot#lazy-arrays-as-lightweight-skims>`__
  - `Lazy arrays in Dask <https://github.com/scikit-hep/uproot#lazy-arrays-in-dask>`__

* `Iteration <https://github.com/scikit-hep/uproot#iteration>`__

  - `Filenames and entry numbers while iterating <https://github.com/scikit-hep/uproot#filenames-and-entry-numbers-while-iterating>`__
  - `Limiting the number of entries to be read <https://github.com/scikit-hep/uproot#limiting-the-number-of-entries-to-be-read>`__
  - `Controlling lazy chunk and iteration step sizes <https://github.com/scikit-hep/uproot#controlling-lazy-chunk-and-iteration-step-sizes>`__
  - `Caching and iteration <https://github.com/scikit-hep/uproot#caching-and-iteration>`__

* `Changing the output container type <https://github.com/scikit-hep/uproot#changing-the-output-container-type>`__
* `Filling Pandas DataFrames <https://github.com/scikit-hep/uproot#filling-pandas-dataframes>`__
* `Selecting and interpreting branches <https://github.com/scikit-hep/uproot#selecting-and-interpreting-branches>`__

  - `TBranch interpretations <https://github.com/scikit-hep/uproot#tbranch-interpretations>`__
  - `Reading data into a preexisting array <https://github.com/scikit-hep/uproot#reading-data-into-a-preexisting-array>`__
  - `Passing many new interpretations in one call <https://github.com/scikit-hep/uproot#passing-many-new-interpretations-in-one-call>`__
  - `Multiple values per event: fixed size arrays <https://github.com/scikit-hep/uproot#multiple-values-per-event-fixed-size-arrays>`__
  - `Multiple values per event: leaf-lists <https://github.com/scikit-hep/uproot#multiple-values-per-event-leaf-lists>`__
  - `Multiple values per event: jagged arrays <https://github.com/scikit-hep/uproot#multiple-values-per-event-jagged-arrays>`__
  - `Jagged array performance <https://github.com/scikit-hep/uproot#jagged-array-performance>`__
  - `Special physics objects: Lorentz vectors <https://github.com/scikit-hep/uproot#special-physics-objects-lorentz-vectors>`__
  - `Variable-width values: strings <https://github.com/scikit-hep/uproot#variable-width-values-strings>`__
  - `Arbitrary objects in TTrees <https://github.com/scikit-hep/uproot#arbitrary-objects-in-ttrees>`__
  - `Doubly nested jagged arrays (i.e. std::vector<std::vector<T>>) <https://github.com/scikit-hep/uproot#doubly-nested-jagged-arrays-ie-stdvectorstdvectort>`__

* `Parallel array reading <https://github.com/scikit-hep/uproot#parallel-array-reading>`__
* `Histograms, TProfiles, TGraphs, and others <https://github.com/scikit-hep/uproot#histograms-tprofiles-tgraphs-and-others>`__
* `Creating and writing data to ROOT files <https://github.com/scikit-hep/uproot#creating-and-writing-data-to-root-files>`__

  - `Writing histograms <https://github.com/scikit-hep/uproot#writing-histograms>`__
  - `Writing TTrees <https://github.com/scikit-hep/uproot#writing-ttrees>`__

Reference documentation
=======================

* `Opening files <http://uproot.readthedocs.io/en/latest/opening-files.html>`__

  - `uproot.open <http://uproot.readthedocs.io/en/latest/opening-files.html#uproot-open>`__
  - `uproot.xrootd <http://uproot.readthedocs.io/en/latest/opening-files.html#uproot-xrootd>`__
  - `uproot.http <http://uproot.readthedocs.io/en/latest/opening-files.html#uproot-http>`__
  - `uproot.iterate <http://uproot.readthedocs.io/en/latest/opening-files.html#uproot-iterate>`__
  - `uproot.pandas.iterate <http://uproot.readthedocs.io/en/latest/opening-files.html#uproot-pandas-iterate>`__
  - `uproot.lazyarray(s) <http://uproot.readthedocs.io/en/latest/opening-files.html#uproot-lazyarray-and-lazyarrays>`__
  - `uproot.daskarray/daskframe <http://uproot.readthedocs.io/en/latest/opening-files.html#uproot-daskarray-and-daskframe>`__
  - `uproot.numentries <http://uproot.readthedocs.io/en/latest/opening-files.html#uproot-numentries>`__

* `ROOT I/O <http://uproot.readthedocs.io/en/latest/root-io.html>`__

  - `uproot.rootio.ROOTDirectory <http://uproot.readthedocs.io/en/latest/root-io.html#uproot-rootio-rootdirectory>`__
  - `uproot.rootio.ROOTObject <http://uproot.readthedocs.io/en/latest/root-io.html#uproot-rootio-rootobject>`__
  - `uproot.rootio.ROOTStreamedObject <http://uproot.readthedocs.io/en/latest/root-io.html#uproot-rootio-rootstreamedobject>`__

* `TTree Handling <http://uproot.readthedocs.io/en/latest/ttree-handling.html>`__

  - `uproot.tree.TTreeMethods <http://uproot.readthedocs.io/en/latest/ttree-handling.html#uproot-tree-ttreemethods>`__
  - `uproot.tree.TBranchMethods <http://uproot.readthedocs.io/en/latest/ttree-handling.html#uproot-tree-tbranchmethods>`__

* `Interpretation <http://uproot.readthedocs.io/en/latest/interpretation.html>`__
* `Caches <http://uproot.readthedocs.io/en/latest/caches.html>`__
* `Parallel I/O <http://uproot.readthedocs.io/en/latest/parallel-io.html>`__


