Warning, /acts/docs/groups/python/data_io.md is written in an unsupported language. File is not indexed.
0001 @defgroup python_data_io Data Reading and Writing
0002 @ingroup python_bindings
0003 @brief Readers and writers available in the PyPI wheel and optional source builds.
0004
0005 # Event data input and output
0006
0007 Add readers with `s.addReader(...)`, converters with `s.addAlgorithm(...)`, and writers with
0008 `s.addWriter(...)`. The available formats depend on the build (see @ref python_bindings):
0009
0010 | Format | Python module | Available in PyPI | Use |
0011 | :--- | :--- | :---: | :--- |
0012 | CSV | `acts.examples` | ✓ | Readers and writers for common ACTS event collections. |
0013 | Parquet | `acts.examples.arrow` | ✓ | Reads and writes Arrow tables; converters connect them to ACTS event collections. |
0014 | HepMC3 (ASCII) | `acts.examples.hepmc3` | ✓ | Reads and writes HepMC3 event files without ROOT. |
0015 | ROOT (native) | `acts.examples.root` | ✗ | Readers and writers for particles, sim hits, tracks, vertices, material, and performance output. |
0016 | ROOT via Uproot | `acts.examples.uproot` | ✓ | Python readers for ACTS particle and sim-hit ROOT files; install `uproot` and `numpy` separately. |
0017 | EDM4hep/podio | `acts.examples.edm4hep` | ✗ | `PodioReader` and `PodioWriter`. |
0018
0019 ✓ is included in the PyPI wheel; ✗ requires a source build with the corresponding component
0020 enabled. HepMC3 ROOT-format files also require ROOT support.
0021
0022 ## Parquet and Arrow tables
0023
0024 There is one `ParquetReader` for the configured Parquet collections, rather than a separate
0025 reader for each ACTS data type. It places one Arrow table per collection on the event whiteboard.
0026 Configure a directory and an expected schema for each collection:
0027
0028 ```python
0029 import acts.arrow # module-level table schemas, e.g. acts.arrow.particleSchema()
0030 import acts.examples.arrow
0031
0032 reader = acts.examples.arrow.ParquetReader(
0033 level=acts.logging.INFO,
0034 inputDir=str(inputDir),
0035 collections={"particles_arrow": "particles_generated"},
0036 expectedSchemas={"particles_arrow": acts.arrow.particleSchema()},
0037 )
0038 s.addReader(reader)
0039 ```
0040
0041 The example makes an Arrow table available as `particles_arrow`; it does not create an ACTS
0042 `SimParticleContainer`. Add an input converter for the dataset's schema when ACTS algorithms need
0043 event collections. The current bindings include `ColliderMLRelease1InputConverter` for the
0044 ColliderML Release 1 particle, hit, and optional track tables; other Parquet schemas need a
0045 matching converter.
0046
0047 For output, `ArrowParticleOutputConverter`, `ArrowSimHitOutputConverter`, and
0048 `ArrowTrackOutputConverter` turn ACTS collections into Arrow tables. One `ParquetWriter` can then
0049 write those tables to separate collection directories. See the
0050 [Parquet round-trip test](https://github.com/acts-project/acts/blob/main/Python/Examples/tests/test_arrow.py)
0051 for a particle example and the
0052 [full-chain example](https://github.com/acts-project/acts/blob/main/Examples/Scripts/Python/full_chain_odd.py)
0053 for particle, hit, and track output.
0054
0055 ## HepMC3 event files
0056
0057 `HepMC3Reader` reads ASCII `.hepmc`/`.hepmc3` files into HepMC3 events. Use
0058 `HepMC3InputConverter` to turn those events into ACTS particles and vertices. In the other
0059 direction, `HepMC3OutputConverter` creates HepMC3 events for `HepMC3Writer`. These ASCII paths
0060 work without ROOT. Reading or writing HepMC3 ROOT files requires a ROOT-enabled build with
0061 HepMC3 ROOT I/O support.
0062
0063 ## Reading ACTS ROOT files with Uproot
0064
0065 `acts.examples.uproot` provides `UprootParticleReader` and `UprootSimHitReader`: pure-Python
0066 `IReader`s that read the exact file format written by `RootParticleWriter`/`RootSimHitWriter`,
0067 using [uproot](https://uproot.readthedocs.io/) without a ROOT-enabled ACTS build. They require
0068 `uproot` and `numpy` to be installed separately. For their `IReader` implementation, see
0069 @ref python_custom_algorithms.
0070
0071 # Loading detector geometry from JSON
0072
0073 To use a `TrackingGeometry` built with detector tooling such as DD4hep or TGeo in a PyPI-only
0074 script, export it to JSON in a source build and load the JSON file:
0075
0076 ```python
0077 import acts.json
0078
0079 gctx = acts.GeometryContext()
0080 converter = acts.json.TrackingGeometryJsonConverter()
0081 trackingGeometry = converter.fromFile(gctx, "geometry.json")
0082 ```
0083
0084 Material maps can be attached the same way with `acts.json.JsonMaterialDecorator`.
0085 The [geometry example](https://github.com/acts-project/acts/blob/main/Examples/Scripts/Python/geometry.py)
0086 shows how to produce such a JSON dump from an existing `TrackingGeometry` (`toFile`/`toJson`),
0087 using a source build with the relevant detector tooling enabled.
