lbcharmdb editor

This project contains the Python machinery to modify the LHCb charm correlations database.

Introduction to nomenclature: full and summary database

The database itself consists of two parts:

• a "full" database, with elaborate details per analysis, including internal information
• a "summary", which is generated from the full (verbose) database each time you save changes

All manipulations happen on the verbose database, and the publisher takes care of generating the summary. A version control for the database itself is also used, with the most recent version available at https://gitlab.cern.ch/lhcb-charm/correlations-database

Currently, the database manipulations happen through Python. When initialising this editor of the database, simply point it to the directory containing both the summary and the full database.

Structure

The database itself contains:

• Observables
• Analyses, which can have results on multiple observables
• Correlations, which are relations between (analysis, observable) pairs

Under the hood, everything is saved in JSON files to help the debugging and portability.

Working with lbcharmdb: setup

Firstly, it is required to git clone the latest correlation database from

git clone https://gitlab.cern.ch/lhcb-charm/correlations-database db

Such that you can make changes to the latest database, and create a merge request for your changes to be published.

After this has been set up, you can use this package either via pip or via lb-conda(TODO):

pip install lbconddb

You can start editing the charm database in Python. To start with, you can load the database:

from lbcharmdb import Analysis, CharmCorrelationDatabase, DatabaseSummary, units

database = CharmCorrelationDatabase( "db/" )
database.load()

Note that we have loaded the entire result of the git clone, and we don't have to worry about setting any specifics. The trailing slash in the directory path is optional. After the database has been loaded, it's time to manipulate it, following the examples below.

Adding a new analysis

Per example, an analysis is added to the database which contains more than one observable: three CP asymmetries are reported.

The following opens a database, defines the analysis ("LHCb-PAPER-2019-002") and adds three of the observables and their results to this analysis.

Lastly, it adds the newly defined analysis to the database. After this step, the changes have not yet been written to the database; the 'flushing' is described further below.

lhcb_paper_2019_002 = Analysis( identifier="LHCb-PAPER-2019-002",
    dataset = [2015, 2016, 2017],
    preprint="arXiv:1903.01150",
    journal_reference="Phys. Rev. Lett.122 (2019) 191803",
    title=r"Search for CP violation in $Ds+ \to KS0\pi+$, $D+ \to KS0K+$ and $D+ \to \phi \pi+$ decays" 
    )

acp_phi_pi = database.add_observable_to_analysis_by_name( analysis=lhcb_paper_2019_002,
            observable_name="ACP(D+ -> phi pi+)", 
            paper_reference="Eq. 6",
            statistical_uncertainty=0.042*units.percent,
            systematic_uncertainty=0.029*units.percent )

acp_ks_k = database.add_observable_to_analysis_by_name( analysis=lhcb_paper_2019_002,
            observable_name="ACP(D+ -> KS K+)", 
            paper_reference="Eq. 5",
            statistical_uncertainty=0.065*units.percent,
            systematic_uncertainty=0.048*units.percent )

acp_ks_pi = database.add_observable_to_analysis_by_name( analysis=lhcb_paper_2019_002,
            observable_name="ACP(Ds+ -> KS pi+)", 
            paper_reference="Eq. 4",
            statistical_uncertainty=0.19*units.percent,
            systematic_uncertainty=0.05*units.percent )

database.add_or_update_analysis( lhcb_paper_2019_002 )

Correlating results from analyses

Updating an existing analysis

To update an analysis, you first have to get it from the database, then update the parameters, and then make a call to add_or_update_analysis. For example:

from lbcharmdb import Analysis, CharmCorrelationDatabase, DatabaseSummary, units

database = CharmCorrelationDatabase( input_directory="db" )
database.load()

lhcb_paper_2019_002 = database.get_analysis( "LHCb-PAPER-2019-002" )
lhcb_paper_2019_002.title=r"Search for CP violation in $Ds+ \to KS0\pi+$, $D+ \to KS0K+$ and $D+ \to \phi \pi+$ decays" 
add_or_update_analysis( lhcb_paper_2019_002 ) 

Afterwards, you need to persist the changes to the database.

List all information and observables for an analysis

In case you have to work with an analysis, and want to know which observables have been registered, you can use print:

    lhcb_paper_2022_024 = database.get_analysis("LHCb-PAPER-2022-024")
    print(lhcb_paper_2022_024)

which provides:

-------- LHCb-PAPER-2022-024 ----
| Title: Measurement of the time-integrated $CP$ asymmetry in $D^0 \to K^- K^+$ decays
| ana: LHCb-ANA-2022-005
| dataset: 2015, 2016, 2017, 2018
| url: https://lhcbproject.web.cern.ch/Publications/p/LHCb-PAPER-2022-024.html
| preprint: arXiv:2209.03179
| journal_reference: None
| tuple_path: None
| observables
|   > [3] 'ACP(D0 -> K- K+)' (paper_reference 'Eq. 1')
| Uncertainties
|   > [ACP(D0 -> K- K+)] 0.00054 Stat.
|   > [ACP(D0 -> K- K+)] 0.00016 Syst.
| Specified Uncertainties: statistical
|   > [ACP(D0 -> K- K+)] 0.00054 Stat ('total')
| Specified Uncertainties: systematic
|   > [ACP(D0 -> K- K+)] 0.00016 Syst ('total')
| obsolete_observables
|   > None
-------------------

Add, or update, a correlation between measurements

It is possible to add correlations to the database between different observables of the same, or different analyses. It is possible to correlate the statistical uncertainty of one to that of the other, but also to correlate the systematic uncretainty of one to the systematic of the other.

In its most basic form, an example of adding a correlation looks as follows:

lhcb_paper_2022_024 = database.get_analysis("LHCb-PAPER-2022-024")
lhcb_paper_2019_002 = database.get_analysis("LHCb-PAPER-2019-002")
acp_kk = database.get_observable_by_name("ACP(D0 -> K- K+)")
acp_phi_pi = database.get_observable_by_name("ACP(D+ -> phi pi+)")

database.make_and_register_correlation( 
                    analysis_A=lhcb_paper_2022_024, observable_A=acp_kk,
                    analysis_B=lhcb_paper_2019_002, observable_B=acp_phi_pi,
                    correlation_coefficient=0.13 )

In the code above, the total statistical uncertainties between these two are correlated with a coefficient 0.13. In case you wanted to add a correlation between systematic uncertainties, it would look as follows:

database.make_and_register_correlation( 
                    analysis_A=lhcb_paper_2022_024, observable_A=acp_kk,
                    analysis_B=lhcb_paper_2019_002, observable_B=acp_phi_pi,
                    is_statistical_uncertainty_A=False, is_statistical_uncertainty_B=False,
                    correlation_coefficient=0.13 )

If you wish to update the correlation coefficient, you can simply call the same function with the updated coefficient. There will be a message in your console warning you that you are updating a pre-existing correlation

CharmCorrelationDb[54728] INFO Overwriting pre-existing correlation.

To remove a correlation, one simply sets the correlation coefficient to 0.

Finalising the database and create a summary database

The database that is in memory locally can be written back into JSON format by the flush() command. In addition to the full database, a summary needs to be created which is used for the front-end. This can be done in one go as follows:

    database.flush( write_summary_to="db/summary" ) #  this writes the "full" database *and* the summary

In case you explicitly only want to write out the database, and not create a summary, you can omit the write_summary_to keyword altogether.

Helpers: Calculating the correlation coefficient between two

KPi asymmetries

A regular correction made is that for the detection asymmetry of K- pi+ pairs, calculated using either a couple of Ds+ or D+ decays.

To help with the calculation of correlation coefficients, a set of scripts are made available to calculate the statistical correlations. Please follow the instructions at (here)[this_link].