Magnitude Supplement API

Functions to estimate observed ACA magnitudes

exception agasc.supplement.magnitudes.mag_estimate.MagStatsException(msg='', agasc_id=None, obsid=None, mp_starcat_time=None, **kwargs)

property failed

Check if the exception is a failure.

Returns:

bool

agasc.supplement.magnitudes.mag_estimate.add_obs_info(telem, obs_stats)

Add observation-specific information to a telemetry table (ok flag, and outlier flag).

This is done as part of get_agasc_id_stats. It is a convenience for writing reports.

Parameters:

• telem – list of tables One or more telemetry tables (potentially many observations)

• obs_stats – table The result of calc_obs_stats.

Returns:

agasc.supplement.magnitudes.mag_estimate.calc_obs_stats(telem)

Get summary magnitude statistics for an observation.

Parameters:

telem – dict Dictionary with telemetry (output of get_telemetry)

Returns:

dict dictionary with stats

agasc.supplement.magnitudes.mag_estimate.get_agasc_id_stats(agasc_id, obs_status_override=None, tstop=None, no_telem_time=<Quantity 14. d>)

Get summary magnitude statistics for an AGASC ID.

Parameters:

• agasc_id – int

• obs_status_override – dict. Dictionary overriding the OK flag for specific observations. Keys are (OBSID, AGASC ID) pairs, values are dictionaries like {‘obs_ok’: True, ‘comments’: ‘some comment’}

• tstop – cxotime-compatible timestamp Only entries in catalogs.STARS_OBS prior to this timestamp are considered.

• no_telem_time – astropy Quantity Time interval to consider for discarding recent observations with no telemetry.

Returns:

dict dictionary with stats

agasc.supplement.magnitudes.mag_estimate.get_droop_systematic_shift(magnitude)

Difference between the magnitude determined from DC-subtracted image telemetry and the catalog ACA magnitude.

The magnitude shift is time-independent. It depends only on the catalog magnitude and is zero for bright stars. More details in the droop notebook:

Parameters:

magnitude – float Catalog ACA magnitude

Returns:

agasc.supplement.magnitudes.mag_estimate.get_mag_from_img(slot_data, t_start, ok=True)

Vectorized estimate of the magnitude from mica archive image telemetry data.

Parameters:

• slot_data – astropy.Table. The data returned by mica.archive.aca_l0.get_slot_data

• t_start – The starting time of the observation (by convention, the starcat time)

• ok – np.array. An boolean array with the same length as slot_data. Only magnitudes for entries with ok=True are calculated. The rest are set to MAX_MAG.

Returns:

agasc.supplement.magnitudes.mag_estimate.get_multi_obs_stats(star_obs, telem=None, obs_status_override=None)

Get summary magnitude statistics for an AGASC ID.

This function deals with several errors that can occur, and assigns various success/error flags to each observation:

• obs_ok: OK observations are considered OK based on criteria listed below, or are have status == 0 in obs_status_override.

• obs_suspect: observations are considered suspect if they have status > 1 in obs_status_override, and do not fulfill the criteria for being OK.

• obs_fail: observations where there was an exception getting the telemetry or calculating the stats.

• no_telem: observations where there was an exception getting the telemetry.

Criteria for an OK observation:

• n > 10, where n is the total number of telemetry entries in the observation.

• f_mag_est_ok > 0.3, where f_mag_est_ok is the fraction of telemetry entries with (AOACASEQ==KALM & AOACIIR==OK & AOPCADMD==NPNT & AOACFCT==TRAK).

• lf_variability_100s < 1, where lf_variability_100s is the largest change in the magnitude smoothed using a 100s rolling window.

Parameters:

• star_obs – Table Table of star observations.

• telem – list List of telemetry tables for each observation. Must be in the same order as star_obs. This should generally be the result of get_telemetry_by_observations.

• obs_status_override – dict. Dictionary overriding the OK flag for specific observations. Keys are (OBSID, AGASC ID) pairs, values are dictionaries like {‘obs_ok’: True, ‘comments’: ‘some comment’}

Returns:

dict dictionary with stats

agasc.supplement.magnitudes.mag_estimate.get_obs_stats(obs, telem=None)

Get summary magnitude statistics for an observation.

Parameters:

• obs – astropy.table.Row a “star observation” row. From the join of starcheck catalog and starcat commands It must have the following columns: ‘agasc_id’, ‘mp_starcat_time’, ‘mag’, ‘slot’

• telem – dict Dictionary with telemetry (output of get_telemetry)

Returns:

dict dictionary with stats

agasc.supplement.magnitudes.mag_estimate.get_responsivity(time)

ACA magnitude response over time.

This was estimated with bright stars that were observed more than a hundred times during the mission. More details in the responsivity notebook:

Parameters:

time – float Time in CXC seconds

Returns:

agasc.supplement.magnitudes.mag_estimate.get_star_position(star, telem)

Residuals for a given AGASC record at a given slot/time.

Parameters:

• star – Table Row of one AGASC entry

• telem – table Table with columns AOATTQT1, AOATTQT2, AOATTQT3, AOATTQT4.

Returns:

agasc.supplement.magnitudes.mag_estimate.get_telemetry(obs)

Get all telemetry relevant for the magnitude estimation task.

This gets: - AOACASEQ - AOPCADMD - AOACMAG (ACA estimated magnitude) - AOACIIR (ACA ionizing radiation flag) - AOACISP (ACA saturated pixel flag)

MSIDs are renamed to remove the slot number. This assumes all MSIDs occur at the same times (they do)

Parameters:

obs – astropy.table.Row It must have the following columns: ‘agasc_id’, ‘mp_starcat_time’, ‘mag’, ‘slot’

Returns:

dict

agasc.supplement.magnitudes.mag_estimate.get_telemetry_by_agasc_id(agasc_id, obsid=None, ignore_exceptions=False, as_table=True)

Get all telemetry relevant for the magnitude estimation, given an AGASC ID.

This gets all observations of a given star, it gets the telemetry for each, and stacks them.

Parameters:

• agasc_id – int

• obsid – int (optional)

• ignore_exceptions – bool if True, any exception is ignored. Useful in some cases. Default is False.

• as_table – bool if True, the telemetry is returned as an astropy Table. If False, it is returned as a list of dicts, one per observation. Default is True.

Returns:

dict

agasc.supplement.magnitudes.mag_estimate.rolling_mean(t, f, window, selection=None)

Calculate the rolling mean of the ‘f’ array, using a centered square window in time.

Parameters:

• t – np.array the time array.

• f – np.array the array to average.

• window – float the window size (in the same units as the time array).

• selection – np.array An optional array of bool.

Returns:

np.array An array with the same type and shape as ‘f’

agasc.supplement.magnitudes.update_mag_supplement.do(start, stop, output_dir, agasc_ids=None, report=False, reports_dir=None, report_date=None, multi_process=False, include_bad=False, dry_run=False, no_progress=None, email='')

Parameters:

• start – cxotime.CxoTime Start time. Only stars with at least one observation between start/stop are considered.

• stop – cxotime.CxoTime Stop time. Only stars with at least one observation between start/stop are considered.

• output_dir – pathlib.Path Directory where to place all output.

• agasc_ids – list List of AGASC IDs. Otional. If not given, all observations within start/stop are used.

• report – bool Generate an HTML report.

• reports_dir – pathlib.Path Directory where to write reports.

• report_date – cxotime.CxoTime The report date (report_date.date[:8] will be the report directory name)

• multi_process – bool Run on mulyiple processes.

• include_bad – bool Consider stars that are in the ‘bad’ supplement table.

• dry_run – bool Only parse options and not actually run the magnitude estimates

• no_progress – bool Hide progress bar

• email – str

Returns:

agasc.supplement.magnitudes.update_mag_supplement.get_agasc_id_stats(agasc_ids, obs_status_override=None, tstop=None, no_progress=None)

Call mag_stats.get_agasc_id_stats for each AGASC ID

Parameters:

• agasc_ids – list

• obs_status_override – dict. Dictionary overriding the OK flag for specific observations. Keys are (OBSID, AGASC ID) pairs, values are dictionaries like {‘obs_ok’: True, ‘comments’: ‘some comment’}

• tstop – cxotime-compatible timestamp Only observations prior to this timestamp are considered.

Returns:

astropy.table.Table, astropy.table.Table, list obs_stats, agasc_stats, fails

agasc.supplement.magnitudes.update_mag_supplement.get_agasc_id_stats_pool(agasc_ids, obs_status_override=None, batch_size=100, tstop=None, no_progress=None)

Call update_mag_stats.get_agasc_id_stats multiple times using a multiprocessing.Pool

Parameters:

• agasc_ids – list

• obs_status_override – dict. Dictionary overriding the OK flag for specific observations. Keys are (OBSID, AGASC ID) pairs, values are dictionaries like {‘obs_ok’: True, ‘comments’: ‘some comment’}

• batch_size – int

• tstop – cxotime-compatible timestamp Only observations prior to this timestamp are considered.

Returns:

astropy.table.Table, astropy.table.Table, list obs_stats, agasc_stats, fails, failed_jobs

agasc.supplement.magnitudes.update_mag_supplement.level0_archive_time_range()

Return the time range covered by mica archive aca_l0 files.

Returns:

tuple of CxoTime

agasc.supplement.magnitudes.update_mag_supplement.update_mag_stats(obs_stats, agasc_stats, fails, outdir='.')

Update the mag_stats catalog.

I currently save three files: - mag_stats_agasc.fits with stats for each AGASC ID - mag_stats_obsid.fits with stats for each OBSID - mag_stats_fails.pkl with a list of failures

Parameters:

• obs_stats

• agasc_stats

• fails

• outdir

Returns:

agasc.supplement.magnitudes.update_mag_supplement.update_supplement(agasc_stats, filename, include_all=True, d_mag_threshold=0.01)

Update the magnitude table of the AGASC supplement.

This function returns two list of stars: new stars and updated stars, which are stars that are not in the supplement already, and stars thar are in the supplement before this update. Note that “updated” stars are not necessarily updated in the supplement. If a star has a small change in magnitude or magnitude uncertainty (less than d_mag_threshold), its magnitude is not updated in the supplement, but it is still included in the “updated” stars list.

This function compares the last_obs_time of the stars in the supplement and in agasc_stats. If last_obs_time is the same, then the star is not updated in the supplement (and not included in the “updated” stars list), even if there is a change in magnitude. This can happen if all observations since last_updated are excluded or failed.

Parameters:

• agasc_stats – astropy.table.Table The table with the new stats for each AGASC ID. It must include the columns in MAGS_DTYPE.

• filename – str or pathlib.Path The filename of the supplement to update.

• include_all – bool if True, all OK entries are included in supplement. if False, only OK entries marked ‘selected_*’

• d_mag_threshold – float If the absolute difference between the new and the current mag_aca is less than this value, mag_aca is not updated. Note that last_obs_time is always updated.

Returns:

new_stars: list of AGASC IDs that are new in the supplement. updated_stars: list of AGASC IDs that are already in the supplement.