Python API Reference¶

Core Classes¶

Schema¶

Defines the structure (columns and types) of a bank.

Schema()
Schema(name: str, group: int, item: int)

Property / Method	Returns	Description
`schema.name`	`str`	Bank name (e.g., `"REC::Particle"`)
`schema.group`	`int`	Group number
`schema.item`	`int`	Item number
`schema.entries`	`int`	Number of columns
`schema.row_length`	`int`	Bytes per row
`schema.parse(definition)`	--	Parse column definitions (e.g., `"pid/I,px/F"`)
`schema.get_entry_order(name)`	`int`	Column index by name (-1 if not found)
`schema.get_entry_type(index)`	`int`	Column type code (1=B, 2=S, 3=I, 4=F, 5=D, 8=L)
`schema.get_entry_type(name)`	`int`	Column type code by name
`schema.get_entry_name(index)`	`str`	Column name by index
`schema.exists(name)`	`bool`	Check if column exists
`schema.get_schema_string()`	`str`	Schema definition string
`len(schema)`	`int`	Number of columns

Dictionary¶

Collection of schemas, typically read from a HIPO file header.

Dictionary()

Method	Returns	Description
`dict.add_schema(schema)`	--	Register a schema
`dict.has_schema(name)`	`bool`	Check if schema exists
`dict.get_schema(name)`	`Schema`	Get schema by name
`dict.get_schema_list()`	`list[str]`	List all schema names
`dict.show()`	--	Print all schemas
`name in dict`	`bool`	Contains check
`dict[name]`	`Schema`	Get schema by name
`len(dict)`	`int`	Number of schemas

Bank¶

Tabular data container with typed columns. Banks hold the actual data in HIPO events.

Bank()
Bank(schema: Schema)
Bank(schema: Schema, rows: int)

Method	Returns	Description
`bank.get_rows()`	`int`	Number of rows
`bank.set_rows(n)`	--	Set number of rows
`bank.get_schema()`	`Schema`	Get associated schema
`bank.reset()`	--	Reset bank (0 rows)
`len(bank)`	`int`	Number of rows

Typed getters (by column name):

Method	Returns
`bank.get_int(name, row)`	`int`
`bank.get_short(name, row)`	`int`
`bank.get_byte(name, row)`	`int`
`bank.get_float(name, row)`	`float`
`bank.get_double(name, row)`	`float`
`bank.get_long(name, row)`	`int`

Typed setters (by column name):

Method	Description
`bank.put_int(name, row, value)`	Set int32 value
`bank.put_short(name, row, value)`	Set int16 value
`bank.put_byte(name, row, value)`	Set int8 value
`bank.put_float(name, row, value)`	Set float value
`bank.put_double(name, row, value)`	Set double value
`bank.put_long(name, row, value)`	Set int64 value

Index-based variants are also available: get_int_by_index(col, row), put_int_by_index(col, row, value), etc.

NumPy array access:

arr = bank.get_array("px")              # copy (safe)
arr = bank.get_array("px", copy=False)  # zero-copy view (unsafe across events)
arr = bank["px"]                        # shorthand, always copies

Warning

copy=False returns a view into the bank's internal buffer. This buffer is overwritten when event.read(bank) is called for the next event. Only use copy=False when you will consume the data before advancing to the next event.

Event¶

Container for one event's worth of bank data.

Event()
Event(size: int)

Method	Returns	Description
`event.read(bank)`	--	Read bank data from this event
`event.add_structure(bank)`	--	Add a bank to this event
`event.remove(bank)`	--	Remove a bank from this event
`event.replace(bank)`	--	Replace a bank in this event
`event.get_tag()`	`int`	Get event tag
`event.set_tag(tag)`	--	Set event tag
`event.get_size()`	`int`	Event buffer size in bytes
`event.reset()`	--	Clear all banks

Reader¶

Reads HIPO files sequentially.

Reader()
Reader(filename: str)

Method	Returns	Description
`reader.open(filename)`	--	Open a HIPO file
`reader.is_open()`	`bool`	Check if file is open
`reader.read_dictionary(dict)`	--	Load schemas from file header
`reader.next()`	`bool`	Advance to next event
`reader.read(event)`	--	Read current event data
`reader.has_next()`	`bool`	Check if more events exist
`reader.get_entries()`	`int`	Total number of events
`reader.goto_event(n)`	--	Seek to event number
`reader.rewind()`	--	Reset to beginning
`reader.set_tags(tag)`	--	Filter events by tag

Writer¶

Writes HIPO files.

Writer()

Method	Returns	Description
`writer.open(filename)`	--	Open file for writing
`writer.close()`	--	Close and finalize file
`writer.add_event(event)`	--	Write an event
`writer.add_dictionary(dict)`	--	Register schemas (call before `open`)
`writer.get_dictionary()`	`Dictionary`	Get registered dictionary
`writer.flush()`	--	Flush pending data

High-Level API¶

hipopy.open()¶

Context manager for convenient file reading:

hipopy.open(filename: str, banks: list[str] = None) -> HipoFile

HipoFile¶

Property / Method	Returns	Description
`f.dictionary`	`Dictionary`	File's schema dictionary
`f.entries`	`int`	Total number of events
`iter(f)`	yields `dict[str, Bank]`	Iterate events, yielding bank dict

Batch Reading¶

read_columns()¶

Read columns from all events into flat concatenated NumPy arrays:

hipopy.read_columns(
    filename: str,          # HIPO file path
    bank_name: str,         # e.g., "REC::Particle"
    columns: list[str] = None,  # column subset (None = all)
    max_events: int = -1    # limit events (-1 = all)
) -> dict[str, np.ndarray]

read_bank()¶

Read a bank into an Awkward Array with per-event ragged structure:

hipopy.read_bank(
    filename: str,          # HIPO file path
    bank_name: str,         # e.g., "REC::Particle"
    columns: list[str] = None,  # column subset (None = all)
    max_events: int = -1    # limit events (-1 = all)
) -> ak.Array

Note

Requires the awkward package. Install with pip install awkward.

Multi-File Access¶

Chain¶

File list management with iteration support:

Chain(threads: int = 0, progress: bool = True, verbose: bool = False)

Method	Returns	Description
`chain.add(filename)`	`int`	Add a file
`chain.add_pattern(glob)`	--	Add files by glob pattern
`chain.clear()`	--	Remove all files
`chain.size()`	`int`	Number of files
`chain.empty()`	`bool`	Whether chain is empty
`chain.open(validate_all)`	--	Open and validate files
`chain.set_tags(tags)`	--	Set event tag filter
`chain.set_threads(n)`	--	Set thread count
`len(chain)`	`int`	Number of files

InputSource¶

Single-file reader with bank-level access by name:

InputSource()
InputSource(filename: str)

Method	Returns	Description
`src.open(filename)`	--	Open file
`src.define(bank_name)`	--	Register a bank for reading
`src.next()`	`bool`	Advance to next event
`src.get_size(bank_name)`	`int`	Rows in bank
`src.get_int(bank, entry, row)`	`int`	Read int value
`src.get_float(bank, entry, row)`	`float`	Read float value
`src.get_double(bank, entry, row)`	`float`	Read double value

Fusion¶

Multi-handle reader for accessing multiple files simultaneously:

Fusion()

Method	Returns	Description
`fusion.open(filename)`	`int`	Open file, return handle
`fusion.define(handle, bank)`	--	Register bank on handle
`fusion.next(handle)`	`bool`	Advance handle to next event
`fusion.get_size(handle, bank)`	`int`	Rows in bank
`fusion.get_int(handle, bank, entry, row)`	`int`	Read value
`fusion.get_float(handle, bank, entry, row)`	`float`	Read value
`fusion.get_bank(handle, bank)`	`Bank`	Get bank object

Utilities¶

Parser¶

Mathematical expression evaluator:

Parser(expression: str)

Method	Returns	Description
`parser.evaluate()`	`float`	Evaluate with current variables
`parser.evaluate(expr)`	`float`	Evaluate a new expression
`parser[name] = value`	--	Set variable
`parser[name]`	`float`	Get variable

Node¶

Low-level data node with typed accessors:

Node()
Node(size: int)

Methods: size(), group(), item(), type(), get_int_at(i), get_float_at(i), get_double_at(i), put_int_at(i, v), etc.

Composite¶

Structured data with row/column access, extends Node:

Composite()
Composite(size: int)

Methods: parse(format), get_rows(), get_entries(), get_int(element, row), get_float(element, row), put_int(element, row, value), etc.

Tuple¶

Write flat n-tuple files:

Tuple()
Tuple(format: str)

Methods: open(filename), fill(values: list[float]), close().

RowList¶

Row filtering for banks:

RowList()

Method	Description
`rl.set_list(indices)`	Set active row indices
`rl.get_list()`	Get current indices
`rl.filter(expression)`	Filter by string expression
`rl.filter(func)`	Filter by Python callable
`rl.filter(parser)`	Filter by Parser object
`rl.reset(num_rows)`	Reset to all rows
`len(rl)`	Number of active rows

Exceptions¶

Exception	C++ Origin	Description
`hipopy.FileError`	`hipo::file_error`	File I/O errors
`hipopy.SchemaError`	`hipo::schema_error`	Schema lookup/parsing errors
`hipopy.RecordError`	`hipo::record_error`	Record read/write errors