README

groot

GoDoc

Experimental, pure-Go package to read and write ROOT files, without having ROOT installed.

Installation

go get go-hep.org/x/hep/groot

Documentation

groot documentation can be found over there:

https://godoc.org/go-hep.org/x/hep/groot

Expand ▾ Collapse ▴

Documentation

Overview

Package groot provides a pure-go read/write-access to ROOT files.

A typical usage is as follows:

f, err := groot.Open("ntup.root")
if err != nil {
    log.Fatal(err)
}
defer f.Close()

obj, err := f.Get("tree")
if err != nil {
    log.Fatal(err)
}
tree := obj.(rtree.Tree)
fmt.Printf("entries= %v\n", tree.Entries())

More complete examples on how to iterate over the content of a Tree can be found in the examples attached to groot.TreeScanner and groot.Scanner: https://godoc.org/go-hep.org/x/hep/groot/rtree#pkg-examples

Another possibility is to look at: https://godoc.org/go-hep.org/x/hep/groot/cmd/root-ls, a command that inspects the content of ROOT files.

File layout

ROOT files are a suite of consecutive data records. Each data record consists of a header part, called a TKey, and a payload whose content, length and meaning are described by the header. The current ROOT file format encodes all data in big endian.

ROOT files initially only supported 32b addressing. Large files support (>4Gb) was added later on by migrating to a 64b addressing.

The on-disk binary layout of a ROOT file header looks like this:

     Type        | Record Name | Description
=================+=============+===========================================
   [4]byte       | "root"      | Root file identifier
   int32         | fVersion    | File format version
   int32         | fBEGIN      | Pointer to first data record
   int32 [int64] | fEND        | Pointer to first free word at the EOF
   int32 [int64] | fSeekFree   | Pointer to FREE data record
   int32         | fNbytesFree | Number of bytes in FREE data record
   int32         | nfree       | Number of free data records
   int32         | fNbytesName | Number of bytes in TNamed at creation time
   byte          | fUnits      | Number of bytes for file pointers
   int32         | fCompress   | Compression level and algorithm
   int32 [int64] | fSeekInfo   | Pointer to TStreamerInfo record
   int32         | fNbytesInfo | Number of bytes in TStreamerInfo record
   [18]byte      | fUUID       | Universal Unique ID
=================+=============+===========================================

This is followed by a sequence of data records, starting at the fBEGIN offset from the beginning of the file.

The on-disk binary layout of a data record is:

      Type     | Member Name | Description
===============+=============+===========================================
 int32         | Nbytes      | Length of compressed object (in bytes)
 int16         | Version     | TKey version identifier
 int32         | ObjLen      | Length of uncompressed object
 int32         | Datime      | Date and time when object was written to file
 int16         | KeyLen      | Length of the key structure (in bytes)
 int16         | Cycle       | Cycle of key
 int32 [int64] | SeekKey     | Pointer to record itself (consistency check)
 int32 [int64] | SeekPdir    | Pointer to directory header
 byte          | lname       | Number of bytes in the class name
 []byte        | ClassName   | Object Class Name
 byte          | lname       | Number of bytes in the object name
 []byte        | Name        | Name of the object
 byte          | lTitle      | Number of bytes in the object title
 []byte        | Title       | Title of the object
 []byte        | DATA        | Data bytes associated to the object
===============+=============+===========================================

The high-level on-disk representation of a ROOT file is thus:

+===============+ -- 0
|               |
|  File Header  |
|               |
+===============+ -- fBEGIN offset
|               |
| Record Header | -->-+
|               |     |
+---------------+     |
|               |     |
|  Record Data  |     | Reference to next Record
|    Payload    |     |
|               |     |
+===============+ <---+
|               |
| Record Header | -->-+
|               |     |
+---------------+     |
|               |     |
|  Record Data  |     | Reference to next Record
|    Payload    |     |
|               |     |
+===============+ <---+
|               |
       ...

|               |
+===============+ -- fSeekInfo
|               |
| Record Header | -->-+
|               |     |
+---------------+     |
|               |     |
|  Record Data  |     | Reference to next Record
|    Payload    |     |
|               |     |
+===============+ <---+ -- fEND offset

Data records payloads and how to deserialize them are described by a TStreamerInfo. The list of all TStreamerInfos that are used to interpret the content of a ROOT file is stored at the end of that ROOT file, at offset fSeekInfo.

Data records

Data records' payloads may be compressed. Detecting whether a payload is compressed is usually done by comparing the object length (ObjLen) field of the record header with the length of the compressed object (Nbytes) field. If they differ after having subtracted the record header length, then the payload has been compressed.

A record data payload is itself split into multiple chunks of maximum size 16*1024*1024 bytes. Each chunk consists of:

- the chunk header,
- the chunk compressed payload.

The chunk header:

- 3 bytes to identify the compression algorithm and version,
- 3 bytes to identify the deflated buffer size,
- 3 bytes to identify the inflated buffer size.

Streamer informations

Streamers describe how a given type, for a given version of that type, is written on disk. In C++/ROOT, a streamer is represented as a TStreamerInfo class that can give metadata about the type it's describing (version, name). When reading a file, all the streamer infos are read back in memory, from disk, by reading the data record at offset fSeekInfo. A streamer info is actually a list of streamer elements, one for each field and, in C++, base class (in Go, this is emulated as an embedded field.)

TODO: groot can not write trees yet.

Index

Examples

Constants

View Source
const (
	Version = root.Version // ROOT version hep/groot implements
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Array

type Array interface {
	Len() int // number of array elements
	Get(i int) interface{}
	Set(i int, v interface{})
}

    Array describes ROOT abstract array type.

    type Collection

    type Collection interface {
    	Object
    
    	// Name returns the name of the collection.
    	Name() string
    
    	// Last returns the last element index
    	Last() int
    
    	// At returns the element at index i
    	At(i int) Object
    
    	// Len returns the number of elements in the collection
    	Len() int
    }

      Collection is a collection of ROOT Objects.

      type File

      type File = riofs.File

      func Create

      func Create(name string, opts ...FileOption) (*File, error)

        Create creates the named ROOT file for writing.

        Example
        Output:
        
        wkeys: 1
        rkeys: 1
        key: name="my-objstring", type="TObjString"
        objstring="Hello World from Go-HEP!"
        
        Example (EmptyFile)
        Output:
        
        file: "empty.root"
        
        Example (WithZlib)
        Output:
        
        key: name="my-objstring", type="TObjString"
        objstring="Hello World from Go-HEP!"
        

        func NewReader

        func NewReader(r Reader) (*File, error)

          NewReader creates a new ROOT file reader.

          func Open

          func Open(path string) (*File, error)

            Open opens the named ROOT file for reading. If successful, methods on the returned file can be used for reading; the associated file descriptor has mode os.O_RDONLY.

            Example
            Output:
            
            key:  "tree" cycle=1 title="fake data"
            tree: "tree", entries=4
            
            Example (Graph)
            Output:
            
            name:  "tg"
            title: "graph without errors"
            #pts:  4
            (x,y)[0] = (+1.000000e+00, +2.000000e+00)
            (x,y)[1] = (+2.000000e+00, +4.000000e+00)
            (x,y)[2] = (+3.000000e+00, +6.000000e+00)
            (x,y)[3] = (+4.000000e+00, +8.000000e+00)
            
            Example (OverXRootD)
            Output:
            
            key:  "Events" cycle=1 title="Events"
            tree: "Events", entries=29308627
            

            type FileOption

            type FileOption = riofs.FileOption

            type List

            type List interface {
            	SeqCollection
            }

              List is a list of ROOT Objects.

              type Named

              type Named interface {
              	Object
              
              	// Name returns the name of this ROOT object
              	Name() string
              
              	// Title returns the title of this ROOT object
              	Title() string
              }

                Named represents a ROOT TNamed object

                type ObjArray

                type ObjArray interface {
                	SeqCollection
                	LowerBound() int
                }

                  ObjArray is an array of ROOT Objects.

                  type ObjString

                  type ObjString interface {
                  	Name() string
                  	String() string
                  }

                    ObjString is a ROOT string that implements ROOT TObject.

                    type Object

                    type Object interface {
                    	// Class returns the ROOT class of this object
                    	Class() string
                    }

                      Object represents a ROOT object

                      type Reader

                      type Reader = riofs.Reader

                      type SeqCollection

                      type SeqCollection interface {
                      	Collection
                      }

                        SeqCollection is a sequential collection of ROOT Objects.

                        Source Files

                        Directories

                        Path Synopsis
                        cmd
                        root-cp
                        root-cp selects and copies keys from a ROOT file to another ROOT file.
                        root-cp selects and copies keys from a ROOT file to another ROOT file.
                        root-diff
                        root-diff compares the content of 2 ROOT files, including the content of their Trees (for all entries), if any.
                        root-diff compares the content of 2 ROOT files, including the content of their Trees (for all entries), if any.
                        root-dump
                        root-dump dumps the content of a ROOT file, including the content of the Trees (for all entries), if any.
                        root-dump dumps the content of a ROOT file, including the content of the Trees (for all entries), if any.
                        root-gen-datareader
                        Command root-gen-datareader generates a Go struct to easily read the event data type stored inside a Tree.
                        Command root-gen-datareader generates a Go struct to easily read the event data type stored inside a Tree.
                        root-gen-rfunc
                        Command root-gen-rfunc generates a rfunc.Formula based on a function signature or an already existing function.
                        Command root-gen-rfunc generates a rfunc.Formula based on a function signature or an already existing function.
                        root-gen-streamer
                        Command root-gen-streamer generates a StreamerInfo for ROOT and user types.
                        Command root-gen-streamer generates a StreamerInfo for ROOT and user types.
                        root-gen-type
                        Command root-gen-type generates a Go type from the StreamerInfo contained in a ROOT file.
                        Command root-gen-type generates a Go type from the StreamerInfo contained in a ROOT file.
                        root-ls
                        root-ls lists the content of a ROOT file.
                        root-ls lists the content of a ROOT file.
                        root-merge
                        root-merge merges ROOT files' content into a merged ROOT file.
                        root-merge merges ROOT files' content into a merged ROOT file.
                        root-print
                        root-print prints ROOT files contents to PDF, PNG, ...
                        root-print prints ROOT files contents to PDF, PNG, ...
                        root-split
                        root-split splits an input file+tree into multiple output ROOT files, each containing N entries.
                        root-split splits an input file+tree into multiple output ROOT files, each containing N entries.
                        root-srv
                        root-srv runs a web server that can inspect and browse ROOT files.
                        root-srv runs a web server that can inspect and browse ROOT files.
                        exp
                        rntup
                        Package rntup contains types to handle RNTuple-related data.
                        Package rntup contains types to handle RNTuple-related data.
                        Package rarrow handles conversion between ROOT and ARROW data models.
                        Package rarrow handles conversion between ROOT and ARROW data models.
                        Package rbase contains the definitions of ROOT base classes.
                        Package rbase contains the definitions of ROOT base classes.
                        Package rbytes contains the definitions of types useful for serializing and deserializing ROOT data buffers.
                        Package rbytes contains the definitions of types useful for serializing and deserializing ROOT data buffers.
                        Package rcmd provides helper functions containing the logic of various root-xyz commands.
                        Package rcmd provides helper functions containing the logic of various root-xyz commands.
                        Package rcont contains the definitions of ROOT container types, such as TList, THashList and TObjArray.
                        Package rcont contains the definitions of ROOT container types, such as TList, THashList and TObjArray.
                        Package rdict contains the definition of ROOT streamers and facilities to generate new streamers meta data from user types.
                        Package rdict contains the definition of ROOT streamers and facilities to generate new streamers meta data from user types.
                        Package rhist contains the interfaces and definitions of ROOT types related to histograms and graphs.
                        Package rhist contains the interfaces and definitions of ROOT types related to histograms and graphs.
                        Package riofs contains the types and low-level functions to deal with opening and creating ROOT files, and decoding the internal structure of ROOT files.
                        Package riofs contains the types and low-level functions to deal with opening and creating ROOT files, and decoding the internal structure of ROOT files.
                        plugin/http
                        Package http is a plugin for riofs.Open to support opening ROOT files over http(s).
                        Package http is a plugin for riofs.Open to support opening ROOT files over http(s).
                        plugin/xrootd
                        Package xrootd is a plugin for riofs.Open to support opening ROOT files over xrootd.
                        Package xrootd is a plugin for riofs.Open to support opening ROOT files over xrootd.
                        Package rmeta provides tools to interoperate with ROOT Meta.
                        Package rmeta provides tools to interoperate with ROOT Meta.
                        Package root defines ROOT core interfaces.
                        Package root defines ROOT core interfaces.
                        Package rphys contains definitions for physics-related ROOT classes.
                        Package rphys contains definitions for physics-related ROOT classes.
                        Package rsql provides a convenient access to ROOT files/trees as a database.
                        Package rsql provides a convenient access to ROOT files/trees as a database.
                        rsqldrv
                        Package rsqldrv registers a database/sql/driver.Driver implementation for ROOT files.
                        Package rsqldrv registers a database/sql/driver.Driver implementation for ROOT files.
                        Package rsrv exposes HTTP end-points to manipulate ROOT files.
                        Package rsrv exposes HTTP end-points to manipulate ROOT files.
                        Package rtree contains the interfaces and types to decode, read, concatenate and iterate over ROOT Trees.
                        Package rtree contains the interfaces and types to decode, read, concatenate and iterate over ROOT Trees.
                        rfunc
                        Package rfunc provides types and funcs to implement user-provided formulae evaluated on data exposed by ROOT trees.
                        Package rfunc provides types and funcs to implement user-provided formulae evaluated on data exposed by ROOT trees.
                        Package rtypes contains the means to register types (ROOT ones and user defined ones) with the ROOT type factory.
                        Package rtypes contains the means to register types (ROOT ones and user defined ones) with the ROOT type factory.
                        Package rvers contains the ROOT version and the classes' versions groot is supporting and currently reading.
                        Package rvers contains the ROOT version and the classes' versions groot is supporting and currently reading.
                        Package ztypes holds all the types registered with the rtypes factory.
                        Package ztypes holds all the types registered with the rtypes factory.
                        internal
                        rcompress
                        rcompress provides types and functions to compress and decompress ROOT data payloads.
                        rcompress provides types and functions to compress and decompress ROOT data payloads.