Package: clusterking
Clustering of Kinematic GraphsDescriptionThis package provides a flexible yet easy to use framework to cluster sets of
histograms (or other higher dimensional data) and to select benchmark points
representing each cluster. The package particularly focuses on use cases in
high energy physics.A physics use case has been demonstrated inhttps://arxiv.org/abs/1909.11088.Physics CaseWhile most of this package is very general and can be applied to a broad variety
of use cases, we have been focusing on applications in high energy physics
(particle physics) so far and provide additional convenience methods for this
use case. In particular, most of the current tutorials are in this context.Though very successful, the Standard Model of Particle Physics is believed to
be uncomplete, prompting the search for New Physics (NP). The phenomenology
of NP models typically depends on a number of free parameters, sometimes
strongly influencing the shape of distributions of kinematic variables.
Besides being an obvious challenge when presenting exclusion limits on such
models, this also is an issue for experimental analyses that need to make
assumptions on kinematic distributions in order to extract features of
interest, but still want to publish their results in a very general way.By clustering the NP parameter space based on a metric that quantifies the
similarity of the resulting kinematic distributions, a small number of NP
benchmark points can be chosen in such a way that they can together represent
the whole parameter space. Experiments (and theorists) can then report
exclusion limits and measurements for these benchmark points without
sacrificing generality.Installationclusterkingcan be installed/upgraded with thepython package installer:pip3install--user--upgrade"clusterking[plotting]"If you do not require plotting, you can remove[plotting].More options and troubleshooting advice is given in thedocumentation.CaveatsVersion 1.0.0 contained several mistakes in the chi2 metric. Please make sure
that you are at least using versoin 1.1.0. These mistakes were also found in
thepaperand will be fixed soon.Usage and DocumentationGood starting point:Jupyter notebooksin theexamples/jupyter_notebookdirectory.
You can also try running them online right now (without any installation required) usingbinder(just note that this is somewhat unstable, slow and takes some time
to start up).For a documentation of the classes and functions in this package,read the docs onreadthedocs.io.For additional examples, presentations and more, you can also head to ourother repositories.ExampleSampleThe following code (taken fromexamples/jupyter_notebook/010_basic_tutorial.ipynb) is all that
is needed to cluster the shape of theq^2distribution ofB->D tau nuin the space of Wilson coefficients:importflavioimportnumpyasnpimportclusterkingascks=ck.scan.WilsonScanner(scale=5,eft='WET',basis='flavio')# Set up kinematic functiondefdBrdq2(w,q):returnflavio.np_prediction("dBR/dq2(B+->Dtaunu)",w,q)s.set_dfunction(dBrdq2,binning=np.linspace(3.2,11.6,10),normalize=True)# Set sampling points in Wilson spaces.set_spoints_equidist({"CVL_bctaunutau":(-1,1,10),"CSL_bctaunutau":(-1,1,10),"CT_bctaunutau":(-1,1,10)})# Create data object to write to and rund=ck.DataWithErrors()r=s.run(d)r.write()# Write results back to data objectClusterUsing hierarchical clustering:c=ck.cluster.HierarchyCluster()# Initialize worker classc.set_metric("euclidean")c.set_max_d(0.15)# "Cut off" value for hierarchyr=c.run(d)# Run clustering on dr.write()# Write results to dBenchmark pointsb=ck.Benchmark()# Initialize worker classb.set_metric("euclidean")r=b.run(d)# Select benchmark points based on metricr.write()# Write results back to dPlottingd.plot_clusters_scatter(['CVL_bctaunutau','CSL_bctaunutau','CT_bctaunutau'],clusters=[1,2]# Only plot 2 clusters for better visibility)d.plot_clusters_fill(['CVL_bctaunutau','CSL_bctaunutau'])Plotting all benchmark points:d.plot_dist()Plotting minima and maxima of bin contents for all histograms in a cluster (+benchmark histogram):d.plot_dist_minmax(clusters=[0,2])Similarly with box plots:d.plot_dist_box()License & ContributingThis project is ongoing work andquestions, comments,bug reportsorpull requestsare most welcome. You can also use the chat
room ongitteror contact us viaemail.
We are also working on a paper, so please make sure to cite us once we publish.This software is licenced under theMIT license.