1[/ 2 Copyright Hans Dembinski 2018 - 2019. 3 Distributed under the Boost Software License, Version 1.0. 4 (See accompanying file LICENSE_1_0.txt or copy at 5 https://www.boost.org/LICENSE_1_0.txt) 6] 7 8[section:getting_started Getting started] 9 10Here are some commented examples to copy-paste from, this should allow you to kick off a project with Boost.Histogram. If you prefer a traditional structured exposition, go to the [link histogram.guide user guide]. 11 12Boost.Histogram uses /axis/ objects to convert input values into indices. The library comes with several builtin axis types, which can be configured via template parameters. This already gives you a lot of flexibility should you need it, otherwise just use the defaults. Beyond that, you can easily write your own axis type. 13 14[section 1d-histogram with axis types known at compile-time] 15 16When the axis types for the histogram are known at compile-time, the library generates the fastest and most efficient code for you. Here is such an example. 17 18[import ../examples/getting_started_listing_01.cpp] 19[getting_started_listing_01] 20 21We passed the [classref boost::histogram::axis::regular regular] axis type directly to the [headerref boost/histogram/make_histogram.hpp make_histogram] function. The library then generates a specialized histogram type with just one regular axis from a generic template. 22 23* Pro: Many user errors are already caught at compile-time, not at run-time. 24* Con: You get template errors if you make a mistake, which may be hard to read. We try to give you useful error messages, but still. 25 26[endsect] 27 28[section 3d-histogram (axis configuration defined at run-time)] 29 30Sometimes, you don't know the number or types of axes at compile-time, because it depends on run-time information. Perhaps you want to write a command-line tool that generates histograms from input data, or you use this library as a back-end for a product with a GUI. This is possible as well, here is the example. 31 32[import ../examples/getting_started_listing_02.cpp] 33[getting_started_listing_02] 34 35The axis configuration is passed to `make_histogram` as a `std::vector<axis::variant<...>>`, which can hold arbitrary sequences of axis types from a predefined set. 36 37Run-time configurable histograms are a slower than their compile-time brethren, but still pretty fast. 38 39[note 40If you know already at compile-time that you will only use one axis type, `axis::regular<>` for example, but not how many per histogram, then you can also pass a `std::vector<axis::regular<>>` to `make_histogram`. You get almost the same speed as in the very first case, where both the axis configuration was fully known at compile-time. 41] 42 43[note 44If you care about maximum performance: In this example, `axis::category<std::string>` is used with two string labels "red" and "blue". It is faster to use an enum, `enum { red, blue };` and a `axis::category<>` axis. 45] 46 47[endsect] 48 49[section 1d-profile] 50 51The library was designed to be very flexible and modular. The modularity is used, for example, to also provide profiles. Profiles are generalized histograms. A histogram counts how often an input falls into a particular cell. A profile accepts pairs of input values and a sample value. The profile computes the mean of the samples that end up in each cell. Have a look at the example, which should clear up any confusion. 52 53[import ../examples/getting_started_listing_03.cpp] 54[getting_started_listing_03] 55 56[endsect] 57 58[section Standard library algorithms] 59 60The library was designed to work well with the C++ standard library. Here is an example on how to get the most common color from an image, using a 3d histogram and `std::max_element`. 61 62[import ../examples/getting_started_listing_04.cpp] 63[getting_started_listing_04] 64 65[endsect] 66 67[section Making classes that hold histograms] 68 69The histograms get their great flexibility and performance from being templated, but this can make the types a bit cumbersome to write. Often it is possible to use `auto` to let the compiler deduce the type, but when you want to store histograms in a class, you need to write the type explicitly. The next example shows how this works. 70 71[import ../examples/getting_started_listing_05.cpp] 72[getting_started_listing_05] 73 74[endsect] 75 76[endsect] 77