# 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
```bash
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):
```bash
pip install lbconddb
```
You can start editing the charm database in Python. To start with, you can load the
database:
```python
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.
```python
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:
```python
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](#flush).
## 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`:
```python
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:
```python
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:
```python
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.
## <a name="flush"></a>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:
```python
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].
Raw data
{
"_id": null,
"home_page": "https://gitlab.cern.ch/lhcb-charm/correlations-database-editor",
"name": "lbcharmdb",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "LHCb,charm",
"author": "Laurent Dufour",
"author_email": "Laurent Dufour <laurent.dufour@cern.ch>",
"download_url": "https://files.pythonhosted.org/packages/71/6d/4fe70fe3c65e0ebb364bbbfb2d595793a048056e653a797bb72beff023e8/lbcharmdb-0.11.tar.gz",
"platform": null,
"description": "# lbcharmdb editor\n\nThis project contains the Python machinery to modify the LHCb charm correlations database.\n\n## Introduction to nomenclature: full and summary database\nThe database itself consists of two parts: \n - a \"full\" database, with elaborate details per analysis, including internal information\n - a \"summary\", which is *generated* from the full (verbose) database each time you save changes\n\nAll manipulations happen on the verbose database, and the publisher takes care of generating\nthe summary. A version control for the database itself is also used, with the most\nrecent version available at\n https://gitlab.cern.ch/lhcb-charm/correlations-database\n\nCurrently, the database manipulations happen through Python. \nWhen initialising this editor of the database, simply point it to the directory \ncontaining *both* the summary and the full database. \n\n## Structure\nThe database itself contains:\n - Observables\n - Analyses, which can have results on multiple observables\n - Correlations, which are relations between (analysis, observable) pairs\n\nUnder the hood, everything is saved in JSON files to help the debugging and\nportability.\n\n## Working with lbcharmdb: setup\nFirstly, it is required to `git clone` the latest correlation database from \n```bash\ngit clone https://gitlab.cern.ch/lhcb-charm/correlations-database db\n```\nSuch that you can make changes to the latest database, and create a merge request\nfor your changes to be published.\n\nAfter this has been set up, you can use this package either via pip or via\nlb-conda(TODO):\n```bash\npip install lbconddb\n```\n\nYou can start editing the charm database in Python. To start with, you can load the \ndatabase:\n\n```python\nfrom lbcharmdb import Analysis, CharmCorrelationDatabase, DatabaseSummary, units\n\ndatabase = CharmCorrelationDatabase( \"db/\" )\ndatabase.load()\n```\n\nNote that we have loaded the entire result of the git clone, and we don't have to\nworry about setting any specifics. The trailing slash in the directory path \nis optional. After the database has been loaded, it's time to manipulate it, \nfollowing the examples below.\n\n## Adding a new analysis\nPer example, an analysis is added to the database which contains more than\none observable: three CP asymmetries are reported. \n\nThe following opens a database, defines the analysis (\"LHCb-PAPER-2019-002\") and \nadds three of the observables and their results to this analysis.\n\nLastly, it adds the newly defined analysis to the database. \nAfter this step, the changes have **not yet** been written to the database; the \n'flushing' is described further below.\n\n```python\nlhcb_paper_2019_002 = Analysis( identifier=\"LHCb-PAPER-2019-002\",\n dataset = [2015, 2016, 2017],\n preprint=\"arXiv:1903.01150\",\n journal_reference=\"Phys. Rev. Lett.122 (2019) 191803\",\n title=r\"Search for CP violation in $Ds+ \\to KS0\\pi+$, $D+ \\to KS0K+$ and $D+ \\to \\phi \\pi+$ decays\" \n )\n\nacp_phi_pi = database.add_observable_to_analysis_by_name( analysis=lhcb_paper_2019_002,\n observable_name=\"ACP(D+ -> phi pi+)\", \n paper_reference=\"Eq. 6\",\n statistical_uncertainty=0.042*units.percent,\n systematic_uncertainty=0.029*units.percent )\n\nacp_ks_k = database.add_observable_to_analysis_by_name( analysis=lhcb_paper_2019_002,\n observable_name=\"ACP(D+ -> KS K+)\", \n paper_reference=\"Eq. 5\",\n statistical_uncertainty=0.065*units.percent,\n systematic_uncertainty=0.048*units.percent )\n\nacp_ks_pi = database.add_observable_to_analysis_by_name( analysis=lhcb_paper_2019_002,\n observable_name=\"ACP(Ds+ -> KS pi+)\", \n paper_reference=\"Eq. 4\",\n statistical_uncertainty=0.19*units.percent,\n systematic_uncertainty=0.05*units.percent )\n\ndatabase.add_or_update_analysis( lhcb_paper_2019_002 )\n```\n\n## Correlating results from analyses\n\n## Updating an existing analysis\n\nTo update an analysis, you first have to get it from the database, then update the parameters, \nand then make a call to `add_or_update_analysis`. For example:\n\n```python\nfrom lbcharmdb import Analysis, CharmCorrelationDatabase, DatabaseSummary, units\n\ndatabase = CharmCorrelationDatabase( input_directory=\"db\" )\ndatabase.load()\n\nlhcb_paper_2019_002 = database.get_analysis( \"LHCb-PAPER-2019-002\" )\nlhcb_paper_2019_002.title=r\"Search for CP violation in $Ds+ \\to KS0\\pi+$, $D+ \\to KS0K+$ and $D+ \\to \\phi \\pi+$ decays\" \nadd_or_update_analysis( lhcb_paper_2019_002 ) \n```\n\nAfterwards, you need to [persist the changes to the database](#flush). \n\n## List all information and observables for an analysis\n\nIn case you have to work with an analysis, and want to know which\nobservables have been registered, you can use `print`:\n\n```python\n lhcb_paper_2022_024 = database.get_analysis(\"LHCb-PAPER-2022-024\")\n print(lhcb_paper_2022_024)\n```\nwhich provides:\n```\n-------- LHCb-PAPER-2022-024 ----\n| Title: Measurement of the time-integrated $CP$ asymmetry in $D^0 \\to K^- K^+$ decays\n| ana: LHCb-ANA-2022-005\n| dataset: 2015, 2016, 2017, 2018\n| url: https://lhcbproject.web.cern.ch/Publications/p/LHCb-PAPER-2022-024.html\n| preprint: arXiv:2209.03179\n| journal_reference: None\n| tuple_path: None\n| observables\n| > [3] 'ACP(D0 -> K- K+)' (paper_reference 'Eq. 1')\n| Uncertainties\n| > [ACP(D0 -> K- K+)] 0.00054 Stat.\n| > [ACP(D0 -> K- K+)] 0.00016 Syst.\n| Specified Uncertainties: statistical\n| > [ACP(D0 -> K- K+)] 0.00054 Stat ('total')\n| Specified Uncertainties: systematic\n| > [ACP(D0 -> K- K+)] 0.00016 Syst ('total')\n| obsolete_observables\n| > None\n-------------------\n```\n\n## Add, or update, a correlation between measurements\n\nIt is possible to add correlations to the database between different observables of the same, \nor different analyses. It is possible to correlate the statistical uncertainty of one to that of the\nother, but also to correlate the systematic uncretainty of one to the systematic of the other. \n\nIn its most basic form, an example of adding a correlation looks as follows:\n```python\nlhcb_paper_2022_024 = database.get_analysis(\"LHCb-PAPER-2022-024\")\nlhcb_paper_2019_002 = database.get_analysis(\"LHCb-PAPER-2019-002\")\nacp_kk = database.get_observable_by_name(\"ACP(D0 -> K- K+)\")\nacp_phi_pi = database.get_observable_by_name(\"ACP(D+ -> phi pi+)\")\n\ndatabase.make_and_register_correlation( \n analysis_A=lhcb_paper_2022_024, observable_A=acp_kk,\n analysis_B=lhcb_paper_2019_002, observable_B=acp_phi_pi,\n correlation_coefficient=0.13 )\n```\n\nIn the code above, the total *statistical* uncertainties between these two are correlated with \na coefficient 0.13. In case you wanted to add a correlation between *systematic* uncertainties,\nit would look as follows:\n\n```python\n\ndatabase.make_and_register_correlation( \n analysis_A=lhcb_paper_2022_024, observable_A=acp_kk,\n analysis_B=lhcb_paper_2019_002, observable_B=acp_phi_pi,\n is_statistical_uncertainty_A=False, is_statistical_uncertainty_B=False,\n correlation_coefficient=0.13 )\n```\n\nIf you wish to update the correlation coefficient, you can simply call the same function\nwith the updated coefficient. There will be a message in your console warning you \nthat you are updating a pre-existing correlation\n> CharmCorrelationDb[54728] INFO Overwriting pre-existing correlation.\n\nTo remove a correlation, one simply sets the correlation coefficient\nto 0.\n\n## <a name=\"flush\"></a>Finalising the database and create a summary database\nThe database that is in memory locally can be written back into JSON format by the `flush()` command.\nIn addition to the full database, a summary needs to be created which is used for the front-end. \nThis can be done in one go as follows:\n\n```python\n database.flush( write_summary_to=\"db/summary\" ) # this writes the \"full\" database *and* the summary\n```\n\nIn case you explicitly only want to write out the database, and not create a summary, you can omit\nthe `write_summary_to` keyword altogether.\n\n## Helpers: Calculating the correlation coefficient between two \n## KPi asymmetries\n\nA regular correction made is that for the detection asymmetry of K- pi+ pairs,\ncalculated using either a couple of Ds+ or D+ decays. \n\nTo help with the calculation of correlation coefficients, a set of scripts\nare made available to calculate the *statistical* correlations. Please follow the instructions\nat (here)[this_link].\n",
"bugtrack_url": null,
"license": "",
"summary": "Maintenance tools for the database of correlations between charm analyses",
"version": "0.11",
"project_urls": {
"Bug Reports": "https://gitlab.cern.ch/lhcb-charm/correlations-database-editor/issues",
"Homepage": "https://gitlab.cern.ch/lhcb-charm/correlations-database-editor",
"Source": "https://gitlab.cern.ch/lhcb-charm/correlations-database-editor"
},
"split_keywords": [
"lhcb",
"charm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2704c046c56ac4fef1f20178dc2ae3725b3ae4300dcc3d60f5a6ec20667bb43a",
"md5": "45809e1c1b7ea5dff297e1e2380209d9",
"sha256": "4a8923f551f277ed69e82a9f7dfefc25db066bfa2dbbf094613e7adb8ad37a2f"
},
"downloads": -1,
"filename": "lbcharmdb-0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "45809e1c1b7ea5dff297e1e2380209d9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 32416,
"upload_time": "2023-11-27T14:53:48",
"upload_time_iso_8601": "2023-11-27T14:53:48.463588Z",
"url": "https://files.pythonhosted.org/packages/27/04/c046c56ac4fef1f20178dc2ae3725b3ae4300dcc3d60f5a6ec20667bb43a/lbcharmdb-0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "716d4fe70fe3c65e0ebb364bbbfb2d595793a048056e653a797bb72beff023e8",
"md5": "f6d146835c5a0e4b3af8982f7e87e381",
"sha256": "99b330c91dded3b6eb21fbcba1fa49ad419c1158665a2e9f77daebe56418c1ff"
},
"downloads": -1,
"filename": "lbcharmdb-0.11.tar.gz",
"has_sig": false,
"md5_digest": "f6d146835c5a0e4b3af8982f7e87e381",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 32831,
"upload_time": "2023-11-27T14:53:50",
"upload_time_iso_8601": "2023-11-27T14:53:50.351813Z",
"url": "https://files.pythonhosted.org/packages/71/6d/4fe70fe3c65e0ebb364bbbfb2d595793a048056e653a797bb72beff023e8/lbcharmdb-0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-27 14:53:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "lbcharmdb"
}
JSON