========================================= 【作成中】空蟬ヒストグラム化の概観 ========================================= :著者: 稲村泰弘 概要 ==== ここでは空蟬環境におけるヒストグラム処理の構造や処理に必要な情報を簡単に示す。本稿で示す情報は、単に空蟬を使用するだけのユーザーならあまり必要ではないかもしれないが、装置責任者クラスには知っておいていただきたい。将来自分で解析スクリプトを書いたり、自分専用の環境を作成したりする際に役に立つであろう。 空蟬環境におけるヒストグラム化の基本関数である *UtsusemiGetNeunetHistogram* は、まさに本稿で示された情報が集約されているものである。 ヒストグラム化に必要な情報 =========================== 空蟬のヒストグラム化の開発では、基礎的関数は共通化し、多様な装置に対応させることを大きな目的としている。開発者視点では少ないリソースで高度化も容易であるし、ユーザー視点でも、複数の装置にわたるデータに対し、様々な単位変換を行うヒストグラム化処理（データリダクション）に対し、「同じ関数を情報（パラメーター）ファイルを変更するだけ」で対応できるというメリットがある。また、扱う情報ファイルも最小限にまとめてしまうことを基本路線としている。 では、ヒストグラム化に必要な情報は何であろうか。 まずハードウェア・システムの面から見る。MLFのデータ収集システム（検出器＋DAQミドルウェア）では、検出器が捉えたシグナルはハードウェア的にイベント化され、何本かまとめられた単位（モジュール）ごとにDAQミドルウェアによってファイルに書き込まれる。一方でデータリダクションや解析に最も必要となる情報は「どこでどんな中性子が検出されたか」であるから、収集された中性子散乱のデータがどの検出位置を持つかを区別する必要がある。そのために、それぞれの検出位置（pixel）ごとに固有のIDをつけている。また、ヒストグラム化処理自体ついての情報も重要で、例えばどのようなヒストグラムに変換したいのか、という情報を与える必要がある。 以上述べてきたことから、ヒストグラム化に求められる情報をざっくりとまとめてみる。 まずハードウェア・システム情報として、 1. DAQの生み出すイベントデータとヒストグラムを結びつける情報（どのファイルのどのイベントがどのpixelのデータなのか） 2. 検出器などの位置情報（どのPixelがどこの場所を意味しているのか） の二つの情報が重要となる。これらは、それぞれのビームラインのハードウェアに依存するものであるが、それほど頻繁に変更がない情報でもある。 他方、データリダクション情報としては、 3. ヒストグラム化情報（横軸、範囲、単位変換パラメーターなど） 4. Time Focusing情報 などの、データ処理ごとに変更が必要な情報が求められる。 以上述べたように、必要な情報は非常に多岐にわたるため、実際には個別に与えるのではなく、少数のパラメーターファイルに書き込み、そのファイルを基礎的関数に引数として与えることでヒストグラム化を実現することとした。 ただ、データ処理ごとに一からパラメーターファイルを作成するのはコストがかかるし、ハードウェア情報をどこかに持つ必要があるのは変わらないので、 1. 装置ごとにパラメーターファイルの「雛形」を用意して 2. それを最小限書き換えて一時ファイルとして保存 3. それを基礎的関数に引数として渡す という形にした。特にハードウェア・システム情報は変更が少ないので、この形式が有効だと考える。 情報のパラメーター化 ====================== 前節で述べた情報は、大まかに 1. ヒストグラムを作成するのに使用する情報 2. 検出器配置など装置内の位置情報に関わる情報 の二つ分けて定義し、それぞれ 1. WiringInfo 2. DetectorInfo と名付けている。以下にそれぞれの情報の主な役割を示す。 +------------------------------------------------------+--------+ | 空蟬に必要なパラメータファイル |記述言語| +=============+========================================+========+ |Wiring Info |イベントとPixelIdの関連付け、 |XML | | |ヒストグラム化に必要な情報（横軸定義） | | +-------------+----------------------------------------+--------+ |Detector Info|検出器の位置情報、装置関連の情報 |XML | | |（線源-試料間距離L1、Time Focusing情報、| | | |バンク情報など） | | +-------------+----------------------------------------+--------+ ----------------------------------- DAQとヒストグラムを結ぶ：WiringInfo ----------------------------------- WiringInfoは、ヒストグラム化に先立ち、扱うイベントデータに応じて準備する必要がある。 なお、Wiring Infoで使用される主要な情報は以下のようなものである。 +-----------------------------------------------------------------------+ | Wiring Info内ので扱われる情報 | +=================+=====================================================+ |daqId | データ収集システムのPCのID | +-----------------+-----------------------------------------------------+ |moduleNo | データ収集システムのPC内におけるモジュール識別用番号| +-----------------+-----------------------------------------------------+ |detId | 検出器のID | +-----------------+-----------------------------------------------------+ |pixelId | 検出位置のID | +-----------------+-----------------------------------------------------+ |tofBinInfo | ヒストグラムの横軸変換のパターン指定 | +-----------------+-----------------------------------------------------+ |tofBinPatternList| ヒストグラムの横軸変換のパターン記述 | +-----------------+-----------------------------------------------------+ ここで、"ID"は装置（ビームライン）内で固有の番号を示し、"No"は固有ではない番号を表している。 DaqId〜PixelIdは、装置自体が大きくアップグレードしないと変更しない部分である。tofBinInfoやtofBinPatternListなどは、解析ごとに変更がある部分である。 また扱う検出器により、必要なパラメータも異なる（psdParamsなど）ことにも留意する必要がある。 詳細なフォーマットや編集方法（編集する関数など）は、別項を参照のこと（　　）。 ------------------------------------- 検出器の位置、構成情報：DetectorInfo ------------------------------------- DetectorInfoは、WiringInfo同様、ヒストグラム化に先立ち、扱うイベントデータに応じて準備する必要がある。 なお、DetectorInfoで使用される主要な情報は以下のようなものである。 +-----------------------------------------------------------------------+ | DetectorInfo内で扱われる情報 | +=======================+===============================================+ |L1 | 線源と試料の間の距離[mm] | +-----------------------+-----------------------------------------------+ |Time Focusing Parameter| 検出器間の距離による違いを補正する値 | +-----------------------+-----------------------------------------------+ |positionInfo | 検出器の位置情報 | +-----------------------+-----------------------------------------------+ |bankInfo | 検出器のグループ化 | +-----------------------+-----------------------------------------------+ このファイルにおいては、装置自体が大きくアップグレードしないと変更されない情報が大部分である。 詳細なフォーマットや編集方法（編集する関数など）は、別項を参照のこと（　　）。 イベントデータファイルの格納場所 =================================== イベントデータファイルの格納場所は、あるビームラインXXXのデータはすべて、フォルダXXXの下におくことを求められる。このデータフォルダを配置する場所はMLFのデフォルトでは :: /data や :: /opt/mlfsoft/data である。このような形で複数のビームラインのデータを共存させている。 後述するヒストグラム化の関数に必要なデータの場所の指定には、XXXの一つ上の階層を示せば良い（"/data"や"/opt/mlfsoft/data"など）。 これらの場所は、環境変数 *UTSUSEMI_DATA_DIR* で指定される。 ヒストグラム化基礎関数 ========================= 空蟬のヒストグラム化の基礎関数としてあげられるものは、*UtsusemiEventDataConverter* の名をもつクラス群である。これらは、前述のWiringInfoとDetectorInfo、そして幾つかの環境変数とRun Number、そしてデータファイルのルートディレクトリを与えることで、イベントデータから適切なヒストグラムを作成するものである。 取り扱うイベントデータの種類によって異なるが、クラスは以下のようなものである。 +----------------------------------+--------------------------------+--------------------------------+ |クラス名 |対象となる検出器 |対象検出器のイベント生成ボード | +==================================+================================+================================+ |UtsusemiEventDataConverterNeunet |位置敏感型検出器(PSD) |NEUNET | | |(Position Sensitive Detector) | | +----------------------------------+--------------------------------+--------------------------------+ |EmakiEventDataConverterReadout1d |１次元シンチレーションカウンター|Readout (+ReadoutGate) | +----------------------------------+--------------------------------+--------------------------------+ |UtsusemiEventDataConverterWLSF32 |２次元シンチレーションカウンター| | | |（Wave Length Shifting Wire） |Readout(32bit) (+ReadoutGate) | +----------------------------------+--------------------------------+--------------------------------+ |UtsusemiEventDataConverterRPMT |２次元検出器RPMT | | | | |Readout(64bit) (+ReadoutGate) | +----------------------------------+--------------------------------+--------------------------------+ |UtsusemiEventDataConverterMWPC |２次元検出器MWPC | | | |(Multiwire Proportional Chamber)|Readout(64bit) (+ReadoutGate) | +----------------------------------+--------------------------------+--------------------------------+ |UtsusemiEventDataConverterTemplate|ヒストグラム化の根幹関数。これをテンプレートとして他の関数が作成 | | |されている。主にイベントデータを読み込みヒストグラム化する部分を | | |担う。この関数を直接呼び出すことはない。 | +----------------------------------+-----------------------------------------------------------------+ ここでは簡単に使い方を紹介するにとどめる。詳細はリファレンスを参照のこと。 ---------------- 具体的な使用例 ---------------- ここでヒストグラム化の具体的な使用例を示す。今回の例では - 空蟬のインストールおよび設定がなされていること - 位置敏感型検出器, Position Sensitive Detector (PSD)からのデータのヒストグラム化であること を前提としている。また今回のヒストグラム化に使用する関数（クラス）は、 :: "Manyo.Utsusemi.UtsusemiEventDataConverterNeunet" である。 スクリプト例 ---------------- .. code-block:: python import Manyo as mm import Manyo.Utsusemi as mu event_conv = mu.UtsusemiEventDataConverterNeunet() evtnt_conv.SetParameterFiles( "path/to/WiringInfo.xml", "path/to/DetectorInfo.xml" ) event_conv.SetHistAllocation() event_conv.LoadEventDataFiles( 123, "path/to/data" ) DAT = mm.ElementContainerMatrix() event_conv.SetElementContainerMatrix( DAT ) スクリプトの解説 ---------------- .. code-block:: python import Manyo as mm import Manyo.Utsusemi as mu ここではまず、Manyoライブラリ（空蟬）を呼び出すためのおまじないを行う。 .. code-block:: python event_conv = mu.UtsusemiEventDataConverterNeunet() 次にUtsusemiEventDataConverterNeunetの関数を使うための準備（インスタンス作成）を行う。 .. code-block:: python evtnt_conv.SetParameterFiles( "path/to/WiringInfo.xml", "path/to/DetectorInfo.xml" ) event_conv.SetHistAllocation() ヒストグラム化に必要な二つのパラメータファイル、WiringInfo.xml、DetectorInfo.xml（あらかじめ準備しておく）のファイル名を引数で与える。またそのファイルで指定されたようにイベントデータを読み込みヒストグラム化する準備を行う。 .. code-block:: python event_conv.LoadEventDataFiles( 123, "path/to/data" ) イベントデータを読み込み、ヒストグラム化する。引数としてRun Numberとデータの場所を与える。ここでデータの場所("path/to/data")は前節で述べたように"/data"もしくは"/opt/mlfsoft/data"といった部分で、それ以下の装置コード（"SIK"とか"HPN"）の部分はWiringInfoに記述されているコードが自動的に用いられる。逆に言えばWiringInfoだけの変更でビームラインをも変更できる（もちろんDetectorInfo.xmlも変更しないと意味がないが）。 .. code-block:: python DAT = mm.ElementContainerMatrix() event_conv.SetElementContainerMatrix( DAT ) 最後に空っぽのElementContainerMatrixを用意（ここにヒストグラムデータを詰め込む）し、ヒストグラム化したデータを詰め込む。 以上がヒストグラム化における基本的な処理である。他の検出器に関しても、使用する関数（クラス）が違うだけで、基本的な処理は同じである。 WiringInfoおよびDetectorInfo編集関数 ===================================== ヒストグラム化基礎関数に渡すWiringInfoやDetectorInfoを編集するクラスである。WiringInfo用クラスとDetectorInfo用クラスとがある。基本的な使い方は雛形となるWiringInfoやDetectorInfoを指定し、データ処理ごとに変更されるパラメーター部分を編集し、一時ファイルとして書き出すものである。もちろん、ゼロからの作成も可能になっている。将来はこれにGUIをつけて編集することも視野に入れてはいるが実現はしていない。 これも対象となる検出器のタイプによりクラスが異なる場合もある。 +------------+--------------------------------+--------------------------------------------+ |対象 |クラス |機能 | +============+================================+============================================+ |WiringInfo |UtsusemiWiringInfoEditorTemplate|WiringInfo編集の基盤クラス。 | | | |この関数を直接呼び出すことはない。 | | +--------------------------------+--------------------------------------------+ | |UtsusemiWiringInfoEditorNeunet |NEUNET用WiringInfo編集クラス | +------------+--------------------------------+--------------------------------------------+ |DetectorInfo|UtsusemiDetectorInfoEditorBase |DetectorInfo編集の基盤クラス。現状、 | | | |このクラスで空蟬対応の装置を全てカバーする。| +------------+--------------------------------+--------------------------------------------+ ここでも紹介するにとどめる。使い方やメソッドはリファレンスを参照のこと。 パラメータファイルとRun Numberの関連性 ======================================= 前述の雛形としてのWiringInfoやDetectorInfoの内容は、通常大きな変更はない。しかしビームラインにおける検出器の増強や使用するモジュールの変更など、時にはパラメーターに大きな変更が必要な場合も発生する。その場合は雛形自体を変更したほうが効率が良い。また同じRun Numberであっても、微妙に使用するパラメーターを変更したい場合もある。例えば試験測定を行って解析に必要なパラメーター自体を決定するなど、通常のユーザーが使用しているパラメーターとは異なる値を利用したい場合である。これらの需要を満たすために空蟬のヒストグラム化においては、 「Run Numberや目的によって使用するパラメーターファイル（WiringInfoとDetectorInfo）の雛形を切り替える」 仕組みを取り入れている。これがenviron_anaとAnaModeの概念である。 ----------------------- environ_anaの役割 ----------------------- environ_ana.xml（以後enviro_ana）には、Run Numberに応じて使用するWiringInfoとDetectorInfoを切り替えるための情報を記述する。 またenviron_anaのバージョン0.4からは、AnaModeという概念を導入した。同じRun Numberでも目的に応じてさらにWiringInfoなどを切り替えたい場合、それぞれの目的をAnaModeと名付けたパラメーターで表し、パラメータファイルをグループ化する。AnaModeは正の整数であるが、その具体的な目的と設定値は各ビームラインで決めることにする。 このファイルはWiringInfoやDetectorInfoの雛形同様、装置管理者クラスのみ変更することになる。 envoron_anaに含まれる情報は主に以下のようなものである。 +------------+--------------------------+ |startrun |Run Numberの領域（の先頭）| +------------+--------------------------+ |endrun |Run Numberの領域（の末尾）| +------------+--------------------------+ |mode |AnaMode | +------------+--------------------------+ |wiringinfo |WiringInfoファイル名 | +------------+--------------------------+ |detectorinfo|DetectorInfoファイル名 | +------------+--------------------------+ フォーマットの詳細は別項（　　）で述べる。 ------------------------- environ_anaの解析 ------------------------- environ_anaファイルの解析には *UtsusemiAnaEnvironReader* クラスを用いる。 このクラスはRun NumberとAnaModeを与えると、environ_anaを解析し、そのRun NumberとAnaModeに対応したパラメータファイルの絶対パスを返す。このパスを利用して、WiringInfoおよびDetectorInfo編集関数に渡したり（ *UtsusemiGetNeunetHistogram* 内でもこのような動作をしている）、直接ヒストグラム化基礎関数に渡したりできる。 -------------------------- 各種ファイルの格納場所 -------------------------- MLFにおける空蟬環境では、WiringInfoファイル, DetectorInfoファイル, そしてそれらを統括するenviron_anaファイルは、決められた場所に存在していることが期待される（ここでの場所がデフォルトとして設定されている）。 具体的には 1. environ_anaは、環境変数 *UTSUSEMI_USR_DIR* 内にある *ana/xml* に 2. WiringInfoやDetectorInfoは、environ_anaと同じ場所か、環境変数 *UTSUSEMI_USR_PRIV_HOME* （通常は\${HOME}）内にある *ana/xml* に 存在することが期待される。