Module: known_object_filters#
- class kbmod.filters.known_object_filters.KnownObjsMatcher(table, obstimes, matcher_name, sep_thresh=1.0, time_thresh_s=600.0, mjd_col='mjd_mid', ra_col='RA', dec_col='DEC', name_col='Name')[source]#
A class which ingests an astopy table of object data expected to be found in the dataset searched by KBMOD (either real objects or inserted synthetic fakes) and provides methods for matching to the observations in a given set of KBMOD Results.
It allows for configuration of how the matching is done, including the maximum separation in arcseconds between a known object and a result to be considered a match, the maximum time separation in seconds between a known object and the observation used in a KBMOD result.
In addition to modifying a KBMOD Results table to include columns for matched known objects, it also provides methods for filtering the results based on the matches. This includes marking observations that matched to known objects as invalid, and filtering out results that matched to known objects by either the minimum number of observations that matched to that known object or the proportion of observations from the catalog for that known object that were matched to a given result.
Methods
filter_matches(result_data, match_col)Filter out the results table to only include results that did not match to any known objects.
get_dec(ko_idx)Returns the DEC of the known object at a given index.
get_mjd(ko_idx)Returns the MJD of the known object at a given index.
get_name(ko_idx)Returns the name of the known object at a given index.
get_ra(ko_idx)Returns the RA of the known object at a given index.
get_recovered_objects(result_data, match_col)Get the set of objects that were recovered or missed in the results.
mark_matched_obs_invalid(result_data[, ...])Mark observations that matched to known objects as invalid, by default dropping results that no longer have any valid observations.
match(result_data, wcs)This function takes a list of results and matches them to known objects.
match_min_obs_col(min_obs)A colummn name for objects that matched results based on the minimum number of observations.
match_on_min_obs(result_data, min_obs)Create a column corresponding to the known objects that were matched to a result based on the minimum number of observations that matched to that known object.
match_on_obs_ratio(result_data, obs_ratio)Create a column corresponding to the known objects that were matched to a result based on the proportion of observations that matched to that known object within the catalog.
Returns a SkyCoord representation of the known objects.
match_obs_ratio_col
- filter_matches(result_data, match_col)[source]#
Filter out the results table to only include results that did not match to any known objects.
- Parameters:
- result_dataResults
The results to filter.
- match_colstr
The name of the column in the results table that contains the matched objects.
- Returns:
- Results
The modified Results object returned for chaining.
- Raises:
- ValueError
If the match_col is not present in the results table.
- get_recovered_objects(result_data, match_col)[source]#
Get the set of objects that were recovered or missed in the results.
For our purposes, a recovered object is one that was matched to a result based on the matching column of choice in the results table and a missing object are objects in the catalog that were not matched. Note that not all catalogs may be constructed in a way where all objects could be spatially present and recoverable in the results.
- Parameters:
- result_dataResults
The results to filter.
- match_colstr
The name of the column in the results table that contains the matched objects.
- Returns:
- set, set
A tuple of sets where the first set contains the names of objects that were recovered and the second set contains the names objects that were missed
- Raises:
- ValueError
If the match_col is not present in the results table
- mark_matched_obs_invalid(result_data, drop_empty_rows=True)[source]#
Mark observations that matched to known objects as invalid, by default dropping results that no longer have any valid observations.
Note that a given result can match to multiple objects, and that we expect the Results table to have a column with name corresponding to self.matcher_name that contains which observations were matched to each known object.
- Parameters:
- result_dataResults
The results to filter.
- drop_empty_rowsbool, optional
If True, drop rows that have no valid observations after filtering. Default is True.
- Returns:
- Results
The modified Results object returned for chaining.
- match(result_data, wcs)[source]#
This function takes a list of results and matches them to known objects.
This modifies the Results table by adding a column with name self.matcher_name that provides for each result a dictionary mapping the names of known objects (as defined by the catalog’s name_col) to a boolean array indicating which observations in the result matched to that known object. Note that depending on the matching parameters, a result can match to multiple known objects from the catalog even at the same observation time.
So for a dataset with 5 observations a result matching to 2 known objects, A and B, might have an entry in the column self.matcher_name like: ```{
“A”: [True, True, False, False, False], “B”: [False, False, False, True, True],
}```
- Parameters:
- result_data: `Results`
The set of results to filter. This data gets modified directly by the filtering.
- wcs: `astropy.wcs.WCS`
The common WCS object for the stack of images.
- Returns:
- Results
The modified Results object returned for chaining.
- match_min_obs_col(min_obs)[source]#
A colummn name for objects that matched results based on the minimum number of observations.
- match_on_min_obs(result_data, min_obs)[source]#
Create a column corresponding to the known objects that were matched to a result based on the minimum number of observations that matched to that known object. Note that the ratio is calculated based on the total number of observations that were within time_sep_thresh_s of the obstimes we are matching to. Observations outside of that time range are not considered.
Note that a given result can match to multiple objects.
- Parameters:
- result_dataResults
The results to filter.
- min_obsint
The minimum number of observations within a KBMOD result that must match to a known object for that result to be considered a match.
- Returns:
- Results
The modified Results object returned for chaining.
- match_on_obs_ratio(result_data, obs_ratio)[source]#
Create a column corresponding to the known objects that were matched to a result based on the proportion of observations that matched to that known object within the catalog.
Note that a given result can match to multiple objects.
- Parameters:
- result_dataResults
The results to filter.
- obs_ratiofloat
The minimum ratio of observations within a KBMOD result that must match to the total observations within our catalog of known objects for that result to be considered a match. Must be within the range [0, 1].
- Returns:
- Results
The modified Results object returned for chaining.
- Raises:
- ValueError
If obs_ratio is not within the range [0, 1].