go-hep.org/x/hep@v0.38.1/hbook/README.md (about)

     1  hbook
     2  =====
     3  
     4  [![GoDoc](https://godoc.org/go-hep.org/x/hep/hbook?status.svg)](https://godoc.org/go-hep.org/x/hep/hbook)
     5  
     6  `hbook` is a set of data analysis tools for HEP (histograms (1D, 2D, 3D), profiles and ntuples).
     7  
     8  `hbook` is a work in progress of a concurrent friendly histogram filling toolkit.
     9  It is loosely based on `AIDA` interfaces and concepts as well as the "simplicity" of `HBOOK` and the previous work of `YODA`.
    10  
    11  ## Installation
    12  
    13  ```sh
    14  $ go get go-hep.org/x/hep/hbook
    15  ```
    16  
    17  ## Documentation
    18  
    19  Documentation is available on godoc:
    20  
    21   https://godoc.org/go-hep.org/x/hep/hbook
    22  
    23  ## Example
    24  
    25  ### H1D
    26  
    27  [embedmd]:# (h1d_example_test.go go /func ExampleH1D/ /\n}/)
    28  ```go
    29  func ExampleH1D() {
    30  	const npoints = 10000
    31  
    32  	// Create a normal distribution.
    33  	dist := distuv.Normal{
    34  		Mu:    0,
    35  		Sigma: 1,
    36  		Src:   rand.New(rand.NewPCG(0, 0)),
    37  	}
    38  
    39  	// Draw some random values from the standard
    40  	// normal distribution.
    41  	h := hbook.NewH1D(20, -4, +4)
    42  	for range npoints {
    43  		v := dist.Rand()
    44  		h.Fill(v, 1)
    45  	}
    46  	// fill h with a slice of values and their weights
    47  	h.FillN([]float64{1, 2, 3}, []float64{1, 1, 1})
    48  	h.FillN([]float64{1, 2, 3}, nil) // all weights are 1.
    49  
    50  	fmt.Printf("mean:    %.12f\n", h.XMean())
    51  	fmt.Printf("rms:     %.12f\n", h.XRMS())
    52  	fmt.Printf("std-dev: %.12f\n", h.XStdDev())
    53  	fmt.Printf("std-err: %.12f\n", h.XStdErr())
    54  
    55  	// Output:
    56  	// mean:    0.002104228518
    57  	// rms:     1.000617135827
    58  	// std-dev: 1.000664927794
    59  	// std-err: 0.010003648633
    60  }
    61  ```
    62  
    63  [embedmd]:# (h1d_example_test.go go /func ExampleAddH1D/ /\n}/)
    64  ```go
    65  func ExampleAddH1D() {
    66  
    67  	h1 := hbook.NewH1D(6, 0, 6)
    68  	h1.Fill(-0.5, 1)
    69  	h1.Fill(0, 1.5)
    70  	h1.Fill(0.5, 1)
    71  	h1.Fill(1.2, 1)
    72  	h1.Fill(2.1, 2)
    73  	h1.Fill(4.2, 1)
    74  	h1.Fill(5.9, 1)
    75  	h1.Fill(6, 0.5)
    76  
    77  	h2 := hbook.NewH1D(6, 0, 6)
    78  	h2.Fill(-0.5, 0.7)
    79  	h2.Fill(0.2, 1)
    80  	h2.Fill(0.7, 1.2)
    81  	h2.Fill(1.5, 0.8)
    82  	h2.Fill(2.2, 0.7)
    83  	h2.Fill(4.3, 1.3)
    84  	h2.Fill(5.2, 2)
    85  	h2.Fill(6.8, 1)
    86  
    87  	hsum := hbook.AddH1D(h1, h2)
    88  	fmt.Printf("Under: %.1f +/- %.1f\n", hsum.Binning.Outflows[0].SumW(), math.Sqrt(hsum.Binning.Outflows[0].SumW2()))
    89  	for i := range hsum.Len() {
    90  		fmt.Printf("Bin %v: %.1f +/- %.1f\n", i, hsum.Binning.Bins[i].SumW(), math.Sqrt(hsum.Binning.Bins[i].SumW2()))
    91  	}
    92  	fmt.Printf("Over : %.1f +/- %.1f\n", hsum.Binning.Outflows[1].SumW(), math.Sqrt(hsum.Binning.Outflows[1].SumW2()))
    93  
    94  	// Output:
    95  	// Under: 1.7 +/- 1.2
    96  	// Bin 0: 4.7 +/- 2.4
    97  	// Bin 1: 1.8 +/- 1.3
    98  	// Bin 2: 2.7 +/- 2.1
    99  	// Bin 3: 0.0 +/- 0.0
   100  	// Bin 4: 2.3 +/- 1.6
   101  	// Bin 5: 3.0 +/- 2.2
   102  	// Over : 1.5 +/- 1.1
   103  }
   104  ```
   105  [embedmd]:# (h1d_example_test.go go /func ExampleAddScaledH1D/ /\n}/)
   106  ```go
   107  func ExampleAddScaledH1D() {
   108  
   109  	h1 := hbook.NewH1D(6, 0, 6)
   110  	h1.Fill(-0.5, 1)
   111  	h1.Fill(0, 1.5)
   112  	h1.Fill(0.5, 1)
   113  	h1.Fill(1.2, 1)
   114  	h1.Fill(2.1, 2)
   115  	h1.Fill(4.2, 1)
   116  	h1.Fill(5.9, 1)
   117  	h1.Fill(6, 0.5)
   118  
   119  	h2 := hbook.NewH1D(6, 0, 6)
   120  	h2.Fill(-0.5, 0.7)
   121  	h2.Fill(0.2, 1)
   122  	h2.Fill(0.7, 1.2)
   123  	h2.Fill(1.5, 0.8)
   124  	h2.Fill(2.2, 0.7)
   125  	h2.Fill(4.3, 1.3)
   126  	h2.Fill(5.2, 2)
   127  	h2.Fill(6.8, 1)
   128  
   129  	hsum := hbook.AddScaledH1D(h1, 10, h2)
   130  	fmt.Printf("Under: %.1f +/- %.1f\n", hsum.Binning.Outflows[0].SumW(), math.Sqrt(hsum.Binning.Outflows[0].SumW2()))
   131  	for i := range hsum.Len() {
   132  		fmt.Printf("Bin %v: %.1f +/- %.1f\n", i, hsum.Binning.Bins[i].SumW(), math.Sqrt(hsum.Binning.Bins[i].SumW2()))
   133  	}
   134  	fmt.Printf("Over : %.1f +/- %.1f\n", hsum.Binning.Outflows[1].SumW(), math.Sqrt(hsum.Binning.Outflows[1].SumW2()))
   135  
   136  	// Output:
   137  	// Under: 8.0 +/- 7.1
   138  	// Bin 0: 24.5 +/- 15.7
   139  	// Bin 1: 9.0 +/- 8.1
   140  	// Bin 2: 9.0 +/- 7.3
   141  	// Bin 3: 0.0 +/- 0.0
   142  	// Bin 4: 14.0 +/- 13.0
   143  	// Bin 5: 21.0 +/- 20.0
   144  	// Over : 10.5 +/- 10.0
   145  }
   146  ```
   147  [embedmd]:# (h1d_example_test.go go /func ExampleSubH1D/ /\n}/)
   148  ```go
   149  func ExampleSubH1D() {
   150  
   151  	h1 := hbook.NewH1D(6, 0, 6)
   152  	h1.Fill(-0.5, 1)
   153  	h1.Fill(0, 1.5)
   154  	h1.Fill(0.5, 1)
   155  	h1.Fill(1.2, 1)
   156  	h1.Fill(2.1, 2)
   157  	h1.Fill(4.2, 1)
   158  	h1.Fill(5.9, 1)
   159  	h1.Fill(6, 0.5)
   160  
   161  	h2 := hbook.NewH1D(6, 0, 6)
   162  	h2.Fill(-0.5, 0.7)
   163  	h2.Fill(0.2, 1)
   164  	h2.Fill(0.7, 1.2)
   165  	h2.Fill(1.5, 0.8)
   166  	h2.Fill(2.2, 0.7)
   167  	h2.Fill(4.3, 1.3)
   168  	h2.Fill(5.2, 2)
   169  	h2.Fill(6.8, 1)
   170  
   171  	hsub := hbook.SubH1D(h1, h2)
   172  	under := hsub.Binning.Outflows[0]
   173  	fmt.Printf("Under: %.1f +/- %.1f\n", under.SumW(), math.Sqrt(under.SumW2()))
   174  	for i, bin := range hsub.Binning.Bins {
   175  		fmt.Printf("Bin %v: %.1f +/- %.1f\n", i, bin.SumW(), math.Sqrt(bin.SumW2()))
   176  	}
   177  	over := hsub.Binning.Outflows[1]
   178  	fmt.Printf("Over : %.1f +/- %.1f\n", over.SumW(), math.Sqrt(over.SumW2()))
   179  
   180  	// Output:
   181  	// Under: 0.3 +/- 1.2
   182  	// Bin 0: 0.3 +/- 2.4
   183  	// Bin 1: 0.2 +/- 1.3
   184  	// Bin 2: 1.3 +/- 2.1
   185  	// Bin 3: 0.0 +/- 0.0
   186  	// Bin 4: -0.3 +/- 1.6
   187  	// Bin 5: -1.0 +/- 2.2
   188  	// Over : -0.5 +/- 1.1
   189  }
   190  ```
   191  
   192  ### H2D
   193  
   194  [embedmd]:# (h2d_example_test.go go /func ExampleH2D/ /\n}/)
   195  ```go
   196  func ExampleH2D() {
   197  	h := hbook.NewH2D(100, -10, 10, 100, -10, 10)
   198  
   199  	const npoints = 10000
   200  
   201  	dist, ok := distmv.NewNormal(
   202  		[]float64{0, 1},
   203  		mat.NewSymDense(2, []float64{4, 0, 0, 2}),
   204  		rand.New(rand.NewPCG(1234, 1234)),
   205  	)
   206  	if !ok {
   207  		log.Fatalf("error creating distmv.Normal")
   208  	}
   209  
   210  	v := make([]float64, 2)
   211  	// Draw some random values from the standard
   212  	// normal distribution.
   213  	for range npoints {
   214  		v = dist.Rand(v)
   215  		h.Fill(v[0], v[1], 1)
   216  	}
   217  
   218  	// fill h with slices of values and their weights
   219  	h.FillN(
   220  		[]float64{1, 2, 3}, // xs
   221  		[]float64{1, 2, 3}, // ys
   222  		[]float64{1, 1, 1}, // ws
   223  	)
   224  
   225  	// fill h with slices of values. all weights are 1.
   226  	h.FillN(
   227  		[]float64{1, 2, 3}, // xs
   228  		[]float64{1, 2, 3}, // ys
   229  		nil,                // ws
   230  	)
   231  }
   232  ```
   233  
   234  ### S2D
   235  
   236  [embedmd]:# (s2d_example_test.go go /func ExampleS2D/ /\n}/)
   237  ```go
   238  func ExampleS2D() {
   239  	s := hbook.NewS2D(hbook.Point2D{X: 1, Y: 1}, hbook.Point2D{X: 2, Y: 1.5}, hbook.Point2D{X: -1, Y: +2})
   240  	if s == nil {
   241  		log.Fatal("nil pointer to S2D")
   242  	}
   243  
   244  	fmt.Printf("len=%d\n", s.Len())
   245  
   246  	s.Fill(hbook.Point2D{X: 10, Y: -10, ErrX: hbook.Range{Min: 5, Max: 5}, ErrY: hbook.Range{Min: 6, Max: 6}})
   247  	fmt.Printf("len=%d\n", s.Len())
   248  	fmt.Printf("pt[%d]=%+v\n", 3, s.Point(3))
   249  
   250  	// Output:
   251  	// len=3
   252  	// len=4
   253  	// pt[3]={X:10 Y:-10 ErrX:{Min:5 Max:5} ErrY:{Min:6 Max:6}}
   254  }
   255  ```
   256  
   257  ### Ntuple
   258  
   259  #### Open an existing n-tuple
   260  
   261  ```go
   262  package main
   263  
   264  import (
   265  	"database/sql"
   266  	"fmt"
   267  
   268  	_ "go-hep.org/x/hep/csvutil/csvdriver"
   269  	"go-hep.org/x/hep/hbook/ntup"
   270  )
   271  
   272  func main() {
   273  	db, err := sql.Open("csv", "data.csv")
   274  	if err != nil {
   275  		panic(err)
   276  	}
   277  	defer db.Close()
   278  
   279  	nt, err := ntup.Open(db, "csv")
   280  	if err != nil {
   281  		panic(err)
   282  	}
   283  
   284  	h1, err := nt.ScanH1D("px where pt>100", nil)
   285  	if err != nil {
   286  		panic(err)
   287  	}
   288  	fmt.Printf("h1: %v\n", h1)
   289  
   290  	h2 := hbook.NewH1D(100, -10, 10)
   291  	h2, err = nt.ScanH1D("px where pt>100 && pt < 1000", h2)
   292  	if err != nil {
   293  		panic(err)
   294  	}
   295  	fmt.Printf("h2: %v\n", h2)
   296  
   297  	h11 := hbook.NewH1D(100, -10, 10)
   298  	h22 := hbook.NewH1D(100, -10, 10)
   299  	err = nt.Scan("px, py where pt>100", func(px, py float64) error {
   300  		h11.Fill(px, 1)
   301  		h22.Fill(py, 1)
   302  		return nil
   303  	})
   304  	if err != nil {
   305  		panic(err)
   306  	}
   307  	fmt.Printf("h11: %v\n", h11)
   308  	fmt.Printf("h22: %v\n", h22)
   309  }
   310  ```