========================================================== MLFイベントデータ処理（ヒストグラム化）の概観 ========================================================== :Status: 作成中 概要 ==== ヒストグラム化とは、MLFで導入されているイベント記録型データ、特にDAQミドルウェアから出力されるデータファイルを読み込み、一般的なデータ処理を行うためのフォーマットであるヒストグラムに変換する処理のことである。空蟬のもつ機能のうち、最も汎用性があり、かつ最も重要なものである。 ここでは空蟬環境におけるヒストグラム処理の構造や処理に必要な情報を簡単に示す。本稿で示す情報は、単に空蟬を使用するだけのユーザーならあまり必要ではないかもしれないが、装置責任者クラスには知っておいていただきたい。将来自分で解析スクリプトを書いたり、自分専用の環境を作成したりする際に役に立つであろう。 空蟬環境におけるヒストグラム化の基本関数である *UtsusemiGetNeunetHistogram* は、まさに本稿で示された情報が集約されているものである。 イベント記録型データとは =========================== MLFで扱われる測定データの大半は「イベント記録型データ」と呼ばれる形式で収集されている。 従来のヒストグラム記録型データ収集システムでは、検出器からのシグナルは、エレキ（データ収集のハードウェア）内であらかじめ範囲や解像度を指定してメモリやストレージ上に作成されたヒストグラムに振り分けてゆく。またハードウェアでの処理であるため、高速な処理が可能である。測定者はこのヒストグラムを1次データ（これ以上遡ることのできないデータ、生データ）として扱うことになる。ヒストグラムデータは扱いが単純で可視化も容易であるが、ヒストグラムの範囲や解像度などは予め決定しておく必要があり、測定中に変更はできない。 この結果、いくつかの問題点が発生する。例えばノイズ問題である。測定中に何らかの原因でシグナルに瞬間的、もしくは一定期間誤ったシグナル（電気的ノイズや測定条件の揺らぎなど）が発生した場合、ヒストグラム記録型の収集システムではそれらの誤った情報もヒストグラムに無差別に加えられ、最終的に得られたデータにはコンタミネーションが含まれることになる。このようなコンタミネーションは原理的には除去不可能であり、そのデータは使用不可能、もしくは精度が著しく悪くなる。一方で測定後の可視化を行って初めて、予め決めておいたヒストグラムの範囲や解像度では不足であることが明らかとなることもある。この場合もより広い範囲、もしくはより精度の高い情報はすでに欠落しており、取り戻すことは不可能である。対策としては予測した必要解像度よりも十分に高い解像度でヒストグラムを作成することで回避できるが、ハードウェアリソースによる制限や予測に基づくリスクの回避は難しい。 これらの問題点をソフトウェア的に回避する方法が、イベント記録型である。 イベント記録型とは、中性子の検知をはじめとする測定開始後から終了までの試料環境や状況の変化など、実時間軸に沿って発生する事象をイベントとして捉え、それらを事象及び時刻情報の組み合わせで記録する方法である。観測された事象が時系列に記録されるので、測定開始後にデータ処理の段階で、任意の時間帯のデータを柔軟に取り出すことが可能となる。 すなわち中性子検知データがイベント型で記録されていれば、時系列に沿った時間分割が非常に自由、かつ柔軟に行えることになる。 これは任意の時間帯のデータを抜き出すだけでなく、取り除くことも可能であることを意味する。 例えば、時系列に変化する試料や装置の状態を同時に記録しておけば、任意の状態の中性子検知データを必要に応じて柔軟に取り出すこともできる。また測定中に発生した何らかのコンタミネーション、例えば一時的な（しかし無視できない強度の）電気的ノイズが中性子検知シグナルとして記録された場合でも、その発生時間の情報があればノイズで汚染された部分のデータだけを取り除くことができる。特に、測定時の時間経過に伴う状況変化に応じて任意のデータを抜き出すことをフィルタリングと呼んでいるが、これは単純な測定時の時間経過でデータを分割する処理と比較すると、特定の条件を満たす時刻領域を抜き出すという点では全く同一の機能である。よってイベント型データに関わる全てのフィルタリング機能は、時間分解を柔軟に行う機能であると言い換えることが可能である。 ヒストグラム化に必要な情報 =========================== 空蟬のヒストグラム化の開発では、基礎的関数は共通化し、多様な装置に対応させることを大きな目的としている。開発者視点では少ないリソースで高度化も容易であるし、ユーザー視点でも、複数の装置にわたるデータに対し、様々な単位変換を行うヒストグラム化処理（データリダクション）に対し、「同じ関数を情報（パラメーター）ファイルを変更するだけ」で対応できるというメリットがある。また、扱う情報ファイルも最小限にまとめてしまうことを基本路線としている。 では、ヒストグラム化に必要な情報は何であろうか。 まずハードウェア・システムの面から見る。MLFのデータ収集システム（検出器＋DAQミドルウェア）では、検出器が捉えたシグナルはハードウェア的にイベント化され、何本かまとめられた単位（モジュール）ごとにDAQミドルウェアによってファイルに書き込まれる。一方でデータリダクションや解析に最も必要となる情報は「どこでどんな中性子が検出されたか」であるから、収集された中性子散乱のデータがどの検出位置(pixel)を持つかを区別する必要がある。また、ヒストグラム化処理自体ついての情報も重要で、例えばどのようなヒストグラムに変換したいのか、という情報を与える必要がある。 次に実験遂行の面から見ると、イベント記録された測定データの中から与えられた条件でのイベントの抜き出しや統合を行うことで、非常に多彩な処理を行うことができる。その抜き出す処理をフィルタリングと呼ぶが、このフィルタリングを行なった結果もヒストグラムとして取り出すことになる。すなわちフィルタリングを行うための情報もヒストグラム化の重要な要素の一つである。 以上述べてきたことから、ヒストグラム化に求められる情報をざっくりとまとめてみる。 まずハードウェア・システム情報として、 1. DAQの生み出すイベントデータとヒストグラムを結びつける情報（どのファイルのどのイベントがどのpixelのデータなのか） 2. 検出器などの位置情報（どのPixelがどこの場所を意味しているのか） の二つの情報が重要となる。これらは、それぞれのビームラインのハードウェアに依存するものであるが、それほど頻繁に変更がない情報でもある。 他方、データリダクション情報としては、 3. ヒストグラム化情報（横軸、範囲、単位変換パラメーターなど） 4. Time Focusing情報 5. フィルタリング処理用情報 などの、データ処理ごとに変更が必要な情報が求められる。 以上述べたように、必要な情報は非常に多岐にわたるため、実際には個別に与えるのではなく、少数のパラメーターファイルに書き込み、そのファイルを基礎的関数に引数として与えよみこませることでヒストグラム化を実行することとした。 ただ、データ処理ごとに一からパラメーターファイルを作成するのはコストがかかるし、ハードウェア情報をどこかに持つ必要があるのは変わらないので、 1. 装置ごとにパラメーターファイルの「雛形」を用意して 2. それを最小限書き換えて文字列(XML)とし 3. パラメータ文字列(XML)を基礎的関数に引数として渡す という形にした。特にハードウェア・システム情報は変更が少ないので、この形式が有効だと考える。 情報のパラメーター化 ====================== 前節で述べた情報は、大まかに 1. ヒストグラムを作成するのに使用する情報 2. 検出器配置など装置内の位置情報に関わる情報 3. 時間経過に伴う状態変化によるデータ分割（フィルタリング）に関わる情報 の３つに分けて定義し、それぞれ 1. WiringInfo 2. DetectorInfo 3. CaseInfo と名付けている。以下にそれぞれの情報の主な役割を示す。 +---------------------------------------------------------+--------+ | 空蟬に必要なパラメータファイル |記述言語| +=============+===========================================+========+ |Wiring Info |イベントとPixelIdの関連付け、 |XML | | |ヒストグラム化に必要な情報（横軸定義） | | +-------------+-------------------------------------------+--------+ |Detector Info|検出器の位置情報、装置関連の情報 |XML | | |（線源-試料間距離L1、Time Focusing情報、 | | | |バンク情報など） | | +-------------+-------------------------------------------+--------+ |Case Info |汎用電気シグナルをイベント記録できる |XML | | |TrigNETボードの出力イベントデータを利用した| | | |時間分解を行うための情報 | | +-------------+-------------------------------------------+--------+ ------------------------------------------------- DAQとヒストグラムを結ぶWiringInfo ------------------------------------------------- WiringInfoは、ヒストグラム化に先立ち、扱うイベントデータに応じて準備する必要がある。 なお、Wiring Infoで使用される主要な情報は以下のようなものである。 +-----------------------------------------------------------------------+ | Wiring Info内ので扱われる情報 | +=================+=====================================================+ |daqId | データ収集システムのPCのID | +-----------------+-----------------------------------------------------+ |moduleNo | データ収集システムのPC内におけるモジュール識別用番号| +-----------------+-----------------------------------------------------+ |detId | 検出器のID | +-----------------+-----------------------------------------------------+ |pixelId | 検出位置のID（コード内部でのみ必要な情報） | +-----------------+-----------------------------------------------------+ |tofBinInfo | ヒストグラムの横軸変換のパターン指定 | +-----------------+-----------------------------------------------------+ |tofBinPatternList| ヒストグラムの横軸変換のパターン記述 | +-----------------+-----------------------------------------------------+ ここで、"ID"は装置（ビームライン）内で固有の番号を示し、"No"は固有ではない番号を表している。 DaqIdやmoduleNo, detIdは、装置自体が大きくアップグレードしないと変更しない部分である。tofBinInfoやtofBinPatternListなどは、解析ごとに変更がある部分である。 また扱う検出器により、必要なパラメータも異なる（psdParamsなど）ことにも留意する必要がある。 詳細なフォーマットや編集方法（編集する関数など）は、別項を参照のこと（...）。 ----------------------------------------------- 検出器の位置、構成情報DetectorInfo ----------------------------------------------- DetectorInfoは、WiringInfo同様、ヒストグラム化に先立ち、扱うイベントデータに応じて準備する必要がある。 なお、DetectorInfoで使用される主要な情報は以下のようなものである。 +---------------------------------------------------------------------------------------+ | DetectorInfo内で扱われる情報 | +=======================+===============================================================+ |Instrument Info |装置の定数L1（線源と試料の間の距離[mm]）等を指定 | +-----------------------+---------------------------------------------------------------+ |Time Focusing Parameter| 検出器間の距離による違いを補正する値 | +-----------------------+---------------------------------------------------------------+ |Position Info | 検出器の位置情報 | +-----------------------+---------------------------------------------------------------+ |Bank Info | 検出器のグループ化 | +-----------------------+---------------------------------------------------------------+ |Detector Structure | 検出機の構造（材料や内部ガス構成）。検出器感度補正などに使用。| +-----------------------+---------------------------------------------------------------+ このファイルにおいては、装置自体が大きくアップグレードしないと変更されない情報が大部分である。 詳細なフォーマットや編集方法（編集する関数など）は、別項を参照のこと（...）。 ----------------------------------------------- フィルタリング処理情報CaseInfo ----------------------------------------------- CaseInfoは他のファイル同様、ヒストグラム化を行う前に用意する必要がある。この詳細については * ヒストグラム化の基盤情報 * CaseInfoとそのフォーマットについて を参照のこと。 イベントデータファイルの格納場所 =================================== イベントデータファイルの格納場所は、あるビームラインXXXのデータはすべて、フォルダXXXの下におくことを求められる。このデータフォルダを配置する場所はMLFのデフォルトでは :: /data や :: /opt/mlfsoft/data である。このような形で複数のビームラインのデータを共存させている。 後述するヒストグラム化の関数に必要なデータの場所の指定には、XXXの一つ上の階層を示せば良い（"/data"や"/opt/mlfsoft/data"など）。 これらの場所は、環境変数 *UTSUSEMI_DATA_DIR* で指定される。 |image0| |image1| ヒストグラム化基礎関数 ========================= 空蟬のヒストグラム化の基礎関数としてあげられるものは、*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 import Manyo.Utsusemi as mu event_conv = mu.UtsusemiEventDataConverterNeunet() evtnt_conv.SetEventParams( "path/to/WiringInfo.xml", "path/to/DetectorInfo.xml" ) event_conv.SetHistAllocation() event_conv.LoadEventDataFiles( 123, "path/to/data" ) DAT = Manyo.ElementContainerMatrix() event_conv.SetElementContainerMatrix( DAT ) スクリプトの解説 ---------------- .. code-block:: python import Manyo 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 = Manyo.ElementContainerMatrix() event_conv.SetElementContainerMatrix( DAT ) 最後に空っぽのElementContainerMatrixを用意（ここにヒストグラムデータを詰め込む）し、ヒストグラム化したデータを詰め込む。 以上がヒストグラム化における基本的な処理である。他の検出器に関しても、使用する関数（クラス）が違うだけで、基本的な処理は同じである。 WiringInfoおよびDetectorInfo編集関数 ===================================== ヒストグラム化基礎関数に渡すWiringInfoやDetectorInfoを編集するクラスである。WiringInfo用クラスとDetectorInfo用クラスとがある。基本的な使い方は雛形となるWiringInfoやDetectorInfoを指定し、データ処理ごとに変更されるパラメーター部分を編集し、一時ファイルとして書き出すものである。もちろん、ゼロからの作成も可能になっている。将来はこれにGUIをつけて編集することも視野に入れてはいるが実現はしていない。 これも対象となる検出器のタイプによりクラスが異なる場合もある。 +------------+--------------------------------+--------------------------------------------+ |対象 |クラス |機能 | +============+================================+============================================+ |WiringInfo |UtsusemiWiringInfoEditorBase |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_BASE_DIR* 内にある *XXX/ana/xml* （ ${UTSUSEMI_BASE_DIR}/{UTSUSEMI_INST_CODE}/ana/xml ） 2. WiringInfoやDetectorInfoは、environ_anaと同じ場所か、環境変数 *UTSUSEMI_USR_DIR* （通常は\${HOME}）内にある *ana/xml* に 3. コードを動作させている（カレント）フォルダ のいずれかに存在していれば空蟬は見つけることが可能である。 .. |image0| image:: media/Env_FolderStructure_v1.png :scale: 30 % :alt: figure of folders structure on Utsusemi environment .. |image1| image:: media/Env_FolderStructure_v2.png :scale: 30 % :alt: figure of folders structure on Utsusemi environment