<commit_before># Eigerデータフォーマットとデータ処理

本稿ではBL32XUにおけるEiger X 9Mに関して記述します．
本内容はEigerのfirmware更新などによって変更される可能性があります．

## Eiger HDF5について

hdf5 (.h5)はこれまでのイメージフォーマット(.img, .cbf)と違い，複数のイメージを1つのファイルにまとめて保存することができます．
HDF5はファイルシステムのような階層構造を持っており，それぞれの階層に任意のデータ（イメージデータや実験に関するパラメータなど）を持つことができます．

Eigerの出力するhdf5は，masterとdataの2種類からなります．例えばprefixをsampleとしてデータを収集すると，

* sample_master.h5 - 実験に関する情報（波長やビームセンターなど）の他，検出器の設定情報
* sample_data_??????.h5 - 回折イメージ

data h5には複数の回折イメージが含まれており，通常100枚ごとに1ファイル作られます．
つまり100枚以下ならばsample_data_000001.h5のみ，200枚以下ならそれに加えてsample_data_000002.h5も出力されます．

sample_master.h5にはdata h5へのリンク(hdf5のExternalLinkという機能)も含まれており，master h5を開くことで，透過的に回折データを読めるようになっています．
実際のデータはdata h5の方に入っていますが，それを意識すること無くデータを読めます．master h5を与えるだけでデータ処理が行えるのは，この仕組みからです．

### 内部データの圧縮(filter)

HDF5は内部的にデータを圧縮することができるようになっています('filter'と呼ばれる機能)．EigerのデータはLZ4アルゴリズムまたはbitshuffle+LZ4 (bslz4)によって圧縮されるようになっており，通常はbslz4です(bslz4はlz4に比べ30-50%ほど小さくなります)．
master.h5は通常圧縮されていません(masterにはflatfieldやpixel maskなどそこそこ大きい情報が格納されています)が，BL32XUではbyteshuffle+gzipによって圧縮するようにしています．

データを読む際には，圧縮されていようがいまいが，同じように読むことができます（HDF5のライブラリが自動的に解凍処理を行います）．ただし非標準のFilter (bslz4も該当)の場合は，プラグインをインストールしなければ読めません．


## ソフトウェアの導入

まず以下のソフトウェアを導入します．

### HDF5 software
generate_XDS.INPは[HDF5 software](https://www.hdfgroup.org/HDF5/release/obtain5.html)に含まれるh5dumpを利用します．
各種パッケージマネージャ(Macの場合macportsなど)でhdf5を導入可能かと思います．

[hdfview](https://www.hdfgroup.org/products/java/release/download.html)も導入しておくと便利です(master h5の中身をツリー表示できるGUIです)．

### eiger2cbf (H5ToXds互換)
eiger2cbfはPILATUSでの標準フォーマットであるCBF形式に変換するためのツールです．
[Downloads - Mosflm](http://www.mrc-lmb.cam.ac.uk/harry/imosflm/ver721/downloads.html#Eiger2CBF)の下の方にリンク(Converter for Eiger files)があり，LinuxおよびMac版のバイナリが配布されています．

eiger2cbfは，XDSがh5を処理する際に必要とするH5ToXdsと互換性のあるプログラムです．
H5ToXdsは[Dectrisのサイト](https://www.dectris.com/EIGER_X_Features.html)の一番下からダウンロードできますが，Linux版のみでありMac版は配布されていません．
またH5ToXdsはCBFにヘッダ情報を付与しません．
これらの理由から，eiger2cbfをH5ToXdsという名前に変えて(またはH5ToXdsという名前のリンクを作って)使うことを推奨します．

eiger2cbfは，以下のようにmaster.h5を与えて使います．

* `eiger2cbf sample_master.h5` .. 格納されているフレーム数を出力
* `eiger2cbf sample_master.h5 10 sample_10.cbf` .. 10枚目(最初の番号は1)のフレームをsample_10.cbfとして保存
* `eiger2cbf sample_master.h5 1:100 sample` .. 1-100枚目をsample_??????.cbfとして保存


## イメージの表示
eiger2cbfを用いてcbfに変換すれば，adxvやその他cbfをサポートするビューアで表示できます．

hdf5形式のまま表示するには，以下の方法があります．

* [ALBULA](https://www.dectris.com/Albula_Overview.html)
* [Adxv](http://www.scripps.edu/tainer/arvai/adxv.html) (要bitshuffle plugin. 但し実験情報が読まれないため分解能が正しく表示されない)
* dials.image_viewer (DIALSプログラムに同梱)


## データ処理の方法

Eigerのデータを処理するには，以下の2通りの方法があります．

1. hdf5のまま処理する (XDS, DIALS)
2. cbfに変換して処理する (iMosflm, 他)

### XDS

[generate_XDS.INP](http://strucbio.biologie.uni-konstanz.de/xdswiki/index.php/Generate_XDS.INP) (rev. 0.63以降)を用いてXDS.INPを作成できます(要h5dump)．
generata\_XDS.INPには，直接master h5を与えてください．例えば以下のようにします．
```<commit_msg>Update eiger-ja.md<commit_after># Eigerデータフォーマットとデータ処理

本稿ではBL32XUにおけるEiger X 9Mに関して記述します．
本内容はEigerのfirmware更新などによって変更される可能性があります．

## Eiger HDF5について

hdf5 (.h5)はこれまでのイメージフォーマット(.img, .cbf)と違い，複数のイメージを1つのファイルにまとめて保存することができます．
HDF5はファイルシステムのような階層構造を持っており，それぞれの階層に任意のデータ（イメージデータや実験に関するパラメータなど）を持つことができます．

Eigerの出力するhdf5は，masterとdataの2種類からなります．例えばprefixをsampleとしてデータを収集すると，

* sample_master.h5 - 実験に関する情報（波長やビームセンターなど）の他，検出器の設定情報
* sample_data_??????.h5 - 回折イメージ

data h5には複数の回折イメージが含まれており，通常100枚ごとに1ファイル作られます．
つまり100枚以下ならばsample_data_000001.h5のみ，200枚以下ならそれに加えてsample_data_000002.h5も出力されます．

sample_master.h5にはdata h5へのリンク(hdf5のExternalLinkという機能)も含まれており，master h5を開くことで，透過的に回折データを読めるようになっています．
実際のデータはdata h5の方に入っていますが，それを意識すること無くデータを読めます．master h5を与えるだけでデータ処理が行えるのは，この仕組みからです．

### 内部データの圧縮(filter)

HDF5は内部的にデータを圧縮することができるようになっています('filter'と呼ばれる機能)．EigerのデータはLZ4アルゴリズムまたはbitshuffle+LZ4 (bslz4)によって圧縮されるようになっており，通常はbslz4です(bslz4はlz4に比べ30-50%ほど小さくなります)．
master.h5は通常圧縮されていません(masterにはflatfieldやpixel maskなどそこそこ大きい情報が格納されています)が，BL32XUではbyteshuffle+gzipによって圧縮するようにしています．

データを読む際には，圧縮されていようがいまいが，同じように読むことができます（HDF5のライブラリが自動的に解凍処理を行います）．ただし非標準のFilter (bslz4も該当)の場合は，プラグインをインストールしなければ読めません．


## ソフトウェアの導入

まず以下のソフトウェアを導入します．

### HDF5 software
generate_XDS.INPは[HDF5 software](https://www.hdfgroup.org/HDF5/release/obtain5.html)に含まれるh5dumpを利用します．
各種パッケージマネージャ(Macの場合macportsなど)でhdf5を導入可能かと思います．

[hdfview](https://www.hdfgroup.org/products/java/release/download.html)も導入しておくと便利です(master h5の中身をツリー表示できるGUIです)．

### eiger2cbf (H5ToXds互換)
eiger2cbfはPILATUSでの標準フォーマットであるCBF形式に変換するためのツールです．
[Downloads - Mosflm](http://www.mrc-lmb.cam.ac.uk/harry/imosflm/ver721/downloads.html#Eiger2CBF)の下の方にリンク(Converter for Eiger files)があり，LinuxおよびMac版のバイナリが配布されています．

eiger2cbfは，XDSがh5を処理する際に必要とするH5ToXdsと互換性のあるプログラムです．
H5ToXdsは[Dectrisのサイト](https://www.dectris.com/EIGER_X_Features.html)の一番下からダウンロードできますが，Linux版のみでありMac版は配布されていません．
またH5ToXdsはCBFにヘッダ情報を付与しません．
これらの理由から，eiger2cbfをH5ToXdsという名前に変えて(またはH5ToXdsという名前のリンクを作って)使うことを推奨します．

eiger2cbfは，以下のようにmaster.h5を与えて使います．

* `eiger2cbf sample_master.h5` .. 格納されているフレーム数を出力
* `eiger2cbf sample_master.h5 10 sample_10.cbf` .. 10枚目(最初の番号は1)のフレームをsample_10.cbfとして保存
* `eiger2cbf sample_master.h5 1:100 sample` .. 1-100枚目をsample_??????.cbfとして保存

### bitshuffle plugin (少し上級編)
必ずしも必須ではありませんが，[bitshuffle](https://github.com/kiyo-masui/bitshuffle) pluginを導入しておくとh5dumpやhdfview，あるいはadxv経由でbslz4圧縮されたhdf5も開けるようになります．
導入には開発環境が必要です(MacではXcode? [未検証])

```
(sudo) easy_install cython
(sudo) easy_install h5py
cd ~/tmp (任意の場所)
git clone https://github.com/kiyo-masui/bitshuffle.git
cd bitshuffle
(sudo) python setup.py install --h5plugin
```
デフォルトでは/usr/local/hdf5/lib/pluginにインストールされます．変更したい場合は`--h5plugin`の後に`--h5plugin-dir=`を付けてください．
インストールした場所に，環境変数`HDF5_PLUGIN_PATH`を設定する必要があります(bashなら`export HDF5_PLUGIN_PATH=`をcshなら`setenv HDF5_PLUGIN_PATH `を使って設定してください)


## イメージの表示
eiger2cbfを用いてcbfに変換すれば，adxvやその他cbfをサポートするビューアで表示できます．

hdf5形式のまま表示するには，以下の方法があります．

* [ALBULA](https://www.dectris.com/Albula_Overview.html)
* [Adxv](http://www.scripps.edu/tainer/arvai/adxv.html) (要bitshuffle plugin. 但し実験情報が読まれないため分解能が正しく表示されない)
* dials.image_viewer (DIALSプログラムに同梱)


## データ処理の方法

Eigerのデータを処理するには，以下の2通りの方法があります．

1. hdf5のまま処理する (XDS, DIALS)
2. cbfに変換して処理する (iMosflm, 他)

### XDS

[generate_XDS.INP](http://strucbio.biologie.uni-konstanz.de/xdswiki/index.php/Generate_XDS.INP) (rev. 0.63以降)を用いてXDS.INPを作成できます(要h5dump)．
generata\_XDS.INPには，直接master h5を与えてください．例えば以下のようにします．
```
{'fraction_non_alphanumeric': 0.1073170731707317, 'fraction_numerical': 0.03855232100708104, 'mean_word_length': 10.49367088607595, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 10, 'lorem ipsum': 0, 'www.': 12, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3986444', 'n_tokens_mistral': 4674, 'n_tokens_neox': 4330, 'n_words': 220}