PIDCalib2

一套用于估计LHCb PID效率的软件工具。

该软件包包括几个用户可调用的模块

• make_eff_hists 创建可用于估计用户样本PID效率的直方图
• ref_calib 计算用户参考样本的LHCb PID效率
• merge_trees 合并具有兼容 TTree 的两个ROOT文件
• plot_calib_distributions 允许您绘制校准数据集中变量的分布
• pklhisto2root 将Pickled boost-histogram 转换为ROOT直方图

术语“参考数据集/样本”指的是用户想要分配PID效率的用户的数据库。 “校准数据集/样本”是PIDCalib内部用于PID效率估计的特殊、集中管理的样本。 --sample 参数始终涉及这些校准样本。

带有附加信息、示例输出和图表的幻灯片可在Indico上找到。

设置

在可以访问LHCb软件栈的计算机上（LXPLUS、大学集群等）工作，可以通过运行以下命令来设置PIDCalib2：

lb-conda pidcalib bash

之后，以下命令将可用

pidcalib2.make_eff_hists
pidcalib2.ref_calib
pidcalib2.merge_trees
pidcalib2.plot_calib_distributions
pidcalib2.pklhisto2root

您可以直接跳过bash调用，将设置和运行阶段合并为单个命令

lb-conda pidcalib pidcalib2.make_eff_hists

要运行make_eff_hists，您需要访问CERN EOS。在LXPLUS上不需要做任何特别的事情。在其他机器上，您通常需要通过运行以下命令获取Kerberos票据：

kinit [username]@CERN.CH

从PyPI安装

PIDCalib2软件包可在PyPI上找到。它可以通过在任意计算机上运行pip来安装（最好在虚拟环境中进行；请参阅venv）

pip install pidcalib2

请注意，这将安装xrootd的Python绑定。还需要安装XRootD本身，以便绑定能够工作。有关XRootD版本和说明，请参阅此页面。

make_eff_hists

此模块创建可以用来估计用户样本的PID效率的直方图。

读取所有相关校准文件可能需要很长时间。当第一次运行配置时，我们建议使用--max-files 1选项。这将限制PIDCalib2只读取单个校准文件。这种测试可以快速揭示例如缺失变量等问题。请注意，当您正在读取校准数据的小子集时，可能会收到有关总直方图中有空bin的警告。对于快速测试的目的，可以安全地忽略此警告。

选项

要获取一个列出所有选项、它们的描述和默认值的用法消息，请键入：

pidcalib2.make_eff_hists --help

要处理的校准文件由sample、magnet和particle选项确定。所有有效的组合都可以通过运行以下命令列出：

pidcalib2.make_eff_hists --list configs

为标准变量定义了别名，以简化命令。我们建议用户在指定变量时使用别名。当您使用不是别名的名称时，日志中会显示如下警告消息：

'probe_PIDK' is not a known PID variable alias, using raw variable

可以通过运行以下命令列出所有别名：

pidcalib2.make_eff_hists --list aliases

请注意，别名的数量比变量多得多。如果您想找到没有别名的变量，可以自己检查校准文件之一。当指定了--verbose选项时，会打印校准文件的路径。或者，您可以简单地猜测名称 - 如果它不存在，PIDCalib2会通知您，并可能提供一个存在的相似名称列表。

可以使用--binning-file指定具有替代分箱的文件。该文件必须包含有效的JSON，指定分箱边缘。例如，对于粒子Pi、变量P和PT的两个分箱分箱可以定义如下：

{"Pi": {"P": [10000, 15000, 30000], "PT": [6000, 10000, 20000]}}

可以在单个文件中定义任意数量的分箱。

可以通过使用&（逻辑与）和|（逻辑或）将简单的表达式链接起来创建复杂的选择表达式。还可以使用标准的数学符号，如*、/、+、-、(、)。空白字符不重要。

示例

• 为单个PID切分创建单个3D效率直方图

  pidcalib2.make_eff_hists --sample Turbo18 --magnet up --particle Pi --pid-cut "DLLK > 4" --bin-var P --bin-var ETA --bin-var nSPDhits --output-dir pidcalib_output
  

• 在单个运行中创建多个直方图（大部分时间都花费在读取数据上，因此指定多个切分比顺序运行make_eff_hists快得多）

  pidcalib2.make_eff_hists --sample Turbo16 --magnet up --particle Pi --pid-cut "DLLK > 0" --pid-cut "DLLK > 4" --pid-cut "DLLK > 6" --bin-var P --bin-var ETA --bin-var nSPDhits --output-dir pidcalib_output
  

• 仅使用带负电的轨迹创建复杂切分的单个效率直方图

  pidcalib2.make_eff_hists --sample Turbo18 --magnet up --particle Pi --pid-cut "MC15TuneV1_ProbNNp*(1-MC15TuneV1_ProbNNpi)*(1-MC15TuneV1_ProbNNk) < 0.5 & DLLK < 3" --cut "IsMuon==0 & Brunel_PT>250 & trackcharge==-1" --bin-var P --bin-var ETA --bin-var nSPDhits --output-dir pidcalib_output
  

注意事项

并非所有数据集都包含所有变量，在某些情况下，相同的变量有不同的名称（例如，在特定的电子样本中，probe_Brunel_IPCHI2 被命名为 probe_Brunel_MINIPCHI2）。别名对应于最常见的名称，但如果你在 PIDCalib2 中找不到所需的变量，你可能需要检查校准文件。

ref_calib

此模块使用由 make_eff_hists 创建的直方图来为用户提供参考样本中的事件分配效率。将效率添加到用户提供的文件需要 PyROOT，这是可选的。

模块分为两个步骤

1. 计算效率并将其保存为单独文件中的 TTree。
2. 可选地将效率 TTree 复制到参考文件中，并将其作为用户 TTree 的朋友。用户必须在命令行上指定 --merge 来请求此步骤。

请注意，--merge 将修改您的文件。请谨慎使用。

选项

sample 和 magnet 选项仅用于选择正确的 PID 效率直方图。因此，它们应该与运行 make_eff_hists 时使用的选项相匹配。

bin-vars 必须是一个字典，将用于创建效率直方图的分箱变量（或别名）与参考样本中的变量相关联。我们假设参考样本分支名称的格式为 [ParticleName]_[VariableName]。例如，D0_K_calcETA 对应于名为 D0_K 的粒子以及变量 calcETA。如果用户希望使用 1D 分箱来估计样本的 PID 效率，其中 calcETA 对应于校准样本的 ETA 分箱变量别名，他们应指定 --bin-vars '{"ETA": "calcETA"}'。

ref-file 是用户想要分配 PID 效率的参考文件。该参数可以是本地文件或远程文件，例如在 EOS 上（--ref-file root://eoslhcb.cern.ch//eos/lhcb/user/a/anonymous/tuple.root）。

ref-pars 必须是从参考样本中应用切割的粒子的字典。键代表粒子分支名称前缀（在之前的示例中为 D0_K），传递的值是一个包含粒子类型和 PID 切割的列表，例如 '{"D0_K" : ["K", "DLLK > 4"], "D0_Pi" : ["Pi", "DLLK < 4"]}'。

--merge 选项将复制 PID 效率树到您的输入文件，并将 PID 效率树作为您的输入树的“朋友”。然后您可以像处理具有 PID 效率分支的输入树一样处理输入树。例如，input_tree->Draw("PIDCalibEff") 应该可以工作。ROOT 的“朋友”机制是将一个树的分支添加到另一个树的高效方法。如果您想了解更多信息，请参阅 这里。

示例

• 评估单个 PID 切割的效率并将其保存到 user_ntuple_PID_eff.root 而不将其添加到 user_ntuple.root

  pidcalib2.ref_calib --sample Turbo18 --magnet up --ref-file data/user_ntuple.root --histo-dir pidcalib_output --bin-vars '{"P": "mom", "ETA": "Eta", "nSPDHits": "nSPDhits"}' --ref-pars '{"Bach": ["K", "DLLK > 4"]}' --output-file user_ntuple_PID_eff.root
  

• 评估单个 PID 切割的效率并将其添加到参考文件 user_ntuple.root

  pidcalib2.ref_calib --sample Turbo18 --magnet up --ref-file data/user_ntuple.root --histo-dir pidcalib_output --bin-vars '{"P": "mom", "ETA": "Eta", "nSPDHits": "nSPDhits"}' --ref-pars '{"Bach": ["K", "DLLK > 4"]}' --output-file user_ntuple_PID_eff.root --merge
  

• 评估多个 PID 切割的效率并将它们添加到参考文件

  pidcalib2.ref_calib --sample Turbo18 --magnet up --ref-file data/user_ntuple.root --histo-dir pidcalib_output --bin-vars '{"P": "P", "ETA": "ETA", "nSPDHits": "nSPDHits"}' --ref-pars '{"Bach": ["K", "DLLK > 4"], "SPi": ["Pi", "DLLK < 0"]}' --output-file user_ntuple_PID_eff.root --merge
  

注意事项

您可能会注意到，您的参考样本中的某些事件被分配了 PIDCalibEff、PIDCalibErr 或两者均为 -999。

• PIDCalibEff 为 -999 当至少有一个轨道时
  • 事件超出分箱范围
  • 效率直方图中相关分箱没有任何事件
  • 效率为负
• PIDCalibErr 为 -999 当至少有一个轨道时
  • 事件超出分箱范围
  • 效率直方图中相关分箱没有任何事件
  • 效率直方图中相关分箱没有通过 PID 切割的事件
  • 效率为负

由于原始 PIDCalib 中的 double 到 float 转换，效率和/或不确定性的微小差异（<1e−3 相对差异）是可以预期的。

原始PIDCalib中的一个错误导致电子校准数据集被读取了两次，从而产生了不正确的效率图不确定性。

原始PIDCalib没有对Omega样本（K_Omega和K_DD）应用正确的切割，导致效率图无意义。

plot_calib_distributions

此工具允许您绘制校准数据集中变量的分布。您可以提供与用于make_eff_hists相同的切割和自定义分箱。如果您想绘制没有分箱的变量，将使用50个分箱的均匀分箱。您可以使用--bins更改分箱数，即使定义了其他分箱也可以通过--force-uniform强制使用均匀分箱。

将为每个请求的变量在--output-dir目录中创建一个图表。图表的格式可以通过--format来控制。此外，如果用户想手动制作图表，将在同一目录中保存plot_calib_distributions.pkl，其中包含所有直方图。

示例

• 使用1个校准文件创建DLLK和P变量的图表

  pidcalib2.plot_calib_distributions --sample Turbo18 --magnet up --particle Pi --bin-var DLLK --bin-var P --output-dir pidcalib_output --max-files 1
  

• 创建具有95个均匀分箱的P变量的PDF图表

  pidcalib2.plot_calib_distributions --sample Turbo18 --magnet up --particle Pi --bin-var P --output-dir pidcalib_output --max-files 1 --format pdf --force-uniform --bins 95
  

• 使用自定义分箱创建P变量的图表

  pidcalib2.plot_calib_distributions --sample Turbo18 --magnet up --particle Pi --bin-var P --output-dir pidcalib_output --max-files 1 --format png --binning-file my_binning.json
  

pklhisto2root

此工具将pickled PIDCalib2直方图转换为TH*D，并保存到ROOT文件中。它可以用于由make_eff_hists或plot_calib_distributions产生的直方图。请注意，ROOT仅支持1维、2维和3维直方图；尝试转换更高维度的直方图将失败。

示例

• 将make_eff_hists中的pickled boost_histograms转换为ROOT

  pidcalib2.pklhisto2root "pidcalib_output/effhists-Turbo18-up-Pi-DLLK>4-P.ETA.nSPDhits.pkl"
  

  这将转换直方图并将它们保存到pidcalib_output/effhists-Turbo18-up-Pi-DLLK>4-P.ETA.nSPDhits.root。

开发

使用lb-conda

在提供了lb-conda的机器上，您可以使用PIDCalib2开发环境中的pidcalib。这主要用于小型修改，并且如果不需要添加任何新依赖项。

1. 从GitLab克隆存储库
2. 进入PIDCalib2目录

   cd pidcalib2
   

3. 在pidcalib环境中启动一个新的BASH shell

lb-conda pidcalib bash

3. 运行您的本地 PIDCalib2代码

cd src
python -m pidcalib2.make_eff_hists -h

不使用lb-conda

这是一个更灵活（但更复杂）的方法。它使您能够完全控制开发环境，并能够使用IDE等。

1. 从GitLab克隆存储库
2. 进入PIDCalib2目录

   cd pidcalib2
   

3. （可选）设置虚拟环境

   python3 -m venv .venv
   source .venv/bin/activate
   

4. 安装固定依赖项

   pip install -r requirements-dev.txt
   

5. 安装xrootd（可能需要手动安装；参见这个问题）
6. 运行测试

   pytest
   

7. 运行模块

   cd src
   python3 -m pidcalib2.make_eff_hists -h
   

提示

可以使用这样的标记排除某些测试

pytest -m "not xrootd"

运行pytest --markers查看可用的标记（列表将首先显示PIDCalib2自定义标记，然后显示pytest内置标记）。

链接

• PIDGen2 - 一种基于数据校准样本分布重新采样MC PID变量的工具