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)

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)

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.

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_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)

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.

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.

Parameters:

• agasc_stats –

• filename –

• 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: