EMBERS: Home ༶ Table of Contents ༶ API Reference

API Reference — Tile Maps

embers.tile_maps is used to create tile maps by aggregating satellite data

It contains beam_utils, ref_fee_healpix, tile_maps, null_test, compare_beams

Beam Utils

A set of tools used to create and visualize tile maps

embers.tile_maps.beam_utils.rotate_map(nside, angle=None, healpix_array=None, savetag=None, flip=False)

Rotates healpix array by the desired angle, and saves it.

Optionally flip the data, changes east-west into west-east because astronomy

Parameters:
  • nside – Healpix nside
  • angle – Angle by which to rotate the healpix map
  • healpix_array – Input healpix array to be rotated
  • savetag – If given, will save the rotated beam map to .npz file
  • flip – Do an astronomy coordinate flip, if True
Returns:

  • Rotated healpix map
embers.tile_maps.beam_utils.healpix_cardinal_indices(nside, za_max=90)

Cardinal slices of healpix maps, upto an zenith angle threshold.

Healpix maps of nside=32 do not have pixels along their cardinal axes, but do have them along their diagonal axes. This function determined the indices of diagonal slices of healpix maps, assuming the original map has been rotated by + 𝛑/4 using the rotate_map() function.

Parameters:
  • nside – Healpix nside
  • za_max – Maximum zenith angle, default: 90 (horizon)
Returns:

  • tuple of NS, EW healpix indices
embers.tile_maps.beam_utils.healpix_cardinal_slices(nside, hp_map, za_max)

Slice healpix map along NS, EW axes, assuming it has been rotated by + 𝛑/4.

Parameters:
  • nside – Healpix nside
  • hp_map – Healpix imput data map
  • za_max – Maximum zenith angle
Returns:

  • tuple of NS, EW data slices of the imput healpix map, each of which contain the healpix indices and corresponding zenith angles
embers.tile_maps.beam_utils.nan_mad(good_ref_map)

Compute MAD of values in pixel of healpix map while ignoring nans.

Parameters:good_ref_map – Reference healpix map, output from good_ref_maps()
Returns:
  • ref_map_mad - Median Absolute Deviation of the input healpix map pixels
embers.tile_maps.beam_utils.map_slices(nside, good_map, za_max)

Slice healpix map along NS & EW axes returning Median and MAD arrays of the cardinal slices.

Parameters:
  • nside – Healpix nside
  • good_map – Healpix map, with pixels having distribution of values in lists
  • za_max – Maximum zenith angle
Returns:

  • tuple of NS & EW data, with each being a list of Median, MAD and Zenith angle arrays for the given cardianl slice of the healpix map
embers.tile_maps.beam_utils.poly_fit(x, y, data, order)

Fit polynominal of any order to data

Parameters:
  • x – Data array
  • y – Data array
  • data – Array of same size as x, y, but with nan’s which can be used to mask x,y
  • order – Degree of polynominal fit
embers.tile_maps.beam_utils.chisq_fit_gain(data=None, model=None)

Chisqaured fit the data and model.

Parameters:
  • data – A data array to be fit to a model. Typically this if rf map data being fit to the fee model
  • model – The model to which the data is being fit. Typically the fee beam model
Returns:

  • Single multiplicative gain value, which best fits data to model
embers.tile_maps.beam_utils.chisq_fit_test(data=None, model=None, offset=20)

chi-squared test for goodness of fit betweet model and data

Parameters:
  • data – A data array to be fit to a model. Typically this if rf map data being fit to the fee model
  • model – The model to which the data is being fit. Typically the fee beam model
  • offset – An integer offset by which data and model can be shifted away from their original 0 peak, which pvalues struggle with. Default=20
Returns:

  • pvalue - an indicator for goodess of fit
embers.tile_maps.beam_utils.plt_slice(fig=None, sub=(None, None, None), zen_angle=None, map_slice=None, map_error=None, model_slice=None, delta_pow=None, pow_fit=None, slice_label=None, model_label=None, xlabel=False, ylabel=True, xlim=[-82, 82], ylim=[-26, 12], title=None)

Plot a slice of measured beam map with errorbars fit the fee beam model. Subplot with residual power.

Parameters:
  • fig – Figure number
  • sub – Subplot position, tuple of matplotlib indices. Ex: (1, 1, 1)
  • zen_angle – Array of zenith angles
  • map_slice – Array of beam powers from slice of beam map
  • map_error – Array of errors on map_slice
  • model_slice – Slice of beam model at given zenith angles
  • delta_pow – Residual power between measured beam slice and model beam
  • pow_fit – Polynomial fit to residual power
  • slice_label – Label of measured beam slice
  • model_label – Label of beam model slice
  • xlabel – If True, plot X label of plot
  • ylabel – If True, plot Y label of plot
  • xlim – X limits on the plot. Default: [-82, 82]
  • ylim – Y limits on the plot. Default: [-26, 12]
  • title – Plot title
Returns:
embers.tile_maps.beam_utils.plot_healpix(data_map=None, fig=None, sub=None, title=None, vmin=None, vmax=None, cmap=None, cbar=True)

Yeesh do some healpix magic to plot the thing

Parameters:
  • data_map – Healpix input map to plot
  • fig – Figure number to use
  • sub – Matplotlib subplot syntax
  • title – Plot title
  • vmin – Colormap minimum
  • vmax – Colormap maximum
  • cmap – Matplotlib ListedColormap
  • cbar – If True, plot a colorbar
Returns:

  • Plot of healpix map

Referece Models

Convert FEKO models on the reference antennas into usable healpix maps

embers.tile_maps.ref_fee_healpix.create_model(nside, file_name=None)

Takes feko .ffe reference model, converts into healpix and smooths the response

Parameters:
  • nside – Healpix nside
  • file_name – Path to .ffe feko model of reference tiles
Returns:

  • tuple of (beam_response, theta_mesh, phi_mesh, power, theta)
embers.tile_maps.ref_fee_healpix.ref_healpix_save(nside, out_dir)

Save and plot reference healix maps

Parameters:
  • nside – Healpix nside
  • out_dir – Path to output directory
Returns:

  • Reference beam models have to .npz file in out_dir and plot of reference beam patterns

Tile Maps

A set of tools to project satellite passes onto a healpix map according to their ephemeris.

embers.tile_maps.tile_maps.check_pointing(timestamp, obs_point_json)

Check if timestamp is at MWA sweet-pointing 0, 2, 4, 41.

Parameters:
  • timestamp – time at which MWA pointing is to be checked
  • obs_point_json – Path to obs_point.json output from obs_pointings()
Returns:

  • Pointing of MWA at given timestamp
embers.tile_maps.tile_maps.plt_channel(out_dir, times, ref, tile, ref_noise, tile_noise, chan_num, sat_id, pointing, timestamp)

Plot power in a frequency channel of raw rf data, with various thresholds

Parameters:
  • out_dir – Output directory where plot will be saved
  • times – Time array
  • ref – Reference antenna rf power array
  • tile – MWA tile rf power array
  • ref_noise – Reference noise threshold
  • tile_noise – MWA tile noise threshold
  • chan_num – Channel Number
  • sat_id – Norad Cat ID
  • pointing – MWA sweet pointing of the observation
  • timestamp – Observation timestamp
Returns:

  • A plot of channel power with multiple power thresholds is saved to out_dir
embers.tile_maps.tile_maps.plt_fee_fit(times, mwa_fee_pass, mwa_pass_fit_raw, mwa_pass_fit, out_dir, point, timestamp, sat)

Plot data and model with goodness of fit p-value to visualize the degree of fit

Parameters:
  • times – Time array
  • mwa_fee_pass – MWA fee model slices according to satellite pass ephemeris
  • mwa_pass_fit_raw – Satellite rf data from MWA tiles
  • mwa_pass_fit – Satellite rf data from MWA tiles, fit to the fee model
  • out_dir – Output directory where plot will be saved
  • point – MWA sweet pointing of the observation
  • timestamp – Observation timestamp
  • sat_id – Norad Cat ID
Returns:

  • Plot comparing MWA fee model slice to satellite data, before and after gain power corrections
embers.tile_maps.tile_maps.rf_apply_thresholds(ali_file, chrono_file, sat_id, sat_chan, sat_thresh, noi_thresh, pow_thresh, point, plots, out_dir)

Apply power, noise thresholds to rf data arrays.

For a particular NORAD sat ID, crop a pair of ref, tile data arrays to when the satellite is above the horizon as indicated by it’s ephemeris. Given the frequency channel in which the satellite transmits, extract the channel power and return a coherent data set with ephemeris and tile power in a tuple

Parameters:
  • ali_file – PurePosixPath to a aligned ref, tile data file, output from save_aligned()
  • chrono_file – PurePosixPath to chrono ephemeris file, output from save_chrono_ephem()
  • sat_id – Norad catalogue ID
  • sat_chan – Transmission channel of given sat_id
  • sat_thresh – σ threshold to detect sats in the computation of rf data noise_floor. A good default is 1
  • noi_thresh – Noise Threshold: Multiples of MAD. 3 is a good default
  • pow_thresh – Peak power which must be exceeded for satellite pass to be considered
  • point – MWA sweet pointing of the observation
  • plots – if True create diagnostic plots
  • out_dir – Output directory where plot will be saved
Returns:

  • tuple of (ref_power, tile_power, alt, az, times) where all thresholds were met. If no data passes all thresholds 0 returned
embers.tile_maps.tile_maps.rfe_calibration(start_date, stop_date, tile_pair, sat_thresh, noi_thresh, pow_thresh, ref_model, fee_map, nside, obs_point_json, align_dir, chrono_dir, chan_map_dir, out_dir)

Calibrate the gain variations of a RF Explorers at high powers.

For a given pair of reference and MWA tile rf data files, within a time interval, critically characterize the gain variations of the RF Explorers, at high power, where they enter a non-linear regime. This is done my comparing satellite passes with corresponding slices of the MWA FEE beam model, and determining the power deficit.

Parameters:
  • start_date – Start date in YYYY-MM-DD-HH:MM format
  • stop_date – Stop date in YYYY-MM-DD-HH:MM format
  • tile_pair – A pair of reference and MWA tile names. Ex: [“rf0XX”, “S06XX”]
  • sat_thresh – σ threshold to detect sats in the computation of rf data noise_floor. A good default is 1
  • noi_thresh – Noise Threshold: Multiples of MAD. 3 is a good default
  • pow_thresh – Peak power which must be exceeded for satellite pass to be considered
  • ref_model – Path to reference feko model .npz file, output by ref_healpix_save()
  • fee_map – Path to MWA fee model .npz file, output by mwa_fee_model()
  • nside – Healpix nside
  • obs_point_json – Path to obs_pointings.json created by obs_pointings()
  • align_dir – Path to directory containing aligned rf data files, output from save_aligned()
  • chrono_dir – Path to directory containing chronological ephemeris data output from save_chrono_ephem()
  • chan_map_dir – Path to directory containing satellite frequency channel maps. Output from batch_window_map()
  • out_dir – Output directory where rfe calibration data will be saved as a json file
Returns:

  • Json file saved to out_dir which contains RF explorer calibration data.
embers.tile_maps.tile_maps.rfe_collate_cali(start_gain, stop_gain, rfe_cali_dir)

Collate RF Explorer gain calibration data from all MWA tile pairs, and plot a gain solution.

Parameters:
  • start_gain – Power at which RFE gain variations begin. Ex: -50dBm
  • stop_gain – Power at which RFE gain variations saturate. Ex: -30dBm
  • rfe_cali_dir – Path to directory which contains gain calibration data saved by rfe_calibration()
Returns:

  • Plot of global gain calibration solution and polynomial fit saved to .npz in the out_dir
embers.tile_maps.tile_maps.rfe_batch_cali(start_date, stop_date, start_gain, stop_gain, sat_thresh, noi_thresh, pow_thresh, ref_model, fee_map, nside, obs_point_json, align_dir, chrono_dir, chan_map_dir, out_dir, max_cores=None)

Batch gain calibrate all pairs of RF explorers and compute a global solution.

Parameters:
  • start_date – Start date in YYYY-MM-DD-HH:MM format
  • stop_date – Stop date in YYYY-MM-DD-HH:MM format
  • start_gain – Power at which RFE gain variations begin. Ex: -50dBm
  • stop_gain – Power at which RFE gain variations saturate. Ex: -30dBm
  • sat_thresh – σ threshold to detect sats in the computation of rf data noise_floor. A good default is 1
  • noi_thresh – Noise Threshold: Multiples of MAD. 3 is a good default
  • pow_thresh – Peak power which must be exceeded for satellite pass to be considered
  • ref_model – Path to reference feko model .npz file, output by ref_healpix_save()
  • fee_map – Path to MWA fee model .npz file, output by mwa_fee_model()
  • nside – Healpix nside
  • obs_point_json – Path to obs_pointings.json created by obs_pointings()
  • align_dir – Path to directory containing aligned rf data files, output from save_aligned()
  • chrono_dir – Path to directory containing chronological ephemeris data output from save_chrono_ephem()
  • chan_map_dir – Path to directory containing satellite frequency channel maps. Output from batch_window_map()
  • out_dir – Output directory where rfe calibration data will be saved as a json file
  • max_cores – Maximum number of cores to be used by this script. Default=None, which means that all available cores are used
Returns:

  • Json files saved to out_dir, contains RF explorer calibration data. Plot and data of global calibration solution saved too.
embers.tile_maps.tile_maps.project_tile_healpix(start_date, stop_date, tile_pair, sat_thresh, noi_thresh, pow_thresh, ref_model, fee_map, rfe_cali, nside, obs_point_json, align_dir, chrono_dir, chan_map_dir, out_dir, plots, rfe_cali_bool)

There be magic here. Project satellite RF data onto a sky healpix map.

For each satellite pass recorded by the MWA tiles and reference antennas, apply equation (1) from the beam paper to remove satellite beam effect and calculate a resultant cross-sectional slice of the MWA beam. Using satellite ephemeris data, project this beam slice onto a healpix map. This function also applies RFE gain correction using the gain solution created by rfe_collate_cali(). The resulting healpix map is saved to a .npz file in out_dir, with the data structured in nested dictionaries, which have the following structure.

map*.npz
├── mwa_map
│   └── pointings
│       └── satellites
│           └── healpix maps
├── ref_map
│   └── pointings
│       └── satellites
│           └── healpix maps
├── tile_map
│   └── pointings
│       └── satellites
│           └── healpix maps
└── time_map
    └── pointings
        └── satellites
            └── healpix maps

The highest level dictionary contains normalized mwa, reference, tile and time maps. Within each of these, there are dictionaries for each of the telescope pointings:0, 2, 4, 41. Within which there are dictionaries for each satellite norad ID, which contain a healpix map of data from one satellite, in one pointing. This structure may seem complicated, but is very useful for diagnostic purposes, and determining where errors in the final tile maps come from. The time maps contain the times of every data point added to the above maps.

Parameters:
  • start_date – Start date in YYYY-MM-DD-HH:MM format
  • stop_date – Stop date in YYYY-MM-DD-HH:MM format
  • tile_pair – A pair of reference and MWA tile names. Ex: [“rf0XX”, “S06XX”]
  • sat_thresh – σ threshold to detect sats in the computation of rf data noise_floor. A good default is 1
  • noi_thresh – Noise Threshold: Multiples of MAD. 3 is a good default
  • pow_thresh – Peak power which must be exceeded for satellite pass to be considered
  • ref_model – Path to reference feko model .npz file, output by ref_healpix_save()
  • fee_map – Path to MWA fee model .npz file, output by mwa_fee_model()
  • rfe_cali – Path to RFE gain calibration solution, output by rfe_collate_cali()
  • nside – Healpix nside
  • obs_point_json – Path to obs_pointings.json created by obs_pointings()
  • align_dir – Path to directory containing aligned rf data files, output from save_aligned()
  • chrono_dir – Path to directory containing chronological ephemeris data output from save_chrono_ephem()
  • chan_map_dir – Path to directory containing satellite frequency channel maps. Output from batch_window_map()
  • out_dir – Output directory where rfe calibration data will be saved as a json file
  • plots – If True, create a zillion diagnostic plots
  • rfe_cali_bool – Turn RFE calibration on or off. True/False
Returns:

  • Tile maps saved as .npz file to out_dir
embers.tile_maps.tile_maps.mwa_clean_maps(nside, tile_map_raw, out_dir)

Extract data from 18 good satellites and make the best possible MWA beam maps.

The maps created by project_tile_healpix() contains satellite data from all 72 satallites listed in embers.sat_utils.sat_list.norad_ids(). Most of these satellites happen to be outside the frequency band of this beam expt and all data from them is probably erroneous and mis-classified. Here, we extract a subset of the data belonging to a list of 18 satellites, identified for being active in the frequency band. Using this list of good_sats, significantly improves the quality of beam maps.

Parameters:
  • nside – Healpix nside
  • tile_map_raw – Path to a tile_map_raw.npz file created by project_tile_healpix()
  • out_dir – Output directory where rfe calibration data will be saved as a json file
Returns:

  • Clean MWA beam maps saved to out_dir
embers.tile_maps.tile_maps.plt_sat_maps(sat, out_dir)

Create healpix plots of the sky coverage of a satellite

Parameters:
  • sat – Norad ID of satellite
  • out_dir – The output directory which contains raw tile maps, and where the sat maps will be saved
Returns:

  • Healpix plots of satellite sky coverage at 4 pointings
embers.tile_maps.tile_maps.plt_clean_maps(clean_map, out_dir)

Plot healpix clean beam, error and count maps at all pointings.

Parameters:
  • clean_map – Path to a clean_map.npz data file created by mwa_clean_maps()
  • out_dir – The output directory where the clean maps will be saved
Returns:

  • Healpix plots of beam, error, count maps at 4 pointings
embers.tile_maps.tile_maps.tile_maps_batch(start_date, stop_date, sat_thresh, noi_thresh, pow_thresh, ref_model, fee_map, rfe_cali, nside, obs_point_json, align_dir, chrono_dir, chan_map_dir, out_dir, plots, rfe_cali_bool=True, max_cores=None)

Batch process satellite RF data to create clean beam maps and all intermediate data products.

Creates tile_maps_raw, which are tile maps with all possible raw data, sorted by satellite ID. Also creates clean_tile_maps which contain data from only the 18 satellites found to be consitently transmitting in the correct frequency band. Plots of satellite coverage and final clean beam maps are also saved to the out_dir.

Parameters:
  • start_date – Start date in YYYY-MM-DD-HH:MM format
  • stop_date – Stop date in YYYY-MM-DD-HH:MM format
  • start_gain – Power at which RFE gain variations begin. Ex: -50dBm
  • stop_gain – Power at which RFE gain variations saturate. Ex: -30dBm
  • sat_thresh – σ threshold to detect sats in the computation of rf data noise_floor. A good default is 1
  • noi_thresh – Noise Threshold: Multiples of MAD. 3 is a good default
  • pow_thresh – Peak power which must be exceeded for satellite pass to be considered
  • ref_model – Path to reference feko model .npz file, output by ref_healpix_save()
  • fee_map – Path to MWA fee model .npz file, output by mwa_fee_model()
  • rfe_cali – Path to RFE gain calibration solution, output by rfe_collate_cali()
  • nside – Healpix nside
  • obs_point_json – Path to obs_pointings.json created by obs_pointings()
  • align_dir – Path to directory containing aligned rf data files, output from save_aligned()
  • chrono_dir – Path to directory containing chronological ephemeris data output from save_chrono_ephem()
  • chan_map_dir – Path to directory containing satellite frequency channel maps. Output from batch_window_map()
  • out_dir – Output directory where rfe calibration data will be saved as a json file
  • plots – If True, create a zillion diagnostic plots for the project_tile_healpix() stage
  • rfe_cali_bool – Turn RFE calibration on or off. Default=True.
  • max_cores – Maximum number of cores to be used by this script. Default=None, which means that all available cores are used

Null Tests

A set of tools to perform null tests on reference rf data and reference beam models

embers.tile_maps.null_test.good_ref_maps(nside, map_dir, tile_pair)

Collates reference data from 18 good satellites into a good_ref_map

Parameters:
  • nside – Healpix nside
  • map_dir – Path to directory with tile_maps_raw, created by project_tile_healpix()
  • tile_pair – List of a pair of mwa tile and reference names. Ex: [“S35XX”, “rf0XX”]
Returns:

  • good_ref_map healpix map, with each pixel of the healpix map containing an array of values from all satellite passes within the pixel
embers.tile_maps.null_test.plt_null_test(fig=None, sub=(None, None, None), zen_angle=None, del_pow=None, del_err=None, del_beam=None, del_fit=None, null_label=None, beam_label=None, fit_label=None, ylabel=True, title=None)

Plot null test between two corresponding slices of reference beam maps

Parameters:
  • fig – Figure number
  • sub – Subplot position, tuple of matplotlib indices. Ex: (1, 1, 1)
  • zen_angle – Array of zenith angles
  • delta_pow – Null test power b/w corresponding slices of reference beam maps
  • del_err – Errors on del_pow (MAD)
  • del_beam – Difference b/w ref beam models, should be zero is both references have the same beam model
  • del_fit – Polynomial fit to residual power
  • null_label – Label of null test data
  • beam_label – Label of beam slice
  • fit_label – Label of del_fit data
  • ylabel – If True, plot Y label of plot
  • title – Plot title
Returns:
embers.tile_maps.null_test.null_test(nside, za_max, ref_model, map_dir, out_dir)

Plot all null tests for reference beam maps

Parameters:
  • nside – Healpix nside
  • za_max – Maximum zenith angle
  • ref_model – Path to feko reference model, saved by ref_healpix_save()
  • map_dir – Path to directory with tile_maps_raw, created by project_tile_healpix()
  • out_dir – Output directory where null test plots will be saved
Returns:

  • Null test plot saved to out_dir
  • Reference residuals saved to out_dir

Compare Beams

A set of tools to compare measured MWA beam maps with FEE models

embers.tile_maps.compare_beams.beam_slice(nside, tile_map, fee_map, out_dir)

Compare slices of measured beam maps and FEE models.

NS & EW slices of measured MWA beam maps are compared to corresponding slices of FEE models. Complete sky maps are plotted to display power gradients across the beam.

Parameters:
  • nside – Healpix nside
  • tile_map – Clean MWA tile map created by mwa_clean_maps()
  • fee_map – MWA FEE model created my mwa_fee()
  • out_dir – Path to output directory where diagnostic plots will be saved
embers.tile_maps.compare_beams.batch_compare_beam(nside, fee_map, map_dir, out_dir, max_cores=None)

Batch compare multiple beam maps

Parameters:
  • nside – Healpix nside
  • fee_map – MWA FEE model created my mwa_fee()
  • map_dir – Path to dir with clean MWA tile maps created by mwa_clean_maps()
  • out_dir – Path to output directory where diagnostic plots will be saved
  • max_cores – Maximum number of cores to be used by this script. Default=None, which means that all available cores are used