EIC code displayed by LXR master/​firebird/​packages/​root2dex/​README.md	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

Warning, /firebird/packages/root2dex/README.md is written in an unsupported language. File is not indexed.

 # @dexvis/root2dex
 
 Converts EDM4eic / EDM4hep podio ROOT files to Firebird DEX, in the browser or
 in node, through the JSROOT API.
 
 This is the TypeScript twin of `pyrobird convert`. For the same input file,
 entries and options the two produce the same DEX document, value for value -
 `src/parity.spec.ts` pins that against reference documents written by pyrobird.
 One default differs: pyrobird keeps its own list of Cherenkov collections out
 of the EDM4hep MC-truth trajectories, and this package keeps none out until
 you name them in `trajectoryExcludedCollections`.
 
 ```ts
 import { Root2DexConverter } from '@dexvis/root2dex';
 
 const converter = await Root2DexConverter.open(file);   // File, URL, path, or byte-range source
 console.log(converter.model, converter.entryCount);      // 'edm4eic' | 'edm4hep', number of events
 const dex = await converter.convert(eventNumber);        // a DEX 1.0 document
 ```
 
 One-shot form, equivalent to the CLI:
 
 ```ts
 const dex = await convertRootToDex('https://host/reco.edm4eic.root', '0-4');
 ```
 
 ## Entry selections
 
 Entries are written as `3`, `1-5` or `1,2-5,8`. Entries the file does not
 hold are dropped with one warning (through `options.onWarning`, or
 `console.warn` without it): `0-99` on a 10-entry file converts entries 0-9.
 A selection with no entry in the file throws `EntrySelectionError`, and the
 message names the file's entry count. pyrobird applies the same rules with
 the same messages.
 
 The `@dexvis/root2dex/entries` subpath holds the selection helpers
 (`parseEntryRanges`, `selectEntries`, `DEFAULT_MAX_ENTRIES`) without the
 converter and its jsroot import.
 
 ## Only the requested event is read
 
 Event files are routinely many GB, so nothing ever loads the whole file.
 JSROOT reads the key directory, the streamer info and the TTree metadata when
 the file is opened, and after that only the baskets covering the requested
 entry. Measured on the repository's test files:
 
 | file | size | open | per event |
 |---|---|---|---|
 | `reco_2024-09_craterlake_2evt.edm4eic.root` | 0.94 MB | 0.26 MB | 22 kB |
 | `k_lambda_10x100_2evt.edm4hep.root` | 1.22 MB | 0.05 MB | 29 kB |
 
 The open cost is paid once per file, not once per event, which is why
 `Root2DexConverter` keeps the file open. All the branches an event needs are
 read in ONE `treeProcess` pass so their baskets go out as few requests — a pass
 per column would multiply the round trips by the number of columns.
 
 Sources `Root2DexConverter.open` accepts:
 
 - a browser `File` (file picker or drag-and-drop) — read with `Blob.slice`
 - an `http(s)` URL — HTTP Range requests
 - a path or `file://` URL under node
 - anything built with `createByteRangeSource()` — you supply
   `readRange(pos, len)`, and optionally `readRanges([...])` when the transport
   can answer several ranges in one round trip. This is where a remote XRootD
   byte-range proxy plugs in; nothing else in the package changes.
 
 ## What is converted
 
 Matching pyrobird's `edm4eic.py` and `edm4hep.py`:
 
 **edm4eic** (`tracker_hits`, `tracks`)
 - every `vector<edm4eic::TrackerHitData>` collection → a `BoxHit` piece, box
   dimensions from `positionError` (±1σ). Empty collections are kept as count-0
   pieces.
 - `CentralTrackSegments` + its `TrackPoint`s → one `PointTrajectory` piece,
   parameters taken positionally from `CentralCKFTrackParameters` (the one-to-one
   relation to Track cannot be followed — EICrecon issue #1730).
 
 **edm4hep** (`tracker_hits`, `mc_trajectories`)
 - every `vector<edm4hep::SimTrackerHitData>` collection → a `BoxHit` piece with
   a fixed box size (sim hits carry no errors). Collections empty in this event
   are dropped.
 - MC-truth trajectories: hits pooled across collections, grouped by their
   `MCParticle`, sorted by time, one `PointTrajectory` piece. Collections named
   in the `trajectoryExcludedCollections` option (default: none) stay out of
   trajectory building and still appear as `BoxHit` pieces. Name the
   Cherenkov/PID collections there: their photon hits are attributed to the
   emitting charged particle and draw zigzags.
 
 The data model is detected from the branch types — files carrying both win as
 `edm4eic` — and can be overridden with the `model` option.
 
 ## Tests
 
 ```bash
 npm test -w @dexvis/root2dex
 ```
 
 The specs read pyrobird's test ROOT files from `pyrobird/tests/unit_tests/data`
 and the reference DEX documents in `test-data/`; they skip themselves when
 those files are absent.

This page was automatically generated by the 2.3.7 LXR engine. The LXR team