1.22. convertK2Jy

Full Name: herschel.hifi.dp.tools.ConvertK2JyTask
Alias: convertK2Jy
Type: Java Task - Java Task
Import: from herschel.hifi.dp.tools import ConvertK2JyTask
Categories

HIFI/Conversion

HIFI/Conversion

Description

Convert the Flux intensities from Kelvin to Jansky.

It can be used for all the spectra contained inside an ObservationContextfor HIFI observation or HifiTimelineProduct or HifiSpectrumDataset or SimpleSpectrum . The Temperature values are converted to Ta' , i.e. if the parameter "forwardEff" or "beamEff" is present in the MetaData of the Spectrum, the temperature are converted respectively from Ta* or Tmb to Ta' with a multiplication of the flux values with the coefficient in the MetaData.

  • When parameter hifiBeam=False the beam is approximated with a gaussian and the formula used in the conversion are:

    1) If the size = 0 the pointing like source formula is used, i.e.

    S/Ta [Jy/K] = 2k / (Ageom * eta_A), where:

    • S is the Energy flux expressed in Jansky

    • Ta is the Antenna Temperature measured in Kelvin

    • k is the Boltzman constant,

    • Ageom is the effective area of the telescope, which we have assumed to be 3.28m diameter, so Ageom = 8.45m^2

    • eta_A is the aperture efficiency, to be extracted from the calibration tree for the frequency of interest

    2) If the size >0 :

    S/Ta [Jy/K] = 2k / (Ageom * eta_A) / Koeff where:

    • S is the Energy flux expressed in Jansky

    • Ta is the Antenna Temperature measured in Kelvin

    • eta_A ,Ageom,k have the same meaning of point 1).

    • Koeff = (1-exp(-x^2))/x^2

      • x = Sqrt( ln(2) )* (source diameter/FWHM_mainbeam)

      • FWHM_mainbeam = sqrt( 4 ln(2) / pi * eta_B * lambda^2/ (eta_A * Ageom) )

      • lambda is the wavelength

      • eta_B is the Main beam efficiency

  • When parameter hifiBeam=True the Beam shape is retreived from the calibration Tree and the formula used is the same of above, but the Koeff is computed through Matrix integration with the formula as point 2) above, but:

    • Koeff = ( P (θ θ' , φ φ' )ψ(θ , φ )dΩ ) / ( P (θ , φ )

      • P (θ , φ ) is the Beam profile

      • ψ(θ , φ ) is the source distribution

Examples

Example 1: convert data in a HifiTimeline Product
obsid=1342216838
obs=getObservation(obsid=obsid, useHsa=True)
cal=obs.calibration
htpv=obs.getProduct("level2").getProduct("WBS-H-USB")
res=convertK2Jy(htp=htpv, size=0, cal=cal) #calibration input
res1=convertK2Jy(htp=htpv.copy(), size=0)  # Use hard coded formula with coefficient function of frequency
Example 2: convert all data in a level 2 ObservationContext
obsid=1342216838
obs=getObservation(obsid=obsid, useHsa=True)
obs2=convertK2Jy(obs=obs, size=10)  #use obs.calibration to retrieve coefficients
obs=getObservation(obsid=obsid, useHsa=True)
obs2=convertK2Jy(obs=obs, size=10, useInterpolation=1)# Use hard coded formula with coefficient function of frequency
Example 3: convert data in a HifiSpectrumDataset
obsid=1342216838
obs=getObservation(obsid=obsid, useHsa=True)
cal=obs.calibration
htpv=obs.getProduct("level2").getProduct("WBS-H-USB")
ds=htpv[1]
res=convertK2Jy(ds=ds, size=40, cal=cal) #use coefficient from calibration input
res1=convertK2Jy(ds=ds, overwrite=0, size=40)  # Use hard coded formula with coefficient function of frequency
res2=convertK2Jy(ds=ds.copy(), size=40 ,cal=cal, useInterpolation=1)  
# Use hard coded formula with coefficient function of frequency
Example 4: convert data in a SimpleSpectrum
obsid=1342216838
obs=getObservation(obsid=obsid, useHsa=True)
htpv=obs.getProduct("level2").getProduct("WBS-H-USB")
spectrum = convertSingleHifiSpectrum(spectra=htpv)
res=convertK2Jy(spectrum=spectrum, size=0)   #compute Beff and Aeff in function of middle frequency

API details

Properties

ObservationContext obs [INPUT, OPTIONAL, default=No default value.]

Provides the ObservationContext cantaining the HifiTimelineProduct with HifiSpectrumDataset where the Flux has to be converted from Kelvin to Jansky. "spectrum" or "htp" or "ds" or "obs" inputs must be provided.

HifiTimelineProduct htp [INPUT, OPTIONAL, default=No default value.]

Provides the HifiTimelineProduct with HifiSpectrumDataset where the Flux has to be converted from Kelvin to Jansky. "spectrum" or "htp" or "ds" or "obs" inputs must be provided.

HifiSpectrumDataset ds [INPUT, OPTIONAL, default=No default value.]

Provides the HifiSpectrumDataset where the Flux has to be converted from Kelvin to Jansky. "spectrum" or "htp" or "ds" or "obs" inputs must be provided.

SimpleSpectrum spectrum [INPUT, OPTIONAL, default=No default value.]

Provides the SimpleSpectrum where the Flux has to be converted from Kelvin to Jansky. "spectrum" or "htp" or "ds" or "obs" inputs must be provided.

Boolean useInterpolation [INPUT, OPTIONAL, default=False.]

If useInterpolation= True the Task use hard coded formula values to compute BeamEfficiency and ApertureEfficiency and each flux values will have its own values for eta_A and eta_A computed in function of Frequency.

eta_A=eta_A0*Math.exp(-1*Math.pow((4 * Math.PI*sigma/lambda),2.0));.

eta_B=eta_B0*Math.exp(-1*Math.pow((4 * Math.PI*sigma/lambda),2.0));.

Where:

  • eta_B0=0.76;

  • eta_A0=0.68;

but in Band 5 i.e. when frequency in range [1120, 1410 ]GHz

  • eta_B0=0.66;

  • eta_A0=0.58;

Double size [INPUT, OPTIONAL, default=No default value ]

The size in arcsec of the source observed. In case a Double2d is passed in the 'inputShape' input, the 'size' represent the total dimension (in arcsec) of each dimension of the squared array passed

Double tol [INPUT, OPTIONAL, default=0.1.]

Tolerance in frequency unit to recompute Koeff when the conversion is performed with hifiBeam=True.

In case useLo= False the Koeff should be computed for each frequency of the spectra, but when a large observation is passed, the computation time of the coupling between Beam and Source could take too much time, thus such computation is performed only for frequency steps of the specified value. The maximum difference between 2 Koeff computed is printed at the and of the conversion.

The "tol" value is used also with useLo=True in case the LO changes during the observation (e.g. in SpectralScan observation).

MapContext cal [INPUT, OPTIONAL, default=No DefaultValue.]

A root of a Calibration tree where the Task can retrieve: apertureEfficiency, beamEfficiency. If the input is an ObservationContext ("obs") and the "cal" input is null the Task use the CalibrationTree of the ObservationContext. In other cases if the "cal" input is not passed the Task set the parameter useInterpolation=True and use hard coded formula to compute coefficients.

Boolean overwrite [INPUT, OPTIONAL, default=True.]

When set to False the "htp","ds","spectrum" input will be not overwritten , while "obs" will be always overwritten with a warning message.

Boolean reverse [INPUT, OPTIONAL, default=False.]

If reverse = True and data are in FluxDensity: Convert from Jansky in to Kelvin If reverse = False and data are in Temperature: Convert from Kelvin in to Jansky

String shape [INPUT, OPTIONAL, default="disk".]

The shape of the source: actually possible shapes are only "disk" or "gaussian". For different shape use the input 'inputShape'

For the code everything that is not a "gaussian" will be a disk (default).

For gaussian source the computed Koeff will use the same X defined in the Task description:i.e.

In case of hifiBeam=False Koeff = 1./(1.+x^2/ln(2)) or

In case of hifiBeam=True it will use the simplified equation: Koeff = ( P (θ , φ )ψ(θ , φ )dΩ ) / ( P (θ , φ );

I.e. in this computation all the spectra will be considered to point to the center of the Gaussian or Disk Source independent of the real pointed position.

Image or Double2d inputShape [INPUT, OPTIONAL, default=null.]

A user-provided source brightness distribution model.

It should be used only with 'hifiBeam' = True.

It accept Image or squared Double2d Array (Image could also contains not squared array).

The Jansky conversion is computed with the approximation that each spectrum point to the same ra/dec computed as the average of the real pointed coordinates.

The Source Image should contains the pointed ra/dec coordinate. Thus a source distribution model that is located outside the passed pointed spectra will return an error. For Double2D array the distribution model is supposed to be positionated with its array center at ra/dec computed as the average of the real pointed coordinates.

Boolean hifiBeam [INPUT, OPTIONAL, default=true.]

If 'hifiBeam'=true it use the hifi detailed Beam model from Calibration Tree. The Beam model in the calibration tree can 1 or 2 dimensional.

If 'hifiBeam'=false it use a gaussian beam.

Boolean useLo [INPUT, OPTIONAL, default=true. ]

If 'useLo' = True the frequency used in the conversion is the LO frequency.

If 'useLo' = False the frequencies used in the conversion are all the frequencies contained in the spectrum.

Boolean result [OUTPUT, OPTIONAL, default=true.]

Passed data with flux converted from measured temperature in Kelvin (K) to flux density in Jansky (Jy)

(or the other way around in case 'reverse'= True).

See also

History

  • 2010-01-22 - Write: the documentation of the Class