Readme.md~

# Agatha
## Disentangling periodic signals from correlated noise in a periodogram framework

### online web app 

The shiny app of Agatha is available [here](https://phillippro.shinyapps.io/Agatha/) or [here](http://www.agatha.herts.ac.uk).
If you use Agatha in your work, please cite **"Feng F., Tuomi M., Jones H. R. A., 2017, Agatha: disentangle periodic signals from correlated noise in a periodogram framework, MNRAS, 470, 4794"** or use the following bibtex.
```
@ARTICLE{2017MNRAS.470.4794F,
   author = {{Feng}, F. and {Tuomi}, M. and {Jones}, H.~R.~A.},
    title = "{Agatha: disentangling periodic signals from correlated noise in a periodogram framework}",
  journal = {\mnras},
archivePrefix = "arXiv",
   eprint = {1705.03089},
 primaryClass = "astro-ph.EP",
 keywords = {methods: data analysis, methods: statistical, techniques: radial velocities, stars: individual: HD 177565, HD 41248, CoRoT-7},
     year = 2017,
    month = oct,
   volume = 470,
    pages = {4794-4814},
      doi = {10.1093/mnras/stx1126},
   adsurl = {http://adsabs.harvard.edu/abs/2017MNRAS.470.4794F},
  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
```

### use the app locally
If you want to use the app locally, you download the whole GitHub repository to a local directory. Then you should install R and R packages. The user should install packages 'shiny', 'magicaxis', 'minpack.lm' and 'fields'. For example,
```
install.packages(c('shiny','magicaxis','minpack.lm','fields'))
```
. To run the app locally, the user should go to the directory where the ui.R and server.R files are, and type "R" to enter the R console, and then run the app 
using the following commands:
```
library(shiny)
runApp()
```
Then the app will appear in your browser for your usage.  

### Details about periodoframe.R

The functions used to calculate the BFP and MLP are put in the periodoframe.R file. The user can use/adapt these functions for different applications. 
For example, the BFP can be made using the following function:
```
BFP(t,y,dy,Nma=Nma,Indices=Indices,ofac=ofac,opt.type=opt.type,model.type=model.type,fmax=fmax)
```
where t, y and dy are the times, y values and the corresponding errors. Nma is the number of moving average components. Indices are a matrix of 
noise proxies. Inds is a vector of column numbers of indices (or noise proxies) in the "Indices" matrix. 
For example, "Inds=1:4" means linearly including the proxies from column 1 to column 4 of "Indices" in the noise model.
"ofac" is the over sampling factor, and opt.type can be "nl" or "sl", and is the method used to optimize parameters.
"sl" is suggested because it is more efficient and is as reliable as "nl". "model.type" is a parameter to specify whether to compare models. If model.type='auto', model comparison is done using the BFP to select the optimal noise model. If model.type='man', BFP will use Nma and Inds manually provided by the user. "fmax" is the maximum frequency for frequency sampling.

The main output of the BFP function is the logarithmic Bayes factor (logBF) for a sample of periods (P). Then the user can make a simple BFP using 
```
plot(BFP$P,BFP$logBF,log='x',type='l')
```
. The functions for calculating the marginalized likelihood periodogram (MLP) and moving periodogram (MP) are also in periodoframe.R. 
The functions used to calculate the Lomb-Scargle (LS), generalized LS (GLS), Bayesian GLS (BGLS), 
GLS with floating trend (GLST) periodograms are put into periodogrames.R. 

### data

The test data is put in the "data/" directory. And the results are put in the "results/" directory. In the "data/" directory, "...calibration.dat" files are calibration data, "..._TERRA_HARPS.dat" are TERRA-reduced HARPS data including JD-2400000, RV, eRV, BIS, FWHM and S-index from left to right columns. "..._TERRA_XAP_dRVs.dat" are differential RVs derived from XAP aperture data sets. In each file, the first column is the time, and the other columns are XAPj-i where j={2,3,...,X} and i=j-1.  

### example code

The "make_periodoframe.R" file is an example code used to compare different periodograms. The "MP.R" file is to calculate the moving periodogram. Both files call "prepare_data.R" which is to set parameters and to load the data. The user is refered to the upcoming paper titled "Agatha: Disentangling periodic singals from correlated noise in a periodogram framework" for more details.  

To quickly produce a periodogram, you just start R console by typing "R", and then run the following command in the R console:
```
source('make_periodogram.R')
```
or run the following command in the terminal directly: 
```
Rscript make_periodogram.R
```
If the user wants to change the parameters of periodograms, he/she can change them in the file "prepare_data.R", and then run make_periodogram.R again. 

The usage of MP.R is similar to make_periodogram.R. 

Comments and questions are welcome and can be sent to fengfabo@gmail.com .