sourcetools

sourcetools.density module

sourcetools.temperature module

sourcetools.entropy module

sourcetools.mass module

sourcetools.match module

xga.sourcetools.match.census_match(telescope=None, obs_ids=None)[source]

Returns XGA census entries (with ObsID, ra, and dec) that are not completely blacklisted, for the specified telescope(s). This is an extremely simple function, and could be largely replicated by just working with the CENSUS directly - however this does check against the blacklist, and will return things in the same style as the ‘proper’ matching functions.

The user can also pass a list of strings (or a dictionary of lists of strings in the case of multiple telescopes being considered) to limit the ObsIDs from the census that are to be considered.

Parameters:

telescope (str/List[str]) – The telescope censuses that should be searched for matches, the default is None, in which case all telescopes that have been set up with this installation of XGA will be used. The user may pass a single telescope name, or a list of telescope names, to control which are used.
obs_ids (List[str]/dict) – ObsIDs that are to be considered

Returns:

A dictionary of dataframes of matching ObsIDs, where the dictionary keys correspond to different telescopes. The second return is structured exactly the same, but represents observations that were completely excluded in the blacklist.

Return type:

Tuple[dict, dict]

xga.sourcetools.match.separation_match(src_ra, src_dec, distance=None, telescope=None, num_cores=1, show_warnings=True, return_flat=False)[source]

Returns XGA census entries (with ObsID, ra, and dec) that match to the input coordinates (either a single coordinate or a set). This is done for a set of telescopes (or a single telescope), and a match is made by the source coordinates being within specified search distances for the different telescopes.

Parameters:

src_ra (float/np.ndarray) – RA coordinate(s) of the source(s), in degrees. To find matches for multiple coordinate pairs, pass an array.
src_dec (float/np.ndarray) – DEC coordinate(s) of the source(s), in degrees. To find matches for multiple coordinate pairs, pass an array.
distance (Quantity/dict) – The radius to search for observations within, the default is None in which case standard search distances for different telescopes are used. The user may pass a single Quantity to use for all telescopes, a dictionary with keys corresponding to ALL or SOME of the telescopes specified by the ‘telescope’ argument. In the case where only SOME of the telescopes are specified in a distance dictionary, the default XGA values will be used for any that are missing.
telescope (str/List[str]) – The telescope censuses that should be searched for matches, the default is None, in which case all telescopes that have been set up with this installation of XGA will be used. The user may pass a single telescope name, or a list of telescope names, to control which are used.
num_cores (int) – The number of cores to use, default is set to 90% of system cores. This is only relevant if multiple coordinate pairs are passed.
show_warnings (bool) – If False, then any warnings that occur will not be displayed. Default is True.
return_flat (bool) – If True, then a flat DataFrame will be returned instead of a sparse dictionary or list of dictionaries. Default is False.

Returns:

A list of dictionaries (or single dictionary for one coordinate) of dataframes of matching ObsIDs, where each dictionary corresponds to an input RA-Dec (in the same order), and the dictionary keys correspond to different telescopes. The second return is structured exactly the same, but represents observations that were completely excluded in the blacklist.

Return type:

Tuple[Union[dict, List[dict], pd.DataFrame], Union[dict, List[dict], pd.DataFrame]]

xga.sourcetools.match.on_detector_match(src_ra, src_dec, distance=None, telescope=None, num_cores=1)[source]

A matching function that checks whether supplied coordinates lie on a detector by using exposure maps to determine the exposure time at the supplied coordinates. Of course, this means that we need an idea of which observations should be checked, so we first run the ‘separation_match’ function.

Parameters:

src_ra (float/np.ndarray) – RA coordinate(s) of the source(s), in degrees. To find matches for multiple coordinate pairs, pass an array.
src_dec (float/np.ndarray) – Dec coordinate(s) of the source(s), in degrees. To find matches for multiple coordinate pairs, pass an array.
distance (Quantity/dict) – As this function calls ‘separation_match’, we have to supply the distance to search for observations within, the default is None in which case standard search distances for different telescopes are used. The user may pass a single Quantity to use for all telescopes, a dictionary with keys corresponding to ALL or SOME of the telescopes specified by the ‘telescope’ argument. In the case where only SOME of the telescopes are specified in a distance dictionary, the default XGA values will be used for any that are missing.
telescope (str/List[str]) – The telescope censuses that should be searched for matches, the default is None, in which case all telescopes that have been set up with this installation of XGA will be used. The user may pass a single telescope name, or a list of telescope names, to control which are used.
num_cores (int) – The number of cores to use, default is set to 90% of system cores. This is only relevant if multiple coordinate pairs are passed.

Returns:

For a single input coordinate, a dictionary (with telescope names as keys) of numpy arrays of ObsID(s) will be returned. For multiple input coordinates an array of dictionaries (with telescope names as keys) of arrays of ObsID(s) and None values will be returned. Each entry corresponds to the input coordinate array, a None value indicates that the coordinate did not fall on an telescope observation at all.

Return type:

Union[dict, np.ndarray]

xga.sourcetools.match.region_match(src_ra, src_dec, src_type, distance=None, telescope=None, num_cores=1)[source]

A function which, if XGA has been configured with access to pre-generated region files, will search for region matches for a set of source coordinates passed in by the user. A region match is defined as when a source coordinate falls within a source region with a particular colour (largely used to represent point vs extended) - the type of region that should be matched to can be defined using the src_type argument.

The separation_match function will be run before the source matching process, to narrow down the sources which need to have the more expensive region matching performed, as well as to identify which ObsID(s) should be examined for each source.

Parameters:

src_ra (float/np.ndarray) – RA coordinate(s) of the source(s), in degrees. To find matches for multiple coordinate pairs, pass an array.
src_dec (float/np.ndarray) – Dec coordinate(s) of the source(s), in degrees. To find matches for multiple coordinate pairs, pass an array.
src_type (str/List[str]) – The type(s) of region that should be matched to. Pass either ‘ext’ or ‘pnt’ or a list containing both.
distance (Quantity/dict) – The distance to search for observations within, the default is None in which case standard search distances for different telescopes are used. The user may pass a single Quantity to use for all telescopes, a dictionary with keys corresponding to ALL or SOME of the telescopes specified by the ‘telescope’ argument. In the case where only SOME of the telescopes are specified in a distance dictionary, the default XGA values will be used for any that are missing.
telescope (str/List[str]) – The telescope censuses that should be searched for matches, the default is None, in which case all telescopes that have been set up with this installation of XGA will be used. The user may pass a single telescope name, or a list of telescope names, to control which are used.
num_cores (int) – The number of cores that can be used for the matching process.

Returns:

An array the same length as the sets of input coordinates (ordering is the same). If there are no matches for a source then the element will be None, if there are matches then the element will be a dictionary, with top key(s) being telescope names, lower level keys being ObsID(s), and the values being a list of region objects (or more likely just one object).

Return type:

np.ndarray

xga.sourcetools.match.simple_xmm_match(src_ra, src_dec, distance=<Quantity 30. arcmin>, num_cores=1)[source]

Returns XMM ObsIDs within a given distance from the input ra and dec values.

Parameters:

src_ra (float/np.ndarray) – RA coordinate(s) of the source(s), in degrees. To find matches for multiple coordinate pairs, pass an array.
src_dec (float/np.ndarray) – DEC coordinate(s) of the source(s), in degrees. To find matches for multiple coordinate pairs, pass an array.
distance (Quantity) – The distance to search for XMM observations within, default should be able to match a source on the edge of an observation to the centre of the observation.
num_cores (int) – The number of cores to use, default is set to 90% of system cores. This is only relevant if multiple coordinate pairs are passed.

Returns:

A dataframe containing ObsID, RA_PNT, and DEC_PNT of matching XMM observations, and a dataframe containing information on observations that would have been a match, but that are in the blacklist.

Return type:

Tuple[Union[DataFrame, List[DataFrame]], Union[DataFrame, List[DataFrame]]]

sourcetools.misc module

xga.sourcetools.misc.nh_lookup(coord_pair)[source]

Uses HEASoft to lookup hydrogen column density for given coordinates.

Parameters:: coord_pair (Quantity) – An astropy quantity with RA and DEC of interest.
Returns:: Average and weighted average nH values.
Return type:: Quantity

xga.sourcetools.misc.rad_to_ang(rad, z, cosmo=LambdaCDM(name=None, H0=<Quantity 70. km / (Mpc s)>, Om0=0.3, Ode0=0.7, Tcmb0=<Quantity 0. K>, Neff=3.04, m_nu=None, Ob0=0.0))[source]

Converts radius in length units to radius on sky in degrees.

Parameters:

rad (Quantity) – Radius for conversion.
cosmo (Cosmology) – An instance of an astropy cosmology, the default is a flat LambdaCDM concordance model.
z (float) – The redshift of the source.

Returns:

The radius in degrees.

Return type:

Quantity

xga.sourcetools.misc.ang_to_rad(ang, z, cosmo=LambdaCDM(name=None, H0=<Quantity 70. km / (Mpc s)>, Om0=0.3, Ode0=0.7, Tcmb0=<Quantity 0. K>, Neff=3.04, m_nu=None, Ob0=0.0))[source]

The counterpart to rad_to_ang, this converts from an angle to a radius in kpc.

Parameters:

ang (Quantity) – Angle to be converted to radius.
cosmo (Cosmology) – An instance of an astropy cosmology, the default is a flat LambdaCDM concordance model.
z (float) – The _redshift of the source.

Returns:

The radius in kpc.

Return type:

Quantity

xga.sourcetools.misc.name_to_coord(name)[source]

Takes a standard format name (e.g. XMMXCS J041853.9+555333.7) and returns RA and DEC in degrees. The sexagesimal coordinates are parsed from the string and converted to decimal degrees.

Parameters:: name (str) – Standard format name of an object.
Returns:: An astropy quantity containing RA and DEC in degrees.
Return type:: Quantity

xga.sourcetools.misc.coord_to_name(coord_pair, survey=None)[source]

This was originally just written in the init of BaseSource, but I figured I should split it out into its own function really. This will take a coordinate pair, and optional survey name, and spit out an object name in the standard format.

Parameters:

coord_pair (Quantity) – The coordinate pair for which we want to generate a name.
survey (str) – The name of the survey to prefix the name with, default is None.

Returns:

Source name based on coordinates.

Return type:

str

xga.sourcetools.misc.model_check(sources, model)[source]

Very simple function that checks if a passed set of models is appropriately structured for the number of sources that have been passed. There is no reason a user would need this directly, it’s only here as these checks have to be performed in multiple places in sourcetools.

Parameters:

sources (BaseSource/BaseSample/List[BaseSource]) – The source(s) for which we are checking models.
model (str/List[str]/BaseModel1D/List[BaseModel1D]) – The model(s).

Returns:

A list of model instances, or names of models.

Return type:

Union[List[BaseModel1D], List[str]]

sourcetools.stack module

sourcetools.deproj module

xga.sourcetools.deproj.shell_ann_vol_intersect(shell_radii, ann_radii)[source]

This function calculates the volume intersection matrix of a set of circular annuli and a set of spherical shells. It is assumed that the annuli and shells have the same x and y origin. The intersection is derived using simple geometric considerations, have a look in the appendix of DOI 10.1086/300836.

Parameters:

shell_radii (ndarray/Quantity) – The radii of the spherical shells.
ann_radii (ndarray/Quantity) – The radii of the circular annuli (DOES NOT need to be the same length as shell_radii).

Returns:

A 2D array containing the volumes of intersections between the circular annuli defined by i_ann and o_ann, and the spherical shells defined by i_sph and o_sph. Annular radii are along the ‘x’ axis and shell radii are along the ‘y’ axis.

Return type:

Union[np.ndarray, Quantity]

xga.sourcetools.deproj.shell_volume(inn_radius, out_radius)[source]

Silly little function that calculates the volume of a spherical shell with inner radius inn_radius and outer radius out_radius.

Parameters:

inn_radius (Quantity/np.ndarray) – The inner radius of the spherical shell.
out_radius (Quantity/np.ndarray) – The outer radius of the spherical shell.

Returns:

The volume of the specified shell

Return type:

Union[Quantity, np.ndarray]