ServiceX DataBinder

版本 v0.5.0

servicex-databinder 是一个使用单个配置文件的用户分析数据管理包。具有外部数据源（例如 RucioDID 或 XRootDFiles）的示例使用ServiceX提供用户选择的列，并可选择行过滤。

以下表格显示了DataBinder支持的ServiceX转换器

先决条件

• 访问ServiceX实例
• Python 3.7+

安装

pip install servicex-databinder

配置文件

配置文件是一个包含所有信息的yaml文件。

以下示例配置文件包含最小字段。您也可以在您的工作目录下载 config_minimum.yaml 文件（重命名为 servicex.yaml），并运行DataBinder for OpenData而不需要访问令牌。

General:
  ServiceXName: servicex-opendata
  OutputFormat: parquet
  
Sample:
  - Name: ggH125_ZZ4lep
    XRootDFiles: "root://eospublic.cern.ch//eos/opendata/atlas/OutreachDatasets\
                  /2020-01-22/4lep/MC/mc_345060.ggH125_ZZ4lep.4lep.root"
    Tree: mini
    Columns: lep_pt, lep_eta

General 块需要两个强制选项（ServiceXName 和 OutputFormat），如示例所示。

每个样本的输入数据集可以由 RucioDID、XRootDFiles 或 LocalPath 定义。

可以使用TCut语法或func-adl构建ServiceX查询。

• TCut语法选项：Filter¹和Columns
• Func-adl表达式的选项：FuncADL

      ¹ Filter仅适用于标量类型的TBranch。

输出格式可以是Apache parquet或ROOT ntuple（对于uproot后端）。仅支持ROOT ntuple格式用于xaod后端。

以下是一些可用的选项

*必填选项

可以通过利用Definition块简化配置文件。您可以在Definition块下定义占位符，这些占位符将替换Sample块中所有匹配的占位符的值。请注意，占位符必须以DEF_开头。

您可以使用不同的ServiceX转换器为每个样本源。默认转换器由servicex.yaml中的type设置，但如果有，General块中的Transformer会覆盖它，并且每个Sample中的Transformer会覆盖任何之前的转换器选择。

以下示例配置显示了如何使用每个选项。

General:
  ServiceXName: servicex-uc-af
  Transformer: uproot
  OutputFormat: root
  OutputDirectory: /Users/kchoi/data_for_MLstudy
  WriteOutputDict: fileset_ml_study
  IgnoreServiceXCache: False
  
Sample:  
  - Name: Signal
    RucioDID: user.kchoi:user.kchoi.signalA,
              user.kchoi:user.kchoi.signalB,
              user.kchoi:user.kchoi.signalC
    Tree: nominal
    FuncADL: DEF_ttH_nominal_query
  - Name: Background1
    XRootDFiles: DEF_ggH_input
    Tree: mini
    Filter: lep_n>2
    Columns: lep_pt, lep_eta
  - Name: Background2
    Transformer: atlasr21
    RucioDID: DEF_Zee_input
    FuncADL: DEF_Zee_query
  - Name: Background3
    LocalPath: /Users/kchoi/Work/data/background3
  - Name: Background4
    Transformer: python
    RucioDID: user.kchoi:user.kchoi.background4
    Function: |
      def run_query(input_filenames=None):
          import awkward as ak, uproot
          tree_name = "nominal"
          o = uproot.lazy({input_filenames:tree_name})
          return {"nominal: o}

Definition:
  DEF_ttH_nominal_query: "Where(lambda e: e.met_met>150e3). \
              Select(lambda event: {'el_pt': event.el_pt, 'jet_e': event.jet_e, \
              'jet_pt': event.jet_pt, 'met_met': event.met_met})"
  DEF_ggH_input: "root://eospublic.cern.ch//eos/opendata/atlas/OutreachDatasets\
                  /2020-01-22/4lep/MC/mc_345060.ggH125_ZZ4lep.4lep.root"
  DEF_Zee_input: "mc15_13TeV:mc15_13TeV.361106.PowhegPythia8EvtGen_AZNLOCTEQ6L1_Zee.\
                merge.DAOD_STDM3.e3601_s2576_s2132_r6630_r6264_p2363_tid05630052_00"
  DEF_Zee_query: "SelectMany('lambda e: e.Jets(\"AntiKt4EMTopoJets\")'). \
              Where('lambda j: (j.pt() / 1000) > 30'). \
              Select('lambda j: j.pt() / 1000.0'). \
              AsROOTTTree('junk.root', 'my_tree', [\"JetPt\"])"

交付数据

from servicex_databinder import DataBinder
sx_db = DataBinder('<CONFIG>.yml')
out = sx_db.deliver()

deliver()函数返回一个包含交付文件的Python嵌套字典。

输入配置也可以以Python字典的形式传入。

OutputDirectory中的交付样本和文件始终与DataBinder配置文件同步。

错误处理

failed_requests = sx_db.get_failed_requests()

如果ServiceX请求失败，deliver()将打印失败请求的数量以及样本名称、如果有，还将打印树名称和输入数据集。您可以通过get_failed_requests()函数获取失败样本的完整列表以及每个错误的消息。如果消息不明确，您可以浏览ServiceX实例网页中的Logs以获取详细信息。

有用的工具

为多个DID创建Rucio容器

当前ServiceX为每个Rucio DID生成一个请求。通常情况下，物理分析需要处理数百个DID。在这种情况下，可以使用脚本（scripts/create_rucio_container.py）从yaml文件中为每个样本创建一个Rucio容器。包含了一个示例yaml文件（scripts/rucio_dids_example.yaml）。

以下是脚本的用法

usage: create_rucio_containers.py [-h] [--dry-run DRY_RUN]
                                  infile container_name version

Create Rucio containers from multiple DIDs

positional arguments:
  infile             yaml file contains Rucio DIDs for each Sample
  container_name     e.g. user.kchoi:user.kchoi.<container-name>.Sample.v1
  version            e.g. user.kchoi:user.kchoi.fcnc_ana.Sample.<version>

optional arguments:
  -h, --help         show this help message and exit
  --dry-run DRY_RUN  Run without creating new Rucio container

致谢

本工作的支持由美国能源部高能物理办公室在项目编号DE-SC0007890下提供