Produced by IDL 7.1.1
User Documentation

./contrib
scal.pro

Last modification date:
Wed Sep 28 13:27:15 2016

scal is a collection of routines for creating a vector Tcal from observations of a calibrator. Supports:

User's Guide for Vector Calibration

I will illustrate how one uses vector calibration by providing first a typical sequence of commands I use. See the documentation for the individual routines for additional information. The library is maintained in three files, all of which are in the GBTIDL contribute area.

Step (1) -- Load in the libraries from the GBTIDL contribute area.

Note that the compile order is important in order to avoid errors

Type:

       GBTIDL -> .compile scalUtils.pro
       GBTIDL -> .compile scal.pro
       GBTIDL -> .compile getVctr.pro
 

Step (2) -- Connect to your data set

Type either:

       GBTIDL -> filein, 'blah.fits'
 
or
       GBTIDL -> offline, 'projid'
 
or
       GBTIDL -> online
 

Step (3) -- Create the common block where the calibration database will reside.

Type:

       GBTIDL -> createCalStruct
 

Running this should empty the Tcal database. I find I only need to run this command infrequently. It must be done each GBTIDL session since the database is not retained between sessions.

Step (4) -- Fill in the Tcal database.

The scal* examples below will use calibration scan 34 which is assumed to be toward a standard calibration source. I tend to smooth the Tcal vectors to 1 MHz (smth=1). See the documentation for scal.pro for how to specify a frequency-dependent functional form for opacity. These scal* routines must be run once per IDL session. Re-executing these commands with a new scan will overwrite the database with new Tcal vectors.

How you generate Tcal vectors depends upon the observing mode and receiver.

(4.a) For Ka-band with subreflector nodding:

	GBTIDL -> scalKaSubrNod, 34, tau=[0.023], ifnum=0, smth=1

(4.b) For any subreflector nodding observation other than Ka-band, substitute for the above commands:

	GBTIDL -> scalSubrNod, 34, tau=[0.023], ifnum=0, plnum=0, smth=1
	GBTIDL -> scalSubrNod, 34, tau=[0.023], ifnum=0, plnum=1, smth=1

(4.c) For any NOD, Ka-band observation, substitute for the above commands:

	GBTIDL -> scal, 34, 35, tau=[0.023], ifnum=0, plnum=0, fdnum=0, smth=1
	GBTIDL -> scal, 35, 34, tau=[0.023], ifnum=0, plnum=1, fdnum=1, smth=1
Note how the order of the given scan numbers is reversed for the 2nd feed

(4.d) For any NOD, non-Ka-band observation, substitute for the above commands:

	GBTIDL -> scal, 34, 35, tau=[0.023], ifnum=0, plnum=0, fdnum=0, smth=1
	GBTIDL -> scal, 34, 35, tau=[0.023], ifnum=0, plnum=1, fdnum=0, smth=1
	GBTIDL -> scal, 35, 34, tau=[0.023], ifnum=0, plnum=0, fdnum=1, smth=1
	GBTIDL -> scal, 35, 34, tau=[0.023], ifnum=0, plnum=1, fdnum=1, smth=1
Note how the order of the given scan numbers is reversed for the 2nd feed

(4.e) For any On-Off, single-beam Ka-band observation, substitute for the above commands:

	GBTIDL -> scal, 34, 35, tau=[0.023], ifnum=0, plnum=0, fdnum=0, smth=1
If you were using Off-On instead of On-Off observing, you will need to exchange the 34 for 35.

(4.f) For any On-Off, non-Ka-band observation, substitute for the above commands:

	GBTIDL -> scal, 34, 35, tau=[0.023], ifnum=0, plnum=0, smth=1
	GBTIDL -> scal, 34, 35, tau=[0.023], ifnum=0, plnum=1, smth=1
If you were using Off-On instead of On-Off observing, you will need to exchange the 34 for 35 and 35 for 34.

Step (5) -- Repeat for all IFNums

Repeat the above scal commands for each IFNum window, using a zenith opacity that may be different for each frequency window. The Tcal vector for each window is stored separately in the database.

Step (6) -- Check results (Optional)

I sometimes take a look at the results.

	GBTIDL -> plotCalDB
See the comments in scal.pro for other plot options.

Step (7) -- Apply Tcal vectors to actual observations

Now that the database contains Tcal vectors for every IFNum, PLnum, etc, you can start averaging scans for a particular source. Before averaging, you will need to remove the affects of the atmosphere at the elevation of the observation and maybe convert to Jy using the Ta2Flux routine. Many ways to do this. Here's one that will average up scans 41,42,...45,48, ...52... Scans 40-45 are assumed to have a different opacity than scans 48-52.

Again, how you do this is receiver and observing mode dependent.

(7.a) Assuming Ka-band subreflector nodding:

	GBTIDL -> sclear
	GBTIDL -> for s = 40, 45 do begin & getKaSubrNod, s, ifnum=0 & Ta2Flux, tau=[0.026] & accum & end
	GBTIDL -> for s = 48, 52 do begin & getKaSubrNod, s, ifnum=0 & Ta2Flux, tau=[0.0275] & accum & end
	GBTIDL -> ave

(7.b) For any subreflector nodding observation other than Ka-band, substitute for the above commands:

	GBTIDL -> sclear
	GBTIDL -> for s = 40, 45 do begin & getVctrSubrNod, s, ifnum=0, plnum=0 & Ta2Flux, tau=[0.026] & accum & end
	GBTIDL -> for s = 48, 52 do begin & getVctrSubrNod, s, ifnum=0, plnum=0 & Ta2Flux, tau=[0.0275] & accum & end
	GBTIDL -> for s = 40, 45 do begin & getVctrSubrNod, s, ifnum=0, plnum=1 & Ta2Flux, tau=[0.026] & accum & end
	GBTIDL -> for s = 48, 52 do begin & getVctrSubrNod, s, ifnum=0, plnum=1 & Ta2Flux, tau=[0.0275] & accum & end
	GBTIDL -> ave

(7.c) For any NOD, Ka-band observation, substitute for the above commands:

	GBTIDL -> sclear
	GBTIDL -> for s = 40, 45, 2 do begin & getVctr, s, s+1, ifnum=0, plnum=0, fdnum=0 & Ta2Flux, tau=[0.026] & accum & end
	GBTIDL -> for s = 48, 52, 2 do begin & getVctr, s, s+1, ifnum=0, plnum=0, fdnum=0 & Ta2Flux, tau=[0.0275] & accum & end
	GBTIDL -> for s = 40, 45, 2 do begin & getVctr, s+1, s, ifnum=0, plnum=1, fdnum=1 & Ta2Flux, tau=[0.026] & accum & end
	GBTIDL -> for s = 48, 52, 2 do begin & getVctr, s+1, s, ifnum=0, plnum=1, fdnum=1 & Ta2Flux, tau=[0.0275] & accum & end
	GBTIDL -> ave
Note how the s and s+1 arguments change when one averages in the data from the 2nd feed.

(7.d) For any NOD, non-Ka-band observation, substitute for the above commands:

	GBTIDL -> sclear
	GBTIDL -> for s = 40, 45, 2 do begin & getVctr, s, s+1, ifnum=0, plnum=0, fdnum=0 & Ta2Flux, tau=[0.026] & accum & end
	GBTIDL -> for s = 48, 52, 2 do begin & getVctr, s, s+1, ifnum=0, plnum=0, fdnum=0 & Ta2Flux, tau=[0.0275] & accum & end
	GBTIDL -> for s = 40, 45, 2 do begin & getVctr, s, s+1, ifnum=0, plnum=1, fdnum=0 & Ta2Flux, tau=[0.026] & accum & end
	GBTIDL -> for s = 48, 52, 2 do begin & getVctr, s, s+1, ifnum=0, plnum=1, fdnum=0 & Ta2Flux, tau=[0.0275] & accum & end
	GBTIDL -> for s = 40, 45, 2 do begin & getVctr, s+1, s, ifnum=0, plnum=0, fdnum=1 & Ta2Flux, tau=[0.026] & accum & end
	GBTIDL -> for s = 48, 52, 2 do begin & getVctr, s+1, s, ifnum=0, plnum=0, fdnum=1 & Ta2Flux, tau=[0.0275] & accum & end
	GBTIDL -> for s = 40, 45, 2 do begin & getVctr, s+1, s, ifnum=0, plnum=1, fdnum=1 & Ta2Flux, tau=[0.026] & accum & end
	GBTIDL -> for s = 48, 52, 2 do begin & getVctr, s+1, s, ifnum=0, plnum=1, fdnum=1 & Ta2Flux, tau=[0.0275] & accum & end
	GBTIDL -> ave
Note how the s and s+1 arguments change when one averages in the data from the 2nd feed.

(7.e) For any On-Off, single-beam Ka-band observation, substitute for the above commands:

 
	GBTIDL -> sclear
	GBTIDL -> for s = 40, 45, 2 do begin & getVctr, s, s+1, ifnum=0, plnum=0 & Ta2Flux, tau=[0.026] & accum & end
	GBTIDL -> for s = 48, 52, 2 do begin & getVctr, s, s+1, ifnum=0, plnum=0 & Ta2Flux, tau=[0.0275] & accum & end
	GBTIDL -> ave
If you were using Off-On instead of On-Off observing, you will need to exchange the 's+1' everywhere there is an 's' and exchage 's' everywhere there is an 's+1'.

(7.f) For any On-Off, single-beam non-Ka-band observation, substitute for the above commands:

	GBTIDL -> sclear
	GBTIDL -> for s = 40, 45, 2 do begin & getVctr, s, s+1, ifnum=0, plnum=0 & Ta2Flux, tau=[0.026] & accum & end
	GBTIDL -> for s = 48, 52, 2 do begin & getVctr, s, s+1, ifnum=0, plnum=0 & Ta2Flux, tau=[0.0275] & accum & end
	GBTIDL -> for s = 40, 45, 2 do begin & getVctr, s, s+1, ifnum=0, plnum=1 & Ta2Flux, tau=[0.026] & accum & end
	GBTIDL -> for s = 48, 52, 2 do begin & getVctr, s, s+1, ifnum=0, plnum=1 & Ta2Flux, tau=[0.0275] & accum & end
	GBTIDL -> ave
If you were using Off-On instead of On-Off observing, you will need to exchange the 's+1' everywhere there is an 's' and exchage 's' everywhere there is an 's+1'.

Step (8) -- Repeat the generation of the above average but for ifnum=1, 2, 3, ...

Repeat the above scal commands for each IFNum window, using a zenith opacity that may be different for each frequency window.

Of course, you will need to change this workflow to match your own style and needs. But, the above should give you a flavor of the sequence of how to process the various parts. (You should expect typos since I didn't run anything through GBTIDL to check for syntax errors)

Contributed By: Ron Maddalena, NRAO-GB

Routine Summary  7 routines

procedure createCalStruct

Initializes or reinitializes the calCommon common block.

procedure plotCalDB, [type=string]

Plots the contents of the calibration DB.

procedure getCalDB, idx

Retrieves data from the calibration DB and places the results into various data contains.

procedure setCalDB, idx, [sampler=sampler], [freqs=freqs], [tcals=tcals], [tauVctr=tauVctr], [effVctr=effVctr], [tsys=tsys], [fluxVctr=fluxVctr]

Overwrites the contents of various scalars and vectors in the calibration database with the contents of IDL vectors.

procedure scalKaSubrNod, scan, [ifnum=integer], [tau=float], [ap_eff=float], [smth=value], [src=string], [flux=flux], [specindex=specindex]

Calculates Tcal, Tsys, .

procedure scal, scan1, scan2, [ifnum=integer], [plnum=integer], [fdnum=integer], [tau=float], [ap_eff=float], [smth=value], [src=string], [flux=flux], [specindex=specindex]

Calculates Tcal,Tsys, .

procedure scalSubrNod, scan, [ifnum=integer], [plnum=integer], [tau=float], [ap_eff=float], [smth=value], [src=string], [flux=flux], [specindex=specindex]

Calculates Tcal, Tsys, .

Routine Details

createCalStruct

procedure createCalStruct

Initializes or reinitializes the calCommon common block.

Must be called at least once before any processing

Version
$Id$
Common blocks
calCommon

plotCalDB

procedure plotCalDB, [type=string]

Plots the contents of the calibration DB. The 'type' argument determines whether tsys, tcal (the default), tau, or eff are plotted

Common blocks
calCommon

Keywords
type
in, optional
string
The type of value to plot. Choices are "tcal", "tsys", "tau", "eff", and "flux". Defaults to "tcal".

getCalDB

procedure getCalDB, idx

Retrieves data from the calibration DB and places the results into various data contains.

The user must supply the index of the entry to retrieve from the database. The data containers will then contain:

Common blocks
calCommon

Parameters
idx
in, required
integer
Cal database index number.

setCalDB

procedure setCalDB, idx, [sampler=sampler], [freqs=freqs], [tcals=tcals], [tauVctr=tauVctr], [effVctr=effVctr], [tsys=tsys], [fluxVctr=fluxVctr]

Overwrites the contents of various scalars and vectors in the calibration database with the contents of IDL vectors.

The user must supply the index (idx) of the database entry that is to be overwritten to store plus the scalar or vectors to use. More than one scalar/vector can be overwritten with a single call. The scalars/vectors that can be overwritten are:

Common blocks
calCommon

Parameters
idx
in, required
integer
Cal database index number.

Keywords
sampler
in, optional
sampler
Sets the sampler value.
freqs
in, optional
freqs
Sets the freqs value.
tcals
in, optional
tcals
Sets the tcals value.
tauVctr
in, optional
tauVctr
Sets the tauVctr value.
effVctr
in, optional
effVctr
Sets the effVctr value.
tsys
in, optional
tsys
Sets the tsys value.
fluxVctr
in, optional
fluxVctr
Sets the fluxVctr value.

scalKaSubrNod

procedure scalKaSubrNod, scan, [ifnum=integer], [tau=float], [ap_eff=float], [smth=value], [src=string], [flux=flux], [specindex=specindex]

Calculates Tcal, Tsys, ... from a Ka-band subreflector nodding observations with the hybrid phases cycling.

Assumes the system is linear (Pwr_in = B*Pwr_out).

Source fluxes are calculated in getFluxCalib for every channel. The routine uses the Ott et al polynomials coefficients for the fluxes of the 'standard' calibrators. Modify this routine when using frequencies outside the Ott fitting range or using a source not in the Ott catalog.

Modify getApEff and getTau if you want a frequency-dependent efficiency or opacity. getAppEff also allows for an elevation dependent efficiency. Results are stored in the calCommon common block. The index entry is encoded as:

    idx = ifnum + 8*s + 16*jSigRef
 
where jsigRef = 0 or 1 for the two possible states of the hybrid and where s = 0 or 1 for the two possible states of the subreflector

The algorithm used is:

    Scal = exp(-Tau*AirMass)*Flux*(CalOn - CalOff)/(SubrPos0 - SubrPos1)
    Tcal = 2.8 * ap_eff * Scal
    Tsys = Tcal * Ref_CalOff / (Ref_CalOn - Ref_CalOff)
 

Examples
getscalKaSubrNod,211,ifnum=0,tau=[0.034],smth=1,src='3C48' getscalKaSubrNod,212
Common blocks
calCommon

Parameters
scan
in, required
integer
Scan number to process

Keywords
ifnum
in, optional
integer
Number of the spectral window. If not supplied, will assume zero (1st window)
tau
in, optional
float
vector that encodes as polynomial coefficients the opacity at the zenith in nepers. If not supplied, will assume the value returned by getTau. See the documentation for getTau for the format of the vector.
ap_eff
in, optional
float
1 or 2-element vector that encodes aperture efficiency and it's frequency dependency. If not supplied, will assume the value returned by getApEff . See the documentation for getApEff for the format of the vector.
smth
in, optional
value
The amount to boxcar smooth the data in MHz. Sometimes mandatory if the source is weak and using very narrow channels. Default is no smoothing
src
in, optional
string
An optional string that allows one to override the source names used in the observations
flux
in, optional
flux
An optional 1, 2, or 3-element vector that encodes the flux of the calibrator and it's frequency dependency. See the documentation for getFluxCalib for the format of the vector. If not supplied, the routine will attempt to use getFluxCalib internal database of fluxes for standard calibrator.s
specindex
in, optional
specindex
An optional spectral index for the source. Will be used only if flux is also given and only if flux is a single-element.

scal

procedure scal, scan1, scan2, [ifnum=integer], [plnum=integer], [fdnum=integer], [tau=float], [ap_eff=float], [smth=value], [src=string], [flux=flux], [specindex=specindex]

Calculates Tcal,Tsys, ... from an on-off or nod (but not subreflector nod) observation of any receiver except Ka-band.

Assumes the system is linear (Pwr_in = B*Pwr_out).

Source fluxes are calculated in getFluxCalib for every channel. The routine uses the Ott et al polynomials coefficients for the fluxes of the 'standard' calibrators. Modify this routine when using frequencies outside the Ott fitting range or using a source not in the Ott catalog.

Modify getApEff and getTau if you want a frequency-dependent efficiency or opacity. getAppEff also allows for an elevation dependent efficiency.

Results are stored in the calCommon common block. The index entry is encoded as:

    idx = ifnum + 8*plnum + 16*fdnum
 

The algorithm used is:

    Scal = exp(-Tau*AirMass)*Flux*(Ref_CalOn - Ref_CalOff)/(Sig_CalOff - Ref_CalOff1)
    Tcal = 2.8 * ap_eff * Scal
    Tsys = Tcal * Ref_CalOff / (Ref_CalOn - Ref_CalOff)
 

Examples
getscal,211,212,ifnum=1,plnum=0,tau=[0.034],smth=1,src='3C48'
Common blocks
calCommon

Parameters
scan1
in, required
integer
on-source scan number
scan2
in, required
integer
off-source scan number

Keywords
ifnum
in, optional
integer
I.F. number as used in standard "get" commands. Defaults to zero.
plnum
in, optional
integer
polarization number as used in standard "get" commands. Defaults to zero.
fdnum
in, optional
integer
feed number as used in standard "get" commands. Defaults to zero.
tau
in, optional
float
vector that encodes as polynomial coefficients the opacity at the zenith in nepers. If not supplied, will assume the value returned by getTau. See the documentation for getTau for the format of the vector.
ap_eff
in, optional
float
1 or 2-element vector that encodes aperture efficiency and it's frequency dependency. If not supplied, will assume the value returned by getApEff . See the documentation for getApEff for the format of the vector.
smth
in, optional
value
The amount to boxcar smooth the data in MHz. Sometimes mandatory if the source is weak and using very narrow channels. Default is no smoothing
src
in, optional
string
An optional string that allows one to override the source names used in the observations
flux
in, optional
flux
An optional 1, 2, or 3-element vector that encodes the flux of the calibrator and it's frequency dependency. See the documentation for getFluxCalib for the format of the vector. If not supplied, the routine will attempt to use getFluxCalib internal database of fluxes for standard calibrator.s
specindex
in, optional
specindex
An optional spectral index for the source. Will be used only if flux is also given and only if flux is a single-element.

scalSubrNod

procedure scalSubrNod, scan, [ifnum=integer], [plnum=integer], [tau=float], [ap_eff=float], [smth=value], [src=string], [flux=flux], [specindex=specindex]

Calculates Tcal, Tsys, ... from a subreflector nodding observations for all dual beam receivers *except* Ka-band.

Assumes the system is linear (Pwr_in = B*Pwr_out).

Source fluxes are calculated in getFluxCalib for every channel. The routine uses the Ott et al polynomials coefficients for the fluxes of the 'standard' calibrators. Modify this routine when using frequencies outside the Ott fitting range or using a source not in the Ott catalog.

Modify getApEff and getTau if you want a frequency-dependent efficiency or opacity. getAppEff also allows for an elevation dependent efficiency.

Results are stored in the calCommon common block. The index entry is encoded as:

    idx = ifnum + 8*plnum + 16*s
 
where s = 0 or 1 for the two possible states of the subreflector

The algorithm used is:

    Scal = exp(-Tau*AirMass)*Flux*(CalOn - CalOff)/(SubrPos0 - SubrPos1)
    Tcal = 2.8 * ap_eff * Scal
    Tsys = Tcal * Ref_CalOff / (Ref_CalOn - Ref_CalOff)
 

Examples
getscalSubrNod,211,ifnum=0,tau=[0.034],smth=1,src='3C48' getscalSubrNod,212
Common blocks
calCommon

Parameters
scan
in, required
integer
Scan number to process

Keywords
ifnum
in, optional
integer
ifnum as used on standard "get" commands
plnum
in, optional
integer
plnum as used on standard get" commands
tau
in, optional
float
vector that encodes as polynomial coefficients the opacity at the zenith in nepers. If not supplied, will assume the value returned by getTau. See the documentation for getTau for the format of the vector.
ap_eff
in, optional
float
1 or 2-element vector that encodes aperture efficiency and it's frequency dependency. If not supplied, will assume the value returned by getApEff . See the documentation for getApEff for the format of the vector.
smth
in, optional
value
The amount to boxcar smooth the data in MHz. Sometimes mandatory if the source is weak and using very narrow channels. Default is no smoothing
src
in, optional
string
An optional string that allows one to override the source names used in the observations
flux
in, optional
flux
An optional 1, 2, or 3-element vector that encodes the flux of the calibrator and it's frequency dependency. See the documentation for getFluxCalib for the format of the vector. If not supplied, the routine will attempt to use getFluxCalib internal database of fluxes for standard calibrator.s
specindex
in, optional
specindex
An optional spectral index for the source. Will be used only if flux is also given and only if flux is a single-element.


Produced by IDLdoc 1.6 on Wed Sep 28 13:27:48 2016