# localPDF チュートリアル

## 1. 目的

Web ブラウザでファイルを選択し、ボタンをクリックして PDF
を計算する代わりに、ローカル Python から同じ計算コアを API で実行する。

基本形は、

``` text
config 読み込み
    ↓
実験データ読み込み
    ↓
必要なら background 読み込み
    ↓
run_all()
    ↓
run_bft()
    ↓
結果取得 / 保存 / 表示
```

である。

------------------------------------------------------------------------

## 2. 最小例

``` python
from localPDF import Config
from localPDF import LocalPDF

config = Config("SiO2_LabAgSource.json")
pdf = LocalPDF(config=config)

pdf.load_xy("SiO2_20h_LabAgSource.dat")

pdf.run_all()
pdf.run_bft()

q, sq = pdf.get_sq()
r, gr = pdf.get_gr_lorch()

pdf.save_sq("sq.dat")
pdf.save_gr_lorch("gr_lorch.dat")
```

これが最も基本的な利用方法である。

------------------------------------------------------------------------

## 3. background がある場合

``` python
from localPDF import Config
from localPDF import LocalPDF

config = Config("config.json")
pdf = LocalPDF(config=config)

pdf.load_xy("sample.dat")
pdf.load_bg_xy("background.dat", factor=1.0)

pdf.run_all()
pdf.run_bft()

pdf.save_sq("sq.dat")
pdf.save_gr_lorch("gr_lorch.dat")
```

------------------------------------------------------------------------

## 4. 結果を Python 上で使う

``` python
q_iq, iq = pdf.get_iq()
q_sq, sq = pdf.get_sq()

r_gr, gr = pdf.get_gr()
r_lorch, gr_lorch = pdf.get_gr_lorch()
```

返り値は NumPy array として後続処理に使用できる。

------------------------------------------------------------------------

## 5. 補正過程を確認する

計算結果だけでなく、実験強度がどのように処理されたかも API
から確認できる。

``` python
tt, raw = pdf.get_intensity_raw()
tt, bg = pdf.get_intensity_bg()
tt, bg_scaled = pdf.get_intensity_bg_scaled()
tt, subtracted = pdf.get_intensity_subtracted()

q, corrected = pdf.get_intensity_corrected()
q, normalized = pdf.get_intensity_corrected_normalized()

q, f2, compton, total = pdf.get_formfactor_components()
```

これは Web 版のグラフで確認していた中間状態を Python
側で直接取得したい場合に使う。

------------------------------------------------------------------------

## 6. Bokeh で表示する

``` python
from localPDF import Config
from localPDF import LocalPDF
from localPDF import LocalPDFPlot

config = Config("SiO2_LabAgSource.json")
pdf = LocalPDF(config=config)

pdf.load_xy("SiO2_20h_LabAgSource.dat")
pdf.run_all()
pdf.run_bft()

view = LocalPDFPlot(local_pdf=pdf)
view.view_all()
```

現状の `view_sq()`
は曲線描画部分がコメントアウトされているため、`view_all()` 内の
S(Q)/i(Q) panel には曲線が表示されない。

------------------------------------------------------------------------

## 7. example/main_local.py の読み方

添付された example は次の順序になっている。

``` python
config = LocalPDFConfig(config_json)
pdf = LocalPDF(config=config)
view = LocalPDFPlot(local_pdf=pdf)

pdf.load_xy(xy_file)

if bg_file is not None:
    pdf.load_bg_xy(bg_file, factor=bg_factor)

pdf.run_all()
pdf.run_bft()

pdf.save_iq("local_iq.dat")
pdf.save_sq("local_sq.dat")
pdf.save_gr("local_gr.dat")
pdf.save_gr_lorch("local_gr_lorch.dat")

view.view_all()
```

この example が localPDF 本体の標準利用例と考えてよい。

------------------------------------------------------------------------

## 8. まず覚える API

最初は次の8個程度で十分である。

``` text
Config(...)
LocalPDF(...)

load_xy(...)
load_bg_xy(...)

run_all()
run_bft()

get_sq()
get_gr_lorch()
```

ファイル出力するなら、

``` text
save_iq()
save_sq()
save_gr()
save_gr_lorch()
```

を追加する。

------------------------------------------------------------------------

## 9. Web 版との感覚的な対応

``` text
Web:
ファイル選択
→ config 選択
→ S(Q) 計算ボタン
→ G(r) 計算ボタン
→ download

Local:
Config(...)
→ load_xy(...)
→ run_all()
→ run_bft()
→ save_*()
```

localPDF を理解するときは、「Web 版のクリック操作を Python API
に置き換えたもの」と考えるのが基本である。