Ecallisto idl routines

Last modified: Thu Mar 16 13:07:05 2023.


List of Routines


Routine Descriptions

ECALBASE - BASE DIRECTORY FOR ECAL DATA FILES

[Next Routine] [List of Routines]
NAME:
ecalbase - base directory for ecal data files

SYNTAX: bdir=ecalbase()

ARGS:
           html documentation.

DESCRIPTION:
   Return the ao base directory where the e callisto fits files are saved.
Daily files are bdir/yymmdd/...

(See /pkg/rsi/local/libao/phil/ecal/ecalbase.pro)


ECALIMGDAY - CREATE DYNAMIC SPECTRA IMAGES FOR A DAYS WORTH OF DATA.

[Previous Routine] [Next Routine] [List of Routines]
NAME:
ecalimgday - create dynamic spectra images for a days worth of data.
SYNTAX: istat=ecalimgday(ecalI,odir)
ARGS:
ecalI: {}  struct with for a day. You input it  with ecalinpday()
odir : string    output directory to write jpeg files.
RETURNS:
istat:  int  >= 0 number of jpeg files written.
             <0  error with message output.
DESCRIPTION:
	Callistio data has spectra sampled at a .25 second interval. You can input a days worth
of data with istat=ecalinpday(yymmdd,ecalI). Data is normally blocked in 15 minute sections (3600 .26 second 
spectra). This routine will make dynamic spectra for each 15 minute set  and write the jpeg files to odir. 
The jpeg file naming convention is: yymmdd_hhmm.jpg  where hhmm is the hour,min for the start of the 15 minute block.
 	The jpeg files contain:
 - an upper frame (polA)
 - and a lower frame (polB)
 - the horizontal axis is time with tickmarks labeled as: hh:mm:ss
 - the vertical scale is freq (MHz). The routine excludes the bottom 8 channels that have no data.

   When computing the dynamic spectra:
 - flatten the image using the median bandpass for the 15 minutes.
 - scale the data to +/- 5 sigma. Sigma is computed across the entire 15 minutes of data 
    using a robust estimator (excludes outliers). 
    Callisto uses a logarithmic sampler. I have not converted it back to linear prior to 
    computing the sigmas and displaying the data (maybe someday..:).

Notes:
	- The polA and polB data are written to separate fits file by the callisto system. 
     The time axis of the polA,B data will correspond to the values in the fits files 
     (they can be different depending when the acquistions started).

(See /pkg/rsi/local/libao/phil/ecal/ecalimgday.pro)


ECALINPDAY - INPUT THE ECALLISTO FITS FILES FOR A DAY.

[Previous Routine] [Next Routine] [List of Routines]
NAME:
ecalinpday - input the ecallisto fits files for a day.
SYNTAX: nfiles=ecalinpday(yymmdd,ecalI,verb=verb)
ARGS:
yymmdd: long   day to input
verb  :        is set output some debug info
RETURNS:
nfiles :  long  > 0 number of fits files found for polA or B
                0   no files available
                -1  i/o error with message output.
3
ecalI:   {}         struct holding the data

DESCRIPTION:
	Input the callisto data for one day. Normal operation has the callisto data uploaded to
the callistion site: http://soleil80.cs.technik.fhnw.ch/solarradio/data/2002-20yy_Callisto
daily. A crontab then downloads the fits files from this site. This routine will
search for the downloaded fits files for the requested date. This routine does not do the
download. If the download did not occur (or failed) then this routine will routine 0 files.

 A days set of data will normally contain 44 sets.
 Each set is has 15 minutes of pola,b data. (on disc there will be 88 files
 since pola,b are in separte fits files.
 Each set has 3600 spectra of 200 channels.  the spectra are separated by .25 seconds

 the ecalI struct holding a days set of data contains
 help,ecalI,/st
** Structure <21771c8>, 8 tags, length=254127544, data length=254127362, refs=1:
   YYMMDD    LONG            211201   yymmdd utc for data
   NSETS     LONG                44   number of 15 minute datasets input
   TMINC     FLOAT          0.250000  time step between spectra
   FREQDIM   INT            200       number of freq dimensions
   TMDIM     LONG           3600      number of time steps 1 data set (15min tot) 
   FREQAR    FLOAT     Array[200]     freq for each of the 200 channels
   TMOFFSETS FLOAT     Array[3600]    time offset (from start of set) for time stamps
    SPCI     STRUCT    ->  Array[44] the 44 sets of 15 minute data

 the ecali.spcI structs hold:

 help,ecalI.spci,/st
** Structure <216fa58>, 10 tags, length=5775280, data length=5775276, refs=2:
   DATEOBS   STRING    '2021'
   TIMEOBS   STRING    '10:30:00.702'
   DATEEND   STRING    '2021'
   TIMEEND   STRING    '10:45:00'
   PWMVAL    LONG       80
   STARTSEC  fltarr(2)  instead of crval1, use timeObs since it has a fraction. 27jan22
   NTM       LONG       3600    ; number of time samples valid
   SPC       FLOAT     Array[200, 3600, 2] ; frq,time,pols

 Notes:
  - i'm storing the spectra as (freq,tim). the fits file has (tim,freq)
  - the freqar in decreasing.. freqAr reflects that.

  - where are the fits files:
          hhjan22:  base dir for fits files: /share/phildat/callisto/
          bdir=ecalbase()  will give the current value

  the fits file contains
  hdu 0 - primary header and byte array of ata
  hdu 1 - extension with 3600 timestamps, and 200 freq points
          i checked and the freq are constant for a day
          some files may have viewer time points.
          I load -1 into the spectra that are missing.
 220127 - Trying to sync polA,polB
          - crval1 for both a,B fits files
            but time-obs is different. Looking at the data, you need to use
            time_obs since that determines when data taken, not crval1.

(See /pkg/rsi/local/libao/phil/ecal/ecalinpday.pro)


ECALTPDAY - COMPUTE TOTAL FOR EACH SAMPLE OF DATE.

[Previous Routine] [List of Routines]
NAME:
ecaltpday - compute total for each sample of date.
SYNTAX: istat=ecaltpday(yymmdd,tpI,useEcalI=useEcalI,ecalI=ecalI,freqrange=freqrange,verb=verb)
ARGS:
yymmdd: long  date to input
KEYWORDS:
useecalI:     if set then use value passed in via ecalI instead of reloading the files
freqrange: fltarr(2) : if supplied then limit toal power to this freq range.
verb          if set then ecalinpday will give verbose output when reading file. 
RETURNS:
 istat:   int  1 ok, -1 error
 tpI  : {}     struct holding total power info
ecalI : {}     if provided and useCalI not set, then return the spectra data that we input.

DESCRIPTION:
 	Input a days worth of spectra (yymmdd) and compute the total power for each time sample. If the useEcali
keyword is set and keyword ecalI is supplied, then the total power will be computed using the data in ecalI.
If useEcalI is not set and ecalI keyword is included, then the input spectra will also  be returned in ecalI.

	By default the total power is computed over the entire freq range (although the lowest 8 freq chan are skipped since 
they have no data). The freqRange= keyword can be use to limit the frequency range for the total power. freqrange[0]
is the loweset freq, and freqrange[1] is the upper frequency (in Mhz) to use.
  The data is returned in the tpI structure:
help,tpI,/st
** Structure <15c1798>, 8 tags, length=3800808, data length=3800800, refs=1:
 YYMMDD   LONG            220131   ; date for data 
 FRQRANGE DOUBLE    Array[2]       ; min,max freq used for tp computation (MHz)
 NSMPA    LONG            158377   ; # of samples of tpA
 HRA      DOUBLE    Array[158377]  ; time stamps for tpA (hr of day UTC)
 TPA      FLOAT     Array[158377]  ; polA total power
 NSMPB    LONG            158354   ; # of samples for tpB
 HRB      DOUBLE    Array[158354]  ; polB time stamps 
 TPB      FLOAT     Array[158354]  ; polB total power

 Note that polA and polB can have a different number of samples.

(See /pkg/rsi/local/libao/phil/ecal/ecaltpday.pro)