aov.f90 Source File


Contents

Source Code


Source Code

Program main
!
!! Purpose:<br>
!!-------------------------------------------------------------------------<br>
!!`Aov` is a tool for period analysis of irregularly sampled time series,
!!such as stellar and planetary transit light curves. It relies on state-of-art
!!statistically poweful, robust and fast algorithms implemented in
!!my `AovPer` package, partly based on my original research and
!!publications. All routines come in two flavours, with/without weights.<br>
!!References:<br>
!!--------------------------------------------------------------------------<br>
!!The methods used are based on my 3 papers, listed in the
!!corresponding routine headers:<br>
!!aov-phase binning aov (Schwarzenberg-Czerny, A., 1989, MNRAS 241, 153);<br>
!!aovmh-multi-harmonic aov (Schwarzenberg-Czerny, A., 1996, ApJ(Lett) 460L, 107);<br>
!!aovtr-transit/eclipse aov (Schwarzenberg-Czerny, A. & Beaulieu, J.-Ph.,
!!2006, MNRAS 365, 165);<br>
!!These papers and my software are also available from my web page
!!`http://www.camk.edu.pl/~alex/`<br>
!!Please cite this papers accordingly in publications using the current package.<br>
!!Input:<br>
!!--------------------------------------------------------------------------<br>
!!Observations - one ASCII file per star, 2 or 3 columns in order: time,value,error<br>
!!`aov.par` - file containing default values of program parameters<br>
!!The file `aov.par` must exist, at least with dummy content `&par /`.
!!Aov command line: may reset parameters from aov.par<br>
!!Star name is either in STAR parameter or input from file named in STRLST.
!!File of star observations is named DIR+STAR+EXT, where + marks concatenation.<br>
!!Running `./aov STAR=SIMUL` generates sample input (see Usage).
!!Compilation:<br>
!!---------------------------------------------------------------------------<br>
!!AOV is compiled simply by:<br>
!!`gfortran -o aov aovconst.f90 aovsub.f90 aovprms.f90 aovobs.f90 aovspec.f90 aovper.f90 aov.f90`<br>
!!
!!For debugging/testing use:<br>
!!`gfortran -g -Og -fimplicit-none -Wall -Wline-truncation -Wcharacter-truncation -Wsurprising -Waliasing -Wimplicit-interface -Wunu
!!Usage:<br>
!!-------------------------------------------------------------------------<br>
!!Running `./aov` generates sample input parameter file `aov.par` and
!!data file `SIMUL1.dat`. Then command `./aov STAR=SIMUL1` executes them in the
!!ordinary way as if provided by the user.<br>
!!Program Parameters:
!!---------------------------------------------------------------------<br>
!!Obligatory Parameters (listed either in aov.par or command line):
!!`  character*(20)    :: STAR=""!  star name or ...   `<br>
!!`  character*(20)    :: STRLST=""! name of file of star names  `<br>
!!<br>
!!Optional command parameters of main interest and their default values`<br>
!!`  real(TIME)        :: FR0=0. !  lower frequency`<br>
!!`  real(TIME)        :: FRU=4. !  upper frequency`<br>
!!`  real(TIME)        :: FRS=0. !  frequency step (0.-optimum sampling)`<br>
!!`                       !  warning: undersampling risk for FRS>0. `<br>
!!`  integer           :: NPAR=5  ! number of model parameters`<br>
!!`  integer           :: METHOD=AOVMH ! select from`<br>
!!`                          ! AOV,AOVTR,AOVMH,AOVW,AOVTRW,AOVMHW`<br>
!!`                          ! Those ending 'W' process weights.`<br>
!!`  integer           :: NCOV=2 ! number of bin coverages`<br>
!!`  character*(20)    :: DIR=''     ! Light curve file name prefix`<br>
!!`  character*(20)    :: EXT='.dat' ! Light curve file name extension`<br>
!!Full list is in header of `mprms` module.<br>
!
!!Input parameter NPAR sets number of phase bins NPAR phase bins or
!!NPAR/2 Fourier harmonics.
!!I was using 3<=NPAR<=9 and I do not recommend exceeding these limits
!!in general period surveys. For transient search use much higher values
!!of NPAR, so that transit width ~1/NPAR. In theory, the CPU time
!!is proportional to ~NPAR, but as NPAR increases the spectral
!!resolution also increases, so it is advisable to decrease
!!the frequency step by 1/NPAR (done automatically by the code),
!!which causes CPU time scaling like ~NPAR^2. There
!!are possible additional CPU savings, but these are not
!!worth worrying about at this stage. NPAR=5 worked well
!!for near sinusoidal oscillations.<br>
!!FSAMPL needs to be set =>3. The FSAMPL=4 choice means 4 frequencies covering
!!a spectral line. This is in my opinion close to optimal as the code fits
!!line profile to find peak frequency. If speed is no problem one can use e.g. FSAMPL=7.<br>
!!The fastest are `AOV` or `AOVW`, depending on `ERRIN`, yet they
!!suffer from an artificial noise/residuals due to sharp steps between phase bins.
!!`AMH` and `AMHW` employ a smooth Fourier model hence are statistically better, yet
!!about 10 times slower. All four algorithms complexity scales proportional
!!to number of observations, frequencies and model parameters.<br>
!
!!Methods:<br>
!!------------------------------------------------------------------<br>
!!The algorithms employ either bins and sub-bins or projection onto
!!ortogonal polynomials yielding as fast implementation as possible when
!!irregular sampling with large gaps make FFT impractical.
!!Use of orthogonal functions, either phase binning or
!!trigonometric polynomials results in statistically near optimal
!!behaviour in that cross-talk/correlation between model elements is minimal.
!!Because of that the algorithms remain fairly robust against outliers.
!!More importantly use of orthogonal functions permits
!!application of the classical Fisher AnoVa statistics to
!!evaluate frequency spectrum and reliability of any detected periods.
!!Depending on `SPTYPE` the spectrum obeys either
!!Fisher-Snedecor F or beta probability distributions.<br>
!
!!Experience:<br>
!!-----------------------------------------------------------------<br>
!!The original periodogram/frequency spectrum routines were used on
!!over 10^5 stars, as part of f95 TATRY package in OGLE and LCVSS
!!mass photometry surveys and in EROS c package
!!All Star Searcher, among others used to analyse 318 light curves
!!of suspected variable stars in the field M31C. For the Cepheids
!!and the eclipsing binaries. Tests against periods set by manual
!!inspection of periodograms and light curves were performed
!!on 25 000 light curves from ASAS South. The comparision involved the most
!!significant periods only. The periods always
!!agreed or were 2om or 3om or om/2 sub-/harmonics of the published frequency om.
!!For Cepheids NPAR=5 worked well. For eclipsing binaries with proximity
!!effects (e.g. W UMA) or for sinusoidal variables NPAR=3 was better,
!!however 2om ambiguities occured.<br>
!!Trials demonstrated that the aov detection criterion
!!used in the present code works better than the Laefler-Kinman,
!!PDM and Stetson criteria for eclipsing or pulsating variable stars.
!!However, picking right NPAR for your problem requires some
!!trial runs before decision on the final NPAR. For some applications,
!!such as transit search it sis recommended to perform several runs,
!!e.g. for NPAR=15, 30 and 60, to scan a range of transit widths.<br>
!
!! History:<br>
!!-------------------------------------------------------------------<br>
!! 1989 - development of AOV phase binning routines;<br>
!! 1996 - AOVMH Fourier series routines added;<br>
!! 1999-2002 - all AOV routines expanded for use as module in TATRY code;<br>
!! 2003 - porting of AOV routines into C for use in EROS and DIRECT projects.
!! This resulted in major upgrade/factor several sppeding of the algorithm AOV by
!! introduction of subbins;<br>
!! 2004 - new transient search algorithm fitting top-hat/box function;<br>
!! 2018 - subsstantial revision: main changes were in array declarations and
!!normalization of observations. All fixed lengh arrays are replaced with the
!!dynamic ones. In periodogram subroutines observations are now copied into local
!!arrays when needed. Input observations are left intact. Small inconsistencies
!!were removed and AOV and AOVTR routines were combined into one AOV routine
!!performing both ordinary phase folding and binning or transit search.
!!F95 and C packages became compatible to a high degree. Auto documentation using `ford`.
!!Phases are now calculated in a uniform way using:<br>
!!`dph=fr*t[i]`<br>
!!`dph-=floor(dph)`<br>
!!Tests on AMD PC and gcc demonstrated that `-=floor` is faster than `fmod`.<br>
!! 2020 - improved handling of command line string parameters, introduction of
!! optional list of star names.<br>
!!
!!Copyrights:<br>
!!The whole package is subject to copyrights by its author,
!!(C) A. Schwarzenberg-Czerny 1089-2020,  alex@camk.edu.pl
!!It is free to use and copy, yet distribution of modiffications or fragments
!!is forbidden. It is unsuitable for application carrying risk of damages.
!!To acknowledge its use, pleas cite papers listed in the References section.<br>
!
!
      Use aovconst
      Use mprms
      Use aovper
      Use aovsub
      Use aovobs
      Use aovspec
!
      Implicit None
!
! Variables
      Logical :: simul, list
      Real (SP) :: dfm, thm, qual
      Integer :: ib, j, metcnt
!
!
      Real (TIME), Allocatable :: f (:), fb (:)
      Type (SPEC_T) :: spec
      Type (OBS_T) :: obs
!
      io = prog_args ('aov')
      If (io /= 0) Then
         Print '(A)', 'Usage:', &
         './aov to generate sample .par and .dat files', &
         './aov STAR=SIMUL1 to run those .par and .dat files', &
         './aov  [[option=value]...] for general use', &
         'where option=FR0|FRU|FRS|NH2|METHOD|SPTYPE|NCOV|DIR|EXT|STAR', &
         'METHOD=aov|atr|amh|psp|aovw|atrw|amhw|pspw', &
         'SPTYPE=RAW|AOV|MODEL|RESID', &
         'EPOCH=MIN|AVE|MED|number', &
         'Option names are not case sensitive', &
         'Values must not contain ''='' sign', &
         'String values are case sensitive and bracket "" is needed', &
         'when they contain SPACE or special characters', &
         'File aov.par has f90 namelist format', &
         'Command line parameter values have precedence over aov.par', &
         'If STRLST=fname, star names are input from file fname'
         Stop
      End If
      NCOV = Max (1, NCOV)
      FRU = Max (FR0, FRU)
      NPAR = Max (2, NPAR)
      NBEST = Max (1, NBEST)
      METHOD = toupper (METHOD)
      SPTYPE = toupper (SPTYPE)
      EPOCH = toupper (EPOCH)
      Allocate (fb(NBEST))
!
      Print '(A)',"", &
      '  AOV/f90 Periodogram Routines, version ' // VER, &
      '  by (C) Alex Schwarzenberg-Czerny alex@camk.edu.pl',""
      Call print_args (6)
      Print *
!
      Open (3, File=trim(STRLST), Status='old', IoStat=io)
      list = (io == 0)
      If ( .Not. list .And. len_trim(STRLST) > 0) Then
         Print '(A)', 'Failed to open STRLST=' // trim (STRLST), &
         'Instead Tries STAR=' // trim (STAR)
      End If
! Get data ...
      Do
         If (list) Then
            Do
               Read (3, '(A)', IoStat=io) STAR
               If (io <= 0) Exit
            End Do
            If (io < 0) Then
               Close (3)
               Exit
            End If
         End If
!
         simul = (trim(STAR) == 'SIMUL')
         If (simul) Then
! ...from simulation
            obs = test_obs (100)! also outputs simulated data to SIMUL1.dat)
            STAR = "SIMUL1"
            Open (4, File='aov.par', Status='unknown')
            Call print_args (4)
            Close (4)
         Else
! ... or from a file. NOTE: appends file prefix/extension, if any.
            msg = trim (DIR) // trim (STAR) // trim (EXT)
            obs = get_obs (trim(msg))
            If (obs%no <= 0) Then
               Print *, '***No valid data for STAR=' // trim (STAR)
               If (list) Cycle
               Exit
            End If
         End If
! Process data/observations
         If (obs%no <= NPAR) Then
            Print *, '***Too few observations, abandoning ' // trim(STAR)
         Else
            If (minval(obs%t(2:)-obs%t(:obs%no-1)) < 0.) &
               Print *, '***Warning: time not sorted in ' // trim (STAR)
            Print *, 'Are errors given? ', obs%weights
!
            metcnt = 1
! Set up frequency grid and get periodogram
            spec = fgrid (obs%t, NPAR/2, FR0, FRU, FRS)
            Allocate (f(spec%nfr), Stat=io)
            If (io /= 0) Then
               Print *, "Failed memory allocation for f"
               Cycle
            End If
            Forall (j=1:spec%nfr) f (j) = spec%FRS * (j-1) + spec%FR0
            If ((obs%tmax-obs%tmin)*spec%FRS > 0.3 .And. VERBOSE) &
               Print *, " AOV: warning: undersampling in frequency"
! do imet=1,8
!    method=trim(meths(imet))
            If (metcnt == 1) &
               Print '(a,2g15.8,i8)', 'grid: ', spec%FR0, spec%FRS, spec%nfr
!
! Calculate periodogramme
            io = aovdrv (METHOD, SPTYPE, obs%t, obs%v, obs%w, NPAR, &
               NCOV, spec)
! Write result periodogram into file
            Open (4, File=trim(STAR)//trim(METHOD)//'.res', Status='unknown', &
               IoStat=io)
            If (io /= 0) Then
               Print *, 'Failed to open ' // trim (STAR) // '.res'
               Exit
            End If
            Write (4, '(g15.8,f12.8)') (f(j), Log10(spec%th(j)), j=1, &
           & spec%nfr)
            Close (4)
! Find & remove peaks
            Do ib = 1, NBEST
               Call peakrm (obs%tmax-obs%tmin, spec, fb(ib), thm, dfm)
               If (ib == 1) qual = Log10 (thm)
            End Do
! Print summary
            If (metcnt == 1) &
               Print *, "meth star  no_obs quality best_frequencies"
            Print '(1x,a4,1x,a6,i5,f8.3,10f10.5)', METHOD, trim (STAR), &
               obs%no, qual, (fb(ib), ib=1, NBEST)
            metcnt = metcnt + 1
! end do
            Deallocate (f)
            Call clr_spec (spec)
         End If
         Call clr_obs (obs)
         If ( .Not. list) Exit
      End Do
!
      Print *, 'AOV finished'
      Print *
!
End Program main
!
!
!
!
!
!
!