# auto_scale

Automatic scaling escan and tscan data using ``A-method``

```{note} 
auto_scale assume each escan have same energy range and and each tscan
have same time range. Also it assumes energy unit of escan data is KeV but
assumes energy unit of tscan_energy_file is eV. Moreover energy unit of
scaled_escan is eV. However time unit for tscan data and escan time must be
same.
```

* usage: auto_scale    [-h] [-p PREFIX] [-ne NUM_OF_ESCAN] [-et ESCAN_TIME]
                       [-re REF_ESCAN_INDEX] [-nt NUM_OF_TSCAN]
                       [-te TSCAN_ENERGY] [-t0 TIME_ZEROS]
                       [-ti TSCAN_INDEX_TO_SCALE [TSCAN_INDEX_TO_SCALE ...]]
                       [-a PARM_A]
                       {-1,0,1,2,3,4}

* positional arguments:
  * {-1,0,1,2,3,4}        current stage, set stage to -1 get detailed
                         description

* optional arguments:
  * -h, --help            show this help message and exit
  * -p PREFIX, --prefix PREFIX
                        prefix for both escan and tscan file, it will read
                        prefix_escan_i.txt and prefix_tscan_j.txt
  * -ne NUM_OF_ESCAN, --num_of_escan NUM_OF_ESCAN
                         the number of escan files
  * -et ESCAN_TIME, --escan_time ESCAN_TIME
                         filename for escan delay times (unit: ps)
  * -re REF_ESCAN_INDEX, --ref_escan_index REF_ESCAN_INDEX
                         index of escan used to the reference for scaling
  * -nt NUM_OF_TSCAN, --num_of_tscan NUM_OF_TSCAN
                         the number of tscan files
  * -te TSCAN_ENERGY, --tscan_energy TSCAN_ENERGY
                         filename for tscan energy (unit: eV)
  * -t0 TIME_ZEROS, --time_zeros TIME_ZEROS
                         filename for time zero of each tscan (unit: ps)
  * -ti TSCAN_INDEX_TO_SCALE [TSCAN_INDEX_TO_SCALE ...], --tscan_index_to_scale TSCAN_INDEX_TO_SCALE [TSCAN_INDEX_TO_SCALE ...]
                         tscan index to scale, use blank separation for
                         multiple arguments
  * -a PARM_A, --parm_A PARM_A
                         filename for the parameter A obtained from fit_static


* Stage discription

* stage -1: description
  It prints the description about each stages and aborts.
  
  ```{note} 
  For every stage except -1, requires 
  prefix, num_of_escan, escan_time, num_of_tscan,
  tscan_energy, time_zeros
  ```

* stage 0: init scaling

    ```{admonition} Additionally requires
    ref_escan_index, tscan_index_to_scale, parm_A
	```
	
    the program read escan_data from
    prefix_escan_1.txt,...,prefix_num_escan.txt
    and tscan_data from
    prefix_tscan_1.txt,...,prefix_tscan_num_tscan.txt
    Also, it read file for parameter A generated by
    fit static.
    Then it fits scaling of escan_data and 
    tscan_i_1,...,tscan_i_N to escan_e_ref.
    Now it generates 
    prefix_escan_scaled.txt (energy unit: eV)
    prefix_escan_eps_scaled.txt
    prefix_tscan_scaled.txt 
    prefix_tscan_eps_scaled.txt
    prefix_A_ref.txt
    If you do not include tscan j for scaling.
    You can see (j+1) th column of prefix_tscan_scaled.txt and
    j th column of tscan_scaled_eps.txt are filled with zeros.
    

* stage 1: Correction

    ```{admonition} Additionally requires
    ref_escan_index, tscan_index_to_scale
	```

    ```{note} 
    ref_escan_index and tscan_index_to_scale must be set to
    same as stage 0
	```
    
    the program read scaled escan data and tscan data from
    prefix_escan_scaled.txt, prefix_escan_eps_scaled.txt,
    prefix_tscan_scaled.txt, prefix_tscan_eps_scaled.txt,
    and then it corrects scaling of escan using tscan_i_1
    It regenerates prefix_escan_scaled.txt and 
    prefix_escan_eps_scaled.txt
    

* stage 2: further scaling

    ```{admonition} Additionally requires
    tscan_index_to_scale
	```
	
	```{note}
	in this stage do not need to give the file name for 
    parameter A.
	```
	
    the program read scaled escan data and tscan data from
    prefix_escan_scaled.txt, prefix_escan_eps_scaled.txt,
    prefix_tscan_scaled.txt, prefix_tscan_eps_scaled.txt,
    and then it fits scaling of tscan_i'_1,...,tscan_i'_N'
    to escan_e_ref'. 
    (Prime means i_1,...,i_N and e_ref values are different
     from stage 0)
    Then it regenerates all prefix_*.txt except prefix_A_ref.txt
    
 
    
* stage 3: sanity check

    In this stage, the program assume, every tscan data are
    scaled to escan data. For sanity check, it gives
    a graph for you.
    

* stage 4: Scaling with another tscan data set
    Scale Another set of tscan data using already scaled 
    escan data

    ```{admonition} Additionally requires
    tscan_index_to_scale
	```
    
    ```{Note}
	Before proceed stage 4, you should move 
    prefix_tscan_scaled.txt, prefix_tscan_eps_scaled.txt
    and prefix_tscan_xxx.txt to some backup folder and
    rename your another tscan data set to prefix_tscan_xxx.txt
    Also you should give time_zero and energy for such tscan.
	```

    In this stage, it reads scaled escan data and eps from
    prefix_escan_scaled.txt and prefix_escan_eps_scaled.txt
    Then it reads unscaled tscan data and eps from
    prefix_tscan_*.txt
    Next, it scales tscan datas just like stage 1.
    After stage4 finished you should go to stage 2 and stage 3.
	
* A-method

    When we measure each escan, we measure static spectrum (flu_off) to
    get difference spectrum (flu_on - flu_off)
    Since we have theortical static spectrum, we can fit theortical
    spectrum with measured static spectrum using following model.

    ```{math} y = A \cdot {conv}({spec}_{thy}, {voigt}({fwhm}_G, {fwhm}_L, {peakshift})) + {baseline}
	---
	label: model
	---
	```

    Also, using ``fit_static``, you can simultaneous fitting each
    escan. During fitting process, it assume fwhm_G, fwhm_L, peak_shift
    are same in each escan, only scaling factor A and base_line are
    different. Parameter base_line reflects environmental effects,
    so pure static signal(w/o environmental effects) is
	
    ```{math} A \cdot {conv}({spec}_{thy}, {voigt}({fwhm}_G, {fwhm}_L, {peakshift}))
	---
	label: model2
	---
	```
	
    Each escan has same fwhm_G, fwhm_L and peak_shift value, so
    Parameter A (scaling parameter) could tell relative scaling of each escan.
    In other words, we can fit scaling of escan data just multipling
    A_ref/A to each escan.
	However, due to inconsistence of laser overlap between energy scans, one good time delay scan is needed to correct the scaling of energy scans.
