Observation utilities
Observation generation
Definition of the obs_generator interface.
- obs.obs_generator.FPT(obsgen, obs, snr_ref, tint_ref, freq_ref, model_ref=None, ephem='ephemeris/space', **kwargs)[source]
Function to apply the frequency phase transfer (“FPT”) SNR thresholding scheme to an observation. This scheme attempts to mimic the fringe-fitting carried out in the HOPS calibration pipeline.
- Parameters
obsgen (ngehtsim.obs.obs_generator.obs_generator) – ngehtsim obs_generator object containing information about the observation
obs (ehtim.obsdata.Obsdata) – eht-imaging Obsdata object containing the input observation
snr_ref (float) – strong baseline SNR threshold
tint_ref (float) – strong baseline coherence time, in seconds
freq_ref (float) – FPT reference frequency, in GHz
model_ref (str) – path to FPT reference model, or the reference model itself
- Returns
An array of kept data indices
- Return type
- obs.obs_generator.determine_mjd(day, month, year)[source]
Determine the MJD from a given day, month, and year.
- obs.obs_generator.eta_dish(freq, sigma, offset, ap_eff)[source]
Function for computing overall antenna aperture efficiency.
- obs.obs_generator.export_SYMBA_antennas(obsgen, output_filename='obsgen.antennas', t_coh=10.0, RMS_point=1.0, PB_model='gaussian', use_two_letter=True, gain_mean=1.0, leak_mean=0j)[source]
Export a SYMBA-compatible .antennas file from the obs_generator object.
- Parameters
obsgen (ngehtsim.obs.obs_generator.obs_generator) – ngehtsim obs_generator object containing information about the observation
output_filename (str) – name of .antennas file to save
t_coh (float) – default coherence time, in seconds
RMS_point (float) – default RMS pointing uncertainty, in arcseconds
PB_model (str) – primary beam model to use; only option right now is ‘gaussian’
use_two_letter (bool) – convert all station names to two-letter codes
gain_mean (float, complex, dict) – Value of the mean gain offset for each station. If float or complex, will apply to all stations; if a dict, should be indexed by station name
leak_mean (float, complex, dict) – Value of the mean leakage offset for each station. If float or complex, will apply to all stations; if a dict, should be indexed by station name
- Returns
SYMBA-compatible .antennas file containing the observation information
- obs.obs_generator.export_SYMBA_master_input(obsgen, input_args={}, input_comments={}, output_filename='master_input.txt', use_two_letter=True)[source]
Export a SYMBA-compatible master_input.txt file from the obs_generator object.
- Parameters
obsgen (ngehtsim.obs.obs_generator.obs_generator) – ngehtsim obs_generator object containing information about the observation
input_args (dict) – dictionary of input arguments
input_comments (dict) – dictionary of comments associated with input arguments
output_filename (str) – name of master_input.txt file to save
use_two_letter (bool) – convert all station names to two-letter codes
- Returns
SYMBA-compatible master_input.txt file containing the observation information
- obs.obs_generator.fringegroups(obsgen, obs, snr_ref, tint_ref)[source]
Function to apply the “fringegroups” SNR thresholding scheme to an observation. This scheme attempts to mimic the fringe-fitting carried out in the HOPS calibration pipeline.
- Parameters
obsgen (ngehtsim.obs.obs_generator.obs_generator) – ngehtsim obs_generator object containing information about the observation
obs (ehtim.obsdata.Obsdata) – eht-imaging Obsdata object containing the input observation
snr_ref (float) – strong baseline SNR threshold
tint_ref (float) – strong baseline coherence time, in seconds
- Returns
An array of kept data indices
- Return type
- obs.obs_generator.get_site_list()
Return a list of known stations; “get_station_list” and “get_site_list” are equivalent
- Returns
a list of station names
- Return type
(list)
- obs.obs_generator.get_station_list()[source]
Return a list of known stations; “get_station_list” and “get_site_list” are equivalent
- Returns
a list of station names
- Return type
(list)
- obs.obs_generator.get_unready_sites(sites, tech_readiness, rng=Generator(PCG64) at 0x104984820)[source]
Function to determine which sites will randomly fail technical readiness.
- Parameters
sites (list) – list of sites participating in the observation
tech_readiness (float) – probability of any individual site being technically ready to observe; takes on a value between 0 and 1
rng (numpy.random.Generator) – a numpy random number generator
- Returns
sites to drop
- Return type
(list)
- obs.obs_generator.load_image(infile, freq=230000000000.0, verbosity=0)[source]
Load an ehtim image or movie object.
- Parameters
- Returns
An ehtim image or movie object; returns None if infile is None
- Return type
- obs.obs_generator.make_array(sitelist, ephem='ephemeris/space', verbosity=0)[source]
Create an ehtim array object from a list of sites.
- Parameters
- Returns
An ehtim array object
- Return type
- class obs.obs_generator.obs_generator(settings={}, settings_file=None, verbosity=0, weight=0, D_overrides={}, surf_rms_overrides={}, receiver_configuration_overrides={}, bandwidth_overrides={}, T_R_overrides={}, sideband_ratio_overrides={}, lo_freq_overrides={}, hi_freq_overrides={}, ap_eff_overrides={}, wind_loading_overrides={}, custom_receivers={}, station_uptimes={}, array=None, ephem='ephemeris/space')[source]
Class that organizes information for generating synthetic observations.
- settings_file
Path to the input settings file; if set to None, will use default settings. Note that any settings specified by the settings keyword argument will override the corresponding settings from the settings file.
- Type
- surf_rms_overrides
A dictionary of station names and surface RMS values (in microns) to override defaults
- Type
- receiver_configuration_overrides
A dictionary of station names and available receivers to override defaults
- Type
- bandwidth_overrides
A dictionary of station names and bandwidth values to override defaults
- Type
- T_R_overrides
A dictionary of station names and receiver temperature values to override defaults
- Type
- sideband_ratio_overrides
A dictionary of station names and sideband ratio values to override defaults
- Type
- lo_freq_overrides
A dictionary of station names and receiver lowest frequency values to override defaults
- Type
- hi_freq_overrides
A dictionary of station names and receiver lowest frequency values to override defaults
- Type
- ap_eff_overrides
A dictionary of station names and aperture efficiency values to override defaults
- Type
- wind_loading_overrides
A dictionary of station names and wind-loading v0, w values (in m/s) to override defaults
- Type
- export_SYMBA(symba_workdir='./data', output_filenames=['obsgen.antennas', 'master_input.txt'], t_coh=10.0, RMS_point=0.0, PB_model='gaussian', use_two_letter=True, gain_mean=1.0, leak_mean=0j, master_input_args={}, master_input_comments={})[source]
Export SYMBA-compatible directory structure and input files from the obs_generator object.
- Parameters
symba_workdir (str) – name of SYMBA working directory to use or create
output_filenames (list) – names of .antennas and master_input.txt files to save
t_coh (float) – default coherence time, in seconds
RMS_point (float) – default RMS pointing uncertainty, in arcseconds
PB_model (str) – primary beam model to use; only option right now is ‘gaussian’
use_two_letter (bool) – convert all station names to two-letter codes
gain_mean (float, complex, dict) – Value of the mean gain offset for each station. If float or complex, will apply to all stations; if a dict, should be indexed by station name
leak_mean (float, complex, dict) – Value of the mean leakage offset for each station. If float or complex, will apply to all stations; if a dict, should be indexed by station name
master_input_args (dict) – dictionary of master input arguments
master_input_comments (dict) – dictionary of comments associated with master input arguments
- Returns
SYMBA-compatible .antennas and master_input.txt files
- make_obs(input_model=None, addnoise=True, addgains=True, gainamp=0.04, leakamp=0.1, opacitycal=True, addFR=True, addleakage=False, flagwind=True, flagday=False, flagsun=True, allow_mixed_basis=False, el_min=10.0, el_max=80.0, p=None)[source]
Generate an observation that folds in weather-based opacity effects and applies a specified SNR thresholding scheme to mimic fringe-finding.
- Parameters
input_model (ehtim.image.Image, ehtim.movie.Movie, ehtim.model.Model, ngEHTforecast.fisher.fisher_forecast.FisherForecast) – input source model
addnoise (bool) – flag for whether or not to add thermal noise to the visibilities
addgains (bool) – flag for whether or not to add station gain corruptions
gainamp (float) – standard deviation of amplitude log-gains
leakamp (float) – standard deviation of leakage real and imaginary parts
opacitycal (bool) – flag for whether or not to assume that atmospheric opacity is assumed to be calibrated out
addFR (bool) – flag for whether or not to add feed rotations
addleakage (bool) – flag for whether or not to add polarization leakage corruptions
flagwind (bool) – flag for whether to derate sites with high wind
flagday (bool) – flag for whether to flag sites during the local daytime
flagsun (bool) – flag for whether to impose a minimum solar avoidance angle
allow_mixed_basis (bool) – flag for whether to apply polarization basis conversions
el_min (float) – minimum elevation that a site can observe at, in degrees
el_max (float) – maximum elevation that a site can observe at, in degrees
p (numpy.ndarray) – list of parameters for an input ngEHTforecast.fisher.fisher_forecast.FisherForecast object
- Returns
eht-imaging Obsdata object containing the generated observation
- Return type
- make_obs_mf(freqs, input_models, addnoise=True, addgains=True, gainamp=0.04, leakamp=0.1, opacitycal=True, addFR=True, addleakage=False, flagwind=True, flagday=False, flagsun=True, el_min=10.0, el_max=80.0, p=None)[source]
Generate a multi-frequency observation
- Parameters
freqs (list) – list of frequencies at which to carry out the observation, in GHz
input_models (list) – list of input source models; one for each frequency
addnoise (bool) – flag for whether or not to add thermal noise to the visibilities
addgains (bool) – flag for whether or not to add station gain corruptions
gainamp (float) – standard deviation of amplitude log-gains
leakamp (float) – standard deviation of leakage real and imaginary parts
opacitycal (bool) – flag for whether or not to assume that atmospheric opacity is assumed to be calibrated out
addFR (bool) – flag for whether or not to add feed rotations
addleakage (bool) – flag for whether or not to add polarization leakage corruptions
flagwind (bool) – flag for whether to derate sites with high wind
flagday (bool) – flag for whether to flag sites during the local daytime
flagsun (bool) – flag for whether to impose a minimum solar avoidance angle
el_min (float) – minimum elevation that a site can observe at, in degrees
el_max (float) – maximum elevation that a site can observe at, in degrees
p (list) – list of lists of parameters for input ngEHTforecast.fisher.fisher_forecast.FisherForecast objects; one for each frequency
- Returns
list of ehtim.obsdata.Obsdata objects containing the generated observations; one for each frequency
- Return type
(list)
- observe(input_model, addnoise=True, addgains=True, gainamp=0.04, leakamp=0.1, opacitycal=True, addFR=True, addleakage=False, flagwind=True, flagday=False, flagsun=True, allow_mixed_basis=False, el_min=10.0, el_max=80.0, p=None)[source]
Generate a raw single-band observation that folds in weather-based opacity and sensitivity effects.
- Parameters
input_model (ehtim.image.Image, ehtim.movie.Movie, ehtim.model.Model, ngEHTforecast.fisher.fisher_forecast.FisherForecast) – input source model
addnoise (bool) – flag for whether or not to add thermal noise to the visibilities
addgains (bool) – flag for whether or not to add station gain corruptions
gainamp (float) – standard deviation of amplitude log-gains
leakamp (float) – standard deviation of leakage real and imaginary parts
opacitycal (bool) – flag for whether or not to assume that atmospheric opacity is assumed to be calibrated out
addFR (bool) – flag for whether or not to add feed rotations
addleakage (bool) – flag for whether or not to add polarization leakage corruptions
flagwind (bool) – flag for whether to derate sites with high wind
flagday (bool) – flag for whether to flag sites during the local daytime
flagsun (bool) – flag for whether to impose a minimum solar avoidance angle
allow_mixed_basis (bool) – flag for whether to apply polarization basis conversions
el_min (float) – minimum elevation that a site can observe at, in degrees
el_max (float) – maximum elevation that a site can observe at, in degrees
p (numpy.ndarray) – list of parameters for an input ngEHTforecast.fisher.fisher_forecast.FisherForecast object
- Returns
eht-imaging Obsdata object containing the generated observation
- Return type
Observation plotting
Definition of the obs_plotter interface.
- obs.obs_plotter.plot_amp(obs, filename='ampplot.png', xlim=(0, 10), ylim=(0.01, 3))[source]
Create and save a plot of visibility amplitude vs \((u,v)\)-distance.
- Parameters
obs (ehtim.obsdata.Obsdata) – eht-imaging Obsdata object
filename (str) – file name for output plot
xlim (tuple) – x-axis range, in \(\rm{G}\lambda\)
ylim (tuple) – y-axis range, in Jy
- obs.obs_plotter.plot_phase(obs, filename='phaseplot.png', xlim=(0, 10), ylim=(- 180, 180))[source]
Create and save a plot of visibility phase vs \((u,v)\)-distance.
- Parameters
obs (ehtim.obsdata.Obsdata) – eht-imaging Obsdata object
filename (str) – file name for output plot
xlim (tuple) – x-axis range, in \(\rm{G}\lambda\)
ylim (tuple) – y-axis range, in degrees
- obs.obs_plotter.plot_snapshot(obs, obsgen, metric, filename='metric.png', timetype='UTC', fov=100.0, fillpix=10, logmid=1.5, logwid=0.525, stokes='I', artype='mean', weighting='natural', robust=0.0, ylim=None)[source]
Create and save a plot of the chosen metric on snapshots.
- Parameters
obs (ehtim.obsdata.Obsdata) – eht-imaging Obsdata object
obsgen (ngehtsim.obs.obs_generator) – an input obs_generator object
metric (str) – selected metric to plot; can be ‘ff’, ‘bff’, lcg’, ‘ar’
filename (str) – file name for output plot
timetype (str) – eht-imaging recognized timetype; can be ‘UTC’ or ‘GMST’
fov (float) – field of view for computing FF, in \(\mu\rm{as}\)
logmid (float) – the logarithmic midpoint of the BFF SNR mapping function
logwid (float) – the logarithmic width of the BFF SNR mapping function
stokes (str) – Stokes parameter for which to compute the BFF metric; can be ‘I’, ‘Q’, ‘U’, ‘V’
artype (str) – what measure of the beam shape to use for AR metric; can be ‘mean’, ‘minor’, ‘major’, ‘PA’, ‘angle’
weighting (str) – \((u,v)\)-weighting scheme for AR metric; can be ‘natural’, ‘uniform’, ‘Briggs’, ‘robust’
robust (float) – the robust parameter for Briggs weighting in the AR metric
ylim (tuple) – y-axis range
- obs.obs_plotter.plot_snr(obs, filename='snrplot.png', xlim=(0, 10), ylim=(1.0, 10000.0))[source]
Create and save a plot of SNR vs \((u,v)\)-distance.
- Parameters
obs (ehtim.obsdata.Obsdata) – eht-imaging Obsdata object
filename (str) – file name for output plot
xlim (tuple) – x-axis range, in \(\rm{G}\lambda\)
ylim (tuple) – y-axis range
- obs.obs_plotter.plot_uv(obs, filename='uvplot.png', umax=10)[source]
Create and save a \((u,v)\)-coverage plot.
- Parameters
obs (ehtim.obsdata.Obsdata) – eht-imaging Obsdata object
filename (str) – file name for output plot
umax (float) – maximum baseline length for plot axes, in \(\rm{G}\lambda\)