# auto_scale

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

```{note} 
auto_scale assume each escan have same energy range and each tscan
have same time range. Also it assumes energy unit of escan data is KeV but
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.

\begin{equation*} 
	y = A \cdot {conv}({spec}_{thy}, {voigt}({fwhm}_G, {fwhm}_L, {peakshift})) + {baseline}
\end{equation*}

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
	
\begin{equation*}
A \cdot {conv}({spec}_{thy}, {voigt}({fwhm}_G, {fwhm}_L, {peakshift}))
\end{equation*}
	
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.
