.. _CUI_UtsusemiD4Matrix2:

D4Mat2Slicer（Step By Step測定及び連続回転測定）用コマンド
============================================================

**（2022/3/9更新 作成中）**

.. contents:: 目次
    :depth: 2

多次元系単結晶試料に対する非弾性散乱測定において、広い運動量空間をカバーするためには、試料に対する入射中性子の方位の異なる測定を複数回行い一つの運動量エネルギー空間にあるものとみなしてデータを扱う必要がある。

その測定手法には２種類、 *Step By Step測定* と *連続回転測定* とがある。これらの測定データを処理するソフトウェアとして、 **D4mat2Slicer** （ 参照： :ref:`「D4mat2Slicerマニュアル」<D4Mat2Slicer>` があるが、本章ではそのコマンドラインインターフェースを紹介する。

使用される関数（C++クラス）は、 **UtsusemiD4Matrix2** である。

------
注意
------
まだ機能的には未完成で不十分なところが多いので、使用には十分気をつけること。


-------------------------------------
サンプルコード（Step By Step測定用）
-------------------------------------

Step By Step測定のデータを利用する場合に使用できるものを紹介する。

:ref:`多次元系単結晶試料非弾性散乱測定（回転測定）のデータ処理（Step-by-Step法）<D4Mat_StepByStep>` でも使用される RunListファイルを利用して処理を行うスクリプトである。

そのため、D4Mat変換用ファイル（vbinファイル）を作成するスクリプト（Extractスクリプト）とよく似た構造であり、特にRunListファイルを処理する部分は全く同じである。

処理として想定している流れとしては以下のようなものである。

1. RunListファイルを利用してそれぞれのRun情報とゴニオの角度情報を取り出す
2. スクリプトに記述したパラメータと1.の情報を利用してそれぞれのデータをヒストグラム化し、角度情報とともに取り込む
3. スクリプトに記述した試料情報を利用し、射影処理を行う
4. 2Dや3Dのスライス及び可視化を行う
5. D4MatSlicerで可視化できるD4Matデータを出力する。


大雑把にいえば、D4Mat用のスクリプト（いわゆる *Extract_runlist.py* ）との相違点は、vbinファイルを書き出すコマンドである

.. code-block:: python
    
    Cmm.VisContMOutputFileByPhi(DAT, XtalParam, PhiValue, savePath)

の部分をD4Mat2へ取り込むためのコマンド

.. code-block:: python
    
    UD.ImportEcmStepByStep( DAT, PhiValue, str(PhiValue) ) # 非弾性処理済みデータを回転角度とともに入力

に置き換えるところと、射影処理の部分

.. code-block:: python
    
    UD.SetD4MatSampleInfo( LatticeConst, Uvector, Vvector, RotateSteps ) # 試料情報の入力
    UD.Projection( ProjAxes )                                  # 射影処理の実行


である。

サンプルコード (A-1)
------------------------------------

上記のステップのうち

1. RunListファイルを利用してそれぞれのRun情報とゴニオの角度情報を取り出す
2. スクリプトに記述したパラメータと1.の情報を利用してそれぞれのデータをヒストグラム化し、角度情報とともに取り込む
3. スクリプトに記述した試料情報を利用し、射影処理を行う

を行うコードを示す。


.. code-block:: python
    :caption: D4MatSlicer command script
    :name: A-1.py
    
    #! /usr/bin/env python3
    from __future__ import print_function
    import os
    import sys
    import DR
    import Cmm
    
    #####################
    # modify here
    ####################
    Ei=30.04
    delta_hw = 0.2
    hw_min = -5.0
    hw_max = 28.0
    maskfile = "default"
    normFactor = 1000000.0
    XtalParam = "XtalParam.xml"
    outFile = "Sample1.d4m"
    gonioValueAtZero = 31.032
    
    # Sample Info
    LatticeConst = [ 3.615, 3.615, 3.615, 90.0, 90.0, 90.0 ]
    Uvector = [ 1.0, 0.0, 0.0 ]
    Vvector = [ 0.0, 1.0, 1.0 ]
    RotateSteps = []
    ProjAxes = [ 1.0, 0.0, 0.0, 0.0,
                 0.0, 1.0, 1.0, 0.0,
                 0.0,-1.0, 1.0, 0.0,
                 0.0, 0.0, 0.0, 1.0 ]
    #########################
    
    argv = sys.argv
    print("len(argv)={}".format(len(argv)))
    
    listFileName=""
    if len(argv)==2:
        if os.path.exists(argv[1]):
            listFileName=argv[1]
            print("RunList=[]".format(listFileName))
        else:
            raise UserWarning("Not found file=%s"%(argv[1]))
    else:
        print("Usage::")
        print("        $ ./{} <filename of runlist>".format(argv[0]))
        print("        ")
        print("        $ python {} <filename of runlist>".format(argv[0]))
        sys.exit(0)
        
    import utsusemi.ana.Reduction.BaseCommandsInEla as BC
    paramDic = {"normFactor":normFactor,"gonio":gonioValueAtZero}
    AngleList, condsDict  = BC.LoadRunListToExtract( listFileName, paramDic, mergeAngles=True )
    
    ## Data Reduction
    import Manyo
    import Manyo.Utsusemi as mu
    
    UD = mu.UtsusemiD4Matrix2()               # D4matSlicer2のコマンドを実行するための用意
    UD.ClearAll()                             # データのクリア（念のため）
    # UD.LoadData(outFile)                    # 以前のデータに追記する場合に読み込み
    
    for angle_key in AngleList:
        angle  = float( angle_key )
        runNos = condsDict[ angle_key ][0]
        norm   = condsDict[ angle_key ][1]
        print("==============[ %s:%8.3f,%10.5f ]" % (runNos,angle,norm))
        DAT = DR.GetDataOfMonochroEi3( runNos, Ei, delta_hw, "%g %g"%(hw_min,hw_max), MaskFile=maskfile, NormFactor=norm )
        UD.ImportEcmStepByStep( DAT, angle, angle_key ) # 非弾性処理済みデータを回転角度とともに入力
        del DAT                               # 入力済みのデータは削除して良い（推奨）
    
    ### Save Data
    #UD.SetXtalParam(XtalParam)                                           # 保存用XtalParam情報（VisualCont情報のみ）
    #UD.SaveData( outFile )                                               # ファイルに保存
    
    ### Projection
    UD.SetD4MatSampleInfo( LatticeConst, Uvector, Vvector, RotateSteps ) # 試料情報の入力
    UD.Projection( ProjAxes )                                  # 射影処理の実行
    

    

もしデータをファイルに保存すれば、そのままD4Mat2Slicerから読み込むことができ、すぐにProjectionやSliceができる。

^^^^^^^^^^^^^^^^^^^^^^
使用上の注意と問題点
^^^^^^^^^^^^^^^^^^^^^^
ただし、以下にあげるような問題点（未実装）がある。

- XtalParamとの連携が不十分

  - 個別に取り込んだRunのメタ情報（RunNOやGonio角度、Proton数など）がXtalParamの情報として反映されない（修正予定）
  - Eiやhwの範囲などの情報も同様（修正予定）
  - データ保存用として既存のXtalparamを登録する( *UD.SetXtalParam(XtalParam)* )ことはできるが、あくまでD4MatSlicerで読み込んだときに格子定数やUV情報、射影、スライスの情報を示すためだけである。

- 既存のd4mデータファイルに追記する形で利用する場合、同じ角度のデータであってもマージされないため、再度d4mデータファイルに保存するとサイズが大きくなる

  - これはD4Mat2Slicerでも同様であると思われるが未確認
  - 大きな仕様変更が必要なため、当面の修正は行わない
  - 同じ角度を何度も測定する場合、一連の測定が終了したときに最初から処理しなおした方が良い


サンプルコード(A-2)
------------------------------------
前述の射影まで処理スクリプトに以下のコードを加えると、2Dスライス＋プロットを行うことができる。
すなわち前述の

4. 2Dスライス及び可視化を行う

を行うためのスクリプトである。

スライスに必要な各軸のパラメータの与え方は :ref:`運動量エネルギー空間への射影に関連するコマンド<CUI_UtsusemiSqeCalc>` と同等である。

.. code-block:: python
    
    ### Slice 2D
    ax1 = ["T", -0.420,2.350]
    ax2 = ["T", -0.876,3.006]
    ax3 = ["X", -0.916,0.841,0.02]
    ax4 = ["Y", -0.600,35.70,0.3]
    ax_dFold = []
    ax_units = ["rlu","rlu","rlu","meV"]
    
    sliced_eca = Manyo.ElementContainerArray()
    if UD.Slice2d( sliced_eca, ax1, ax2, ax3, ax4, ax_dFold, ax_units ):
        print("## Slice succeeded.")
        ## Plot sliced data on display with GUI
        import uGao.M2PlotPlusCui as mp                 # 夕顔のGUIを起動してプロットする
        p=mp.M2PlotPlusCui(sliced_eca)
        p.ShowData()
        p.SetLabels("Qa [rlu]","Qb [rlu]")
        del p
        
        ## Save sliced data as PNG figure file          # 夕顔で表示させずに画像だけ保存も可能
        import uGao.U2IFInDark as UIF
        p=UIF.U2IFInDark()
        p.SetKeys("ax3","ax4","Intensity")              # 横軸、縦軸のキー("ax1", "ax2", "ax3", "ax4")、および強度のキー
        p.SetData(sliced_eca)                           # データの読み込み
        p.SetRange(False,0.0,40.0)                      # 強度の範囲指定（最初のFalseはAuto Scaleはしないの意味）
        p.SetTitles("Test Data","SubTitle")             # TitleとSubTitle
        p.SetLabels("Qa (rlu)","hw (meV)")              # 軸のラベル
        p.SaveFile( "TestData.png" )                    # 画像ファイルとして保存
        del p
    else:
        print("## Slice failed.")


サンプルコード(A-3) 
---------------------------------------------
前述の射影まで処理スクリプトに以下のコードを加えると、D4Matデータへの書き出しが行える。

5. D4MatSlicerで可視化できるD4Matデータを出力する。

.. code-block:: python
    
    ### Make D4Mat data
    v=UD.PutQRange()
    
    ax1 = [v[0],v[1],0.02]
    ax2 = [v[2],v[3],0.02]
    ax3 = [v[4],v[5],0.1]
    ax4 = [v[6],v[7],0.5]
    titles = [ "Qa","Qb","Qc","Energy" ]
    data_dir = "./D4Mat"
    paramfile = "D4Mat.xml"
    
    ret = UD.AllocateD4MatOnDisk(ax1, ax2, ax3, ax4, titles, data_dir, paramfile )
    if ret:
        print("Suceeded to output D4Mat data")



-------------------------------------
サンプルコード（連続回転測定用）
-------------------------------------

連続回転測定のデータを処理する場合に使用するものを紹介する。

1. 測定情報をパラメータとしてデータを角度毎のヒストグラムに落とし込む処理をする (Data Reduction)
2. 試料の情報を利用してヒストグラムデータを見たい座標に射影する (Projection))
3. 射影データを2Dスライスする
4. 射影データを3Dスライスしてテキストファイルに保存する

サンプルコード(B-1)
------------------------------------

連続回転測定のデータ処理のステップのうち

1. 測定情報をパラメータとしてデータを角度毎のヒストグラムに落とし込む処理をする (Data Reduction)
2. 試料の情報を利用してヒストグラムデータを見たい座標に射影する (Projection))

を行うものである。

.. code-block:: python
    :caption: D4Mat2 commands scripts for the continuous rotation method
    :name: Sample-A-2.py
    
    #!/usr/bin/python
    # -*- coding: utf-8 -*-
    
    ############################
    # Data Reduction parameters
    ############################
    runNo = 17714
    Ei = 50.0     #[meV]
    HW_min = 0.0  #[meV]
    HW_max = 3.0  #[meV]
    HW_bin = 1.0  #[meV]
    
    mask_file = "mask.txt"
    
    st_deg = -31.0 #[degree]
    ed_deg = 90.0  #[degree]
    w_deg = 0.5    #[degree]
    
    t_start = -1   #[seconds]
    t_end = -1     #[seconds]
    ############################
    # Sample Info
    ############################
    LatticeConst = [ 3.615, 3.615, 3.615, 90.0, 90.0, 90.0 ]
    Uvector = [ 0.0, 0.0, 1.0 ]
    Vvector = [ 1.0, 1.0, 0.0 ]
    ProjAxes = [ 0.0, 0.0, 1.0, 0.0,
                 1.0, 1.0, 0.0, 0.0,
                 1.0,-1.0, 0.0, 0.0,
                 0.0, 0.0, 0.0, 1.0 ]
    RotateSteps = []
    ############################
    DataReductParams = [t_start, t_end, Ei, HW_bin, HW_min, HW_max, st_deg, ed_deg, w_deg ]
    data_dir = "/data"
    ############################
    
    
    
    ################################
    import Manyo
    import Manyo.Utsusemi as mu
    try:
        from vis.D4Mat2Slicer import D4Mat2Utils ## for Utsusemi 0.3.7
    except:
        from utsusemi.vis.D4Mat2SlicerQ import D4Mat2Utils ## for Utsusemi 4.0
    import sys
    
    #### Data Reduction from raw data files
    ### Make parameter files
    st_Params = "hw,%f,%f,%f,%f"%( (Ei,HW_min,HW_max,HW_bin ) )
    DU = D4Mat2Utils()
    wfile,dfile = DU.MakeTempInfoFiles(runNo,st_Params)
    cfile = DU.MakeCaseInfoFile( st_deg, ed_deg, w_deg, runNo )
    
    ### Do Data Reduction
    EDC=mu.UtsusemiEventDataConverterNeunet()
    EDC.LoadParamFiles( wfile, dfile, cfile )
    
    if t_start<0 and t_end<0:
        pass
    else:
        if not EDC.SetRangeOfSingleTimeSlicing( t_start, t_end ):
            msg = "TimeSlicing arguments are invalid : "+str(t_start)+","+str(t_end)
            raise UserWarning(msg)
    
    EDC.LoadTrignetEventFile( runNo, data_dir, "" )
    EDC.SetHistAllocation()
    EDC.LoadEventDataFiles( runNo, data_dir, "" )
    
    print( " ------------ Data Reduction finish" )
    
    #### Projection
    ### Make Angle inforamtion
    num_of_cases = EDC.PutNumOfCases()
    case_list = EDC.PutListOfCounterConditions()
    
    IND = Manyo.MakeUInt4Vector()
    PHI = Manyo.MakeDoubleVector()
    for i in range(num_of_cases):
        IND.push_back(i+1)
        PHI.push_back( (case_list[(i+1)*2] + case_list[(i+1)*2 +1])/2.0 )
    
    ### Get parameter for Solid Angle Corrections
    dOmega = 1.0
    hh = Manyo.HeaderBase()
    if EDC.AddRunInfoToHeader(hh):
        L2 = hh.PutDouble("TypicalL2")
        dS = hh.PutDouble("TypicalDS")
        dOmega = dS/(L2*L2)
    
    mask_path = mu.FindParamFilePath( mask_file )
    
    ### Set Data to D4Matrix2 and Do Projection
    D4M = mu.UtsusemiD4Matrix2()
    D4M.SetD4MatSampleInfo( LatticeConst, Uvector, Vvector, RotateSteps )
    D4M.SetD4MatDataReductionInfo( DataReductParams )
    D4M.SetD4MatRunNo( runNo )
    D4M.SetD4MatProjectionAxesInfo( ProjAxes )
    D4M.ImportEcmsContRot( EDC, IND, PHI, mask_path, dOmega )
    
    print( " ------------ Projection finish" )
    



サンプルコード(B-2)
-------------------------

3. 射影データを2Dスライスする

.. code-block:: python
    
    #### Slice on D4Matrix2
    ### Get maximum range of D4Matrix2 data axes
    limRange = D4M.GetAxLimit()
    
    ##### 2D slice test
    ### Make parameters for slicing
    Ax1_slice = [ "X", limRange[0], limRange[1], 0.02 ]
    Ax2_slice = [ "Y", limRange[2], limRange[3], 0.02 ]
    Ax3_slice = [ "T", -0.1, 0.1 ]
    Ax4_slice = [ "T", HW_min, HW_min+HW_bin ]
    Foldings = []
    
    ### Do Slice and plot
    sliced_eca = Manyo.ElementContainerArray()
    if D4M.Slice2d( sliced_eca, Ax1_slice, Ax2_slice, Ax3_slice, Ax4_slice, Foldings ):
        try:    ## for Utsusemi 0.3.7
            import vis.M2Plot as mp
            p=mp.M2Plot(sliced_eca)
        except: ## for Utsusemi 4.0
            import uGao.M2PlotPlusCui as mp
            p=mp.M2PlotPlusCui(sliced_eca)
    







-----------------------------
UtsusemiD4Matrix2リファレンス
-----------------------------
以下に **UtsusemiD4Matrix2** で使用できるコマンド（メソッド）のうち、主要なものを示す。

.. py:class:: UtsusemiD4Matrix2
    
    連続回転測定データの処理や、StepByStepデータの処理を、全データをメモリ上に保管することにより、高速に、かつ処理の柔軟性を高めたものである。

.. py:method:: UtsusemiD4Matrix2.SetD4MatSampleInfo( LatticeConst, Uvector, Vvector, RotateSteps )
    
    試料情報（格子定数、方位情報など）を与える。
    
    :param list(float) LatticeConsts: 格子定数の指定 [ a, b, c,α,β,γ]
    :param list(float) Uvec: U-vector
    :param list(float) Vvec: V-vector
    :param list(float) Rvec: U-V-vectorの回転を指定
    :return: 結果 True 成功, False 失敗
    :rtype: bool

.. py:method:: UtsusemiD4Matrix2.ImportEcmStepByStep( DAT, PhiValue, title )
    
    StepByStep測定の非弾性散乱処理済みのデータ（ElementContainerMatrix）を角度情報とともに取り込む。この時点では射影計算はなされない。
    
    :param ElementContainerMatrix ecm: データ処理済みヒストグラム
    :param float PhiValue: U-vectorと平行な方位を0度とした時の角度
    :param string title: このデータに対するタイトル
    :return: 結果 True 成功, False 失敗
    :rtype: bool

.. py:method:: UtsusemiD4Matrix2.Projection( ProjAxes )
    
    StepByStep測定及び連続回転測定の取り込み済みのデータに対し、射影処理を行う。
    
    :param list(float) ProjAxes: 射影軸の指定
    :return: 結果 True 成功, False 失敗
    :rtype: bool

.. py:method:: UtsusemiD4Matrix2.Slice2d( sliced_eca, sl_ax1, sl_ax2, sl_ax3, sl_ax4, sl_dFold )
    
    射影処理終了後のデータに対し2Dスライスを行う。
    
    :param ElementContainerArray sliced_eca: スライスされたデータを収めるコンテナ
    :param list(float) sl_ax1: 射影軸1のスライス情報
    :param list(float) sl_ax2: 射影軸2のスライス情報
    :param list(float) sl_ax3: 射影軸3のスライス情報
    :param list(float) sl_ax4: 射影軸4のスライス情報
    :param list sl_dFold: 畳み込み情報
    :return: 結果 True 成功, False 失敗
    :rtype: bool
    
    
    射影軸ごとにlist(float)でスライス情報を与えるが、そのフォーマットは以下のとおり。
    
    **[ "A", min, max, (width) (,folding) ]**
    
    +-------+------+----------------------------------------------------+
    |要素   |タイプ|説明                                                |
    +=======+======+====================================================+
    |"A"    |str   |軸の役割, X軸なら"X"、Y軸なら"Y"、Z軸なら"Z"、      |
    |       |      |Thickness軸なら"T"                                  |
    +-------+------+----------------------------------------------------+
    |min    |float |範囲の最小値                                        |
    +-------+------+----------------------------------------------------+
    |max    |float |範囲の最大値                                        |
    +-------+------+----------------------------------------------------+
    |width  |float |bin幅、ただしAが"X"か"Y","Z"の時のみ有効            |
    +-------+------+----------------------------------------------------+
    |folding|float |その軸の畳み込みを行うQ値　（下表参照）             |
    +-------+------+----------------------------------------------------+
    
    *Folding* 値
    
    +---+--------------------+
    |-1 |（負の値）使用しない|
    +---+--------------------+
    |0.0|その軸=0で折りたたむ|
    +---+--------------------+
    |x  |その軸=xで折りたたむ|
    +---+--------------------+
    
    
    例：
    
    +--------------------------+------------------------+
    |X,Y,Z軸方向は長さ4のリスト|[ "X", -1.8, 2.6, 0.02 ]|
    +--------------------------+------------------------+
    |T軸方向は長さ3のリスト.   |[ "T", -0.1, 0.1 ]      |
    +--------------------------+------------------------+
    
    対角線での畳み込みを行う方法は未実装（2019.12.20時点）
    
    
    
    なお、2Dスライスの時は、"X","Y"が一つずつ、"T"が二つ、3Dスライスなら"X","Y","Z","T"が一つずつ指定する。

.. py:method:: UtsusemiD4Matrix2.Slice3d( sliced_ecm, sl_ax1, sl_ax2, sl_ax3, sl_ax4, sl_dFold )
    
    射影処理終了後のデータに対し3Dスライスを行う。
    
    :param ElementContainerMatrix sliced_ecm: スライスされたデータを収めるコンテナ
    :param list(float) sl_ax1: 射影軸1のスライス情報
    :param list(float) sl_ax2: 射影軸2のスライス情報
    :param list(float) sl_ax3: 射影軸3のスライス情報
    :param list(float) sl_ax4: 射影軸4のスライス情報
    :param list sl_dFold: 畳み込み情報
    :return: 結果 True 成功, False 失敗
    :rtype: bool
    
    射影軸のスライス情報は、 Slice2dを参照のこと。

.. py:method:: UtsusemiD4Matrix2.AllocateD4MatOnDisk(a1range, a2range, a3range, a4range, titles, data_dir, string paramfile )
    
    StepByStep測定の入力済みデータから、D4MatSlicer用のデータ（D4Matデータ）を出力するコマンドである。
    
    :param list(float) a1range: 射影軸1の範囲とbin幅
    :param list(float) a2range: 射影軸2の範囲とbin幅
    :param list(float) a3range: 射影軸3の範囲とbin幅
    :param list(float) a4range: 射影軸4の範囲とbin幅
    :param list(string) titles: 射影軸のタイトル
    :param string data_dir: 出力先のフォルダへのパス指定
    :param string paramfile: 出力先のパラメータファイル名
    :return: 結果 True 成功, False 失敗
    :rtype: bool
    
    射影軸の範囲とbin幅は、[ min, max, bin ] のフォーマットである。

.. py:method:: UtsusemiD4Matrix2.ExportEcmFromStepByStep( ecm, index)
    
    StepByStep測定の入力済みデータから、特定の角度のデータを取り出す。最低角度のデータをindex=0とする。
    
    :param ElementContainerMatrix ecm: 取り出すデータのコンテナ
    :param int index: 角度のインデックス
    :return: 結果 True 成功, False 失敗
    :rtype: bool
    
    例：
    .. code-block:: python
        
        ecm = ElementContainerMatrix()
        UD.ExportEcmFromStepByStep( ecm, 10 )

.. py:method:: UtsusemiD4Matrix2.ClearAll()
    
    取り込んだデータを全てクリアする。
    
    :return: None
    :rtype: None

.. py:method:: UtsusemiD4Matrix2.PutQRange()
    
    取り込んだデータから、Q領域及びhw領域のそれぞれの最小値と最大値を返す。
    
    :return: Q1, Q2, Q3, hwのそれぞれの最小値、最大値のリスト
    :rtype: list(float)
    
    戻り値は、[ Q1_min, Q1_max, Q2_min, ... , hw_max ]のサイズ8のリストである。