{"id":7838,"library":"uproot3-methods","title":"Pythonic Mix-ins for ROOT classes (uproot3-methods)","description":"uproot3-methods provides Pythonic mix-ins that extend the functionality of `uproot3` and `awkward0` arrays, adding common methods found in ROOT's C++ classes like TLorentzVector, TVector2, TVector3, and histogram types. It is specifically designed for the `uproot3` and `awkward0` ecosystems. The current version is 0.10.1 and it is primarily in maintenance mode, supporting the older `uproot3` branch.","status":"maintenance","version":"0.10.1","language":"en","source_language":"en","source_url":"https://github.com/scikit-hep/uproot3-methods","tags":["ROOT","HEP","physics","data analysis","uproot","awkward","scikit-hep"],"install":[{"cmd":"pip install uproot3-methods","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides the core ROOT file I/O objects that uproot3-methods extends.","package":"uproot3"},{"reason":"uproot3-methods adds methods to Awkward 0.x arrays; incompatible with Awkward 1.x or 2.x.","package":"awkward0"}],"imports":[{"note":"The package name changed from 'uproot-methods' to 'uproot3-methods' in version 0.10.0.","wrong":"from uproot_methods.vector.lorentz import TLorentzVector","symbol":"TLorentzVector","correct":"from uproot3_methods.vector.lorentz import TLorentzVector"},{"note":"The package name changed from 'uproot-methods' to 'uproot3-methods' in version 0.10.0.","wrong":"from uproot_methods.hist import TH1F","symbol":"TH1F","correct":"from uproot3_methods.hist import TH1F"}],"quickstart":{"code":"import uproot3\nimport numpy as np\n# Installing uproot3-methods automatically adds methods to uproot3 arrays.\n# No explicit import of uproot3_methods is needed for the methods to be available on arrays.\n\n# Example: Create a dummy ROOT file with four-vectors using uproot3\nwith uproot3.recreate('test_tree.root') as file:\n    file['tree'] = {\n        'px': np.array([10.0, 20.0, 30.0]),\n        'py': np.array([5.0, 10.0, 15.0]),\n        'pz': np.array([1.0, 2.0, 3.0]),\n        'energy': np.array([11.22, 22.45, 33.67])\n    }\n\n# Open the file and access the branches as a 'Momentum4D' object\nwith uproot3.open('test_tree.root') as file:\n    tree = file['tree']\n    # uproot3-methods automatically provides a 'Momentum4D' accessor\n    # if the 'px', 'py', 'pz', 'energy' branches are present.\n    # This assumes 'Momentum4D' is enabled by default or via configuration.\n    # For a direct example, let's load specific branches and construct.\n    vectors = uproot3.allbranches(file, filter_name=['px', 'py', 'pz', 'energy'])\n    \n    # Assuming uproot3-methods is installed, it enhances the awkward0 array with methods\n    # You might need to explicitly wrap or configure, but typically it's auto-applied.\n    # For direct usage or clarity, we can use the class directly.\n    from uproot3_methods.vector.lorentz import TLorentzVector\n    \n    # Example: create TLorentzVector objects from numpy arrays\n    p4_vectors = TLorentzVector.from_pxyzm(\n        vectors['px'], vectors['py'], vectors['pz'], np.zeros_like(vectors['px']) # mass=0 for simplicity\n    )\n    \n    print(f\"First vector pt: {p4_vectors.pt[0]:.2f}\")\n    print(f\"All vectors eta: {p4_vectors.eta}\")\n\n# Example for histograms\n# from uproot3_methods.hist import TH1F\n# hist = TH1F(bins=np.array([0, 1, 2, 3]), values=np.array([10, 20, 30]))\n# print(f\"Histogram integral: {hist.integral}\")","lang":"python","description":"This quickstart demonstrates how `uproot3-methods` extends `uproot3`'s capabilities. When `uproot3-methods` is installed, it implicitly adds methods (like `pt`, `eta`, `phi` for four-vectors or `integral` for histograms) to arrays loaded by `uproot3` or created as `awkward0` arrays. The example creates a dummy ROOT file, loads four-vector branches, and then explicitly creates `TLorentzVector` objects using data from the file to showcase the extended methods."},"warnings":[{"fix":"Uninstall `uproot-methods` if present (`pip uninstall uproot-methods`) and install the new package (`pip install uproot3-methods`). Update all `import` statements from `uproot_methods` to `uproot3_methods`.","message":"The package name was changed from `uproot-methods` to `uproot3-methods` starting from version 0.10.0. Older installations or `import` statements will fail.","severity":"breaking","affected_versions":"0.10.0 and later"},{"fix":"Ensure your environment uses `uproot3` and `awkward0`. If you need to work with newer `uproot` or `awkward` versions, use `uproot-methods` (no '3' in the name, e.g., `pip install uproot-methods`) which is compatible with `uproot` 4+ and `awkward` 1+.","message":"uproot3-methods is strictly designed for `uproot3` and `awkward0`. It is incompatible with `uproot` versions 4 or later, and `awkward` versions 1 or later.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update to `uproot3-methods` version 0.10.1 or later (`pip install --upgrade uproot3-methods`) to ensure correct histogram error calculations from NumPy arrays.","message":"Histogram `fSumw2` calculation was corrected for NumPy arrays (which have values without errors). Previously, `fSumw2` was incorrectly set to the square of values; it should be equal to the values.","severity":"gotcha","affected_versions":"Prior to 0.10.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statements from `uproot_methods` to `uproot3_methods`. If you still have the old package installed, uninstall it: `pip uninstall uproot-methods`.","cause":"Attempting to import from the old package name after updating uproot3-methods (or its dependencies) or installing an environment with the new name.","error":"ModuleNotFoundError: No module named 'uproot_methods'"},{"fix":"Ensure `uproot3-methods` is installed (`pip install uproot3-methods`) and that your environment uses `awkward0` (`pip install 'awkward<1'`). If you intend to use `uproot` v4+ and `awkward` v1+, you should install `uproot-methods` instead (without the '3').","cause":"This error typically occurs when `uproot3-methods` is not installed, or when you are trying to use it with an incompatible version of `awkward` (e.g., Awkward 1.x or 2.x instead of Awkward 0.x).","error":"AttributeError: 'JaggedArray' object has no attribute 'pt'"},{"fix":"Verify your `awkward` installation. For `uproot3-methods`, you must use `awkward0` (e.g., `pip install 'awkward<1'`). If you need a newer `awkward` version, use `uproot-methods` (compatible with Awkward 1+) instead of `uproot3-methods`.","cause":"This warning indicates that `uproot3-methods` is installed, but it couldn't properly apply its mix-ins to the `awkward` arrays because the loaded `awkward` version is not `awkward0`.","error":"RuntimeWarning: A mix-in for an Awkward 0.x Array could not be found..."}]}