lightcurvelynx.math_nodes.ra_dec_sampler

Samplers used for generating (RA, dec) coordinates.

Classes

`UniformRADEC`	A FunctionNode that uniformly samples (RA, dec) over a sphere,
`ObsTableRADECSampler`	A FunctionNode that randomly samples RA and dec (and any extra columns) from
`ObsTableUniformRADECSampler`	A FunctionNode that samples RA and dec uniformly from the area covered
`ApproximateMOCSampler`	A FunctionNode that samples RA and dec (approximately) from the coverage of
`CatalogRADECSampler`	A FunctionNode that randomly samples RA and dec from a given catalog of objects.
`MilkyWayCoordSampler`	A FunctionNode that samples (RA, dec, distance) positions according to a

Module Contents

class UniformRADEC(outputs=None, seed=None, use_degrees=True, **kwargs)[source]

Bases: lightcurvelynx.math_nodes.np_random.NumpyRandomFunc

A FunctionNode that uniformly samples (RA, dec) over a sphere,

use_degrees[source]

The default return unit. If True returns samples in degrees. Otherwise, if False, returns samples in radians.

Type:: bool

use_degrees = True[source]

compute(graph_state, rng_info=None, **kwargs)[source]

Return the given values.

Parameters:

graph_state (GraphState) – An object mapping graph parameters to their values. This object is modified in place as it is sampled.
rng_info (numpy.random._generator.Generator, optional) – A given numpy random number generator to use for this computation. If not provided, the function uses the node’s random number generator.
**kwargs (dict, optional) – Additional function arguments.

Returns:

results – The result of the computation. This return value is provided so that testing functions can easily access the results.

Return type:

any

class ObsTableRADECSampler(data, *, extra_cols=None, radius=None, dedup_threshold=0.0, **kwargs)[source]

Bases: lightcurvelynx.math_nodes.given_sampler.TableSampler

A FunctionNode that randomly samples RA and dec (and any extra columns) from around given data. This node is used for both sampling from a list of pointings (where the radius is the field of view) or sampling from a list of true objects. This sampling strategy will return a visit-weighted distribution, so areas of the sky that are observed more often will be sampled more often.

Parameters:

data (ObsTable, Pandas DataFrame, NestedFrame, or dict) – The data to use for sampling. Must contain ‘ra’ and ‘dec’ columns.
extra_cols (list of str, optional) – A list of extra column names to include in the sampling. Default: None
radius (float, optional) – The sampling radius around the given points. If the points represent the center of a pointing, this is the radius of the field of view in degrees. If the points represent exact true objects, this can be a noise factor. Use 0.0 to return the exact given points. If None and data is an ObsTable, uses the value from the ObsTable. Default: None
dedup_threshold (float, optional) – The deduplication threshold in degrees. If two rows have RA and dec values that are within this threshold, only one of them will be kept for sampling. Use 0.0 to keep all rows. Default: 0.0
**kwargs (dict, optional) – Additional keyword arguments to pass to the parent class constructor.

radius = None[source]

classmethod from_hats(path, *, radius=None, extra_cols=None, dedup_threshold=0.0, **kwargs)[source]

Create a ObsTableRADECSampler from the observations in a HATS Catalog.

Note

If you have an existing Dask client, it may be used. See LSDB documentation for details: https://docs.lsdb.io/en/latest/

Parameters:

path (str or Path) – The base path of the HATS data directory.
radius (float, optional) – The sampling radius (noise factor) in degrees. Use 0.0 to return the exact pointings. Default: 0.0
extra_cols (list of str, optional) – A list of extra column names to include in the sampling. Default: None
dedup_threshold (float, optional) – The deduplication threshold in degrees. If two rows have RA and dec values that are within this threshold, only one of them will be kept for sampling. Use 0.0 to keep all rows. Default: 0.0
**kwargs (dict, optional) – Additional keyword arguments to pass to the constructor.

Returns:

The created ObsTableRADECSampler object.

Return type:

ObsTableRADECSampler

compute(graph_state, rng_info=None, **kwargs)[source]

Return the given values.

Parameters:

graph_state (GraphState) – An object mapping graph parameters to their values. This object is modified in place as it is sampled.
rng_info (numpy.random._generator.Generator, optional) – A given numpy random number generator to use for this computation. If not provided, the function uses the node’s random number generator.
**kwargs (dict, optional) – Additional function arguments.

Returns:

results – The result of the computation. This return value is provided so that testing functions can easily access the results.

Return type:

any

class ObsTableUniformRADECSampler(data, *, radius=None, outputs=None, seed=None, max_iterations=1000, **kwargs)[source]

Bases: lightcurvelynx.math_nodes.np_random.NumpyRandomFunc

A FunctionNode that samples RA and dec uniformly from the area covered by an ObsTable. RA and dec are returned in degrees.

Note

This uses rejection sampling where it randomly guesses an (RA, dec) then checks if that point falls within the survey. If not, it repeats the process until it finds a valid point or reaches max_iterations iterations (then returns the last sample). This sampling method can be quite slow or even generate out-of-survey samples if the coverage is small.

data[source]

The ObsTable object to use for sampling.

Type:: ObsTable

radius[source]

The radius of the field of view of the observations in degrees.

Type:: float

max_iterations[source]

The maximum number of iterations to perform. Default: 1000

Type:: int

Parameters:

data (ObsTable) – The ObsTable object to use for sampling.
radius (float, optional) – The search radius around the center of the pointing. If None, uses the value from the ObsTable.
outputs (list of str, optional) – The list of output names. Default: [“ra”, “dec”]
seed (int, optional) – The random seed to use for the internal random number generator. Default: None
max_iterations (int, optional) – The maximum number of iterations to perform. Default: 1000
**kwargs (dict, optional) – Additional keyword arguments to pass to the parent class constructor.

radius = None[source]

data[source]

max_iterations = 1000[source]

compute(graph_state, rng_info=None, **kwargs)[source]

Return the given values.

Parameters:

graph_state (GraphState) – An object mapping graph parameters to their values. This object is modified in place as it is sampled.
rng_info (numpy.random._generator.Generator, optional) – A given numpy random number generator to use for this computation. If not provided, the function uses the node’s random number generator.
**kwargs (dict, optional) – Additional function arguments.

Returns:

(ra, dec) – If a single sample is generated, returns a tuple of floats. Otherwise, returns a tuple of np.ndarrays.

Return type:

tuple of floats or np.ndarray

class ApproximateMOCSampler(moc, *, outputs=None, seed=None, depth=12, **kwargs)[source]

Bases: lightcurvelynx.math_nodes.np_random.NumpyRandomFunc, citation_compass.CiteClass

A FunctionNode that samples RA and dec (approximately) from the coverage of a MOCPy Multi-Order Coverage Map object.

The depth parameter controls the approximation level. Higher depths provide better accuracy but require more memory and computation time. We recommend at least depth=12 for reasonable accuracy.

References

MOCPY: https://github.com/cds-astro/mocpy/
CDS Healpix: https://github.com/cds-astro/cds-healpix-python
MOC: Pierre Fernique, Thomas Boch, Tom Donaldson, Daniel Durand , Wil O’Mullane, Martin Reinecke, and Mark Taylor. MOC - HEALPix Multi-Order Coverage map Version 1.0. IVOA Recommendation 02 June 2014, pages 602, Jun 2014. doi:10.5479/ADS/bib/2014ivoa.spec.0602F.

healpix_list[source]

The list of healpix pixel IDs that cover the MOC at the given depth.

Type:: list of int

depth[source]

The healpix depth to use as an approximation. Must be [2, 29].

Type:: int

depth = 12[source]

healpix_list[source]

classmethod from_file(filename, format='fits', **kwargs)[source]

Create an ApproximateMOCSampler from a MOC file.

This file can be created from a mocpy.MOC object using its save() function.

Parameters:

filename (str or Path) – The path to the MOC file. Supported formats include FITS, JSON, and ASCII.
format (str, optional) – The format of the MOC file. Supported formats include ‘fits’, ‘json’, and ‘ascii’. Default is ‘fits’.
**kwargs (dict, optional) – Additional keyword arguments to pass to the constructor.

Returns:

The created ApproximateMOCSampler object.

Return type:

ApproximateMOCSampler

classmethod from_obstable(obstable, *, depth=12, use_footprint=False, radius=None, **kwargs)[source]

Create an ApproximateMOCSampler from an ObsTable object.

The depth parameter controls the approximation level. Higher depths provide better accuracy but require more memory and computation time. We recommend at least depth=12 for reasonable accuracy.

Parameters:

obstable (ObsTable) – The ObsTable object to use for creating the MOC.
depth (int, optional) – The healpix depth to use as an approximation. Must be [2, 29]. Default: 12
radius (float, optional) – The radius to use for each image (in degrees). Only used if use_footprint is False. If None, the radius from the survey values will be used.
use_footprint (bool, optional) – Whether to use the detector footprint to build the MOC. If True, the footprint will be used to compute the MOC regions for each pointing. If False, a simple cone with the given radius will be used.
**kwargs (dict, optional) – Additional keyword arguments to pass to the constructor.

Returns:

The created ApproximateMOCSampler object.

Return type:

ApproximateMOCSampler

classmethod from_obstable_union(obstables, *, depth=12, use_footprint=False, radii=None, **kwargs)[source]

Create an ApproximateMOCSampler from the union of the footprints in an ObsTable.

The depth parameter controls the approximation level. Higher depths provide better accuracy but require more memory and computation time. We recommend at least depth=12 for reasonable accuracy.

Parameters:

obstables (list of ObsTable) – The list of ObsTable objects to use for creating the MOC. The union of their coverages will be used.
depth (int, optional) – The healpix depth to use as an approximation. Must be [2, 29]. Default: 12
radii (list of float, optional) – The radius to use for each image (in degrees). Only used if use_footprint is False. If None, the radius from the survey values will be used.
use_footprint (bool, optional) – Whether to use the detector footprint to build the MOC. If True, the footprint will be used to compute the MOC regions for each pointing. If False, a simple cone with the given radius will be used.
**kwargs (dict, optional) – Additional keyword arguments to pass to the constructor.

Returns:

The created ApproximateMOCSampler object.

Return type:

ApproximateMOCSampler

classmethod from_obstable_intersection(obstables, *, depth=12, use_footprint=False, radii=None, **kwargs)[source]

Create an ApproximateMOCSampler from the intersection of the footprints in an ObsTable.

The depth parameter controls the approximation level. Higher depths provide better accuracy but require more memory and computation time. We recommend at least depth=12 for reasonable accuracy.

Parameters:

obstables (list of ObsTable) – The list of ObsTable objects to use for creating the MOC. The intersection of their coverages will be used.
depth (int, optional) – The healpix depth to use as an approximation. Must be [2, 29]. Default: 12
radii (list of float, optional) – The radius to use for each image (in degrees). Only used if use_footprint is False. If None, the radius from the survey values will be used.
use_footprint (bool, optional) – Whether to use the detector footprint to build the MOC. If True, the footprint will be used to compute the MOC regions for each pointing. If False, a simple cone with the given radius will be used.
**kwargs (dict, optional) – Additional keyword arguments to pass to the constructor.

Returns:

The created ApproximateMOCSampler object.

Return type:

ApproximateMOCSampler

classmethod from_ra_dec_lists(ra_list, dec_list, *, depth=6, **kwargs)[source]

Create an ApproximateMOCSampler from lists of RA and dec values. This method is useful when the survey contains many small pointings, such as CCD-level information.

The depth parameter controls the approximation level. Higher depths provide better accuracy but require more memory and computation time.

Parameters:

ra_list (list or np.ndarray) – The list of RA values in degrees.
dec_list (list or np.ndarray) – The list of dec values in degrees.
depth (int, optional) – The healpix depth to use as an approximation. Must be [2, 29]. Default: 12
**kwargs (dict, optional) – Additional keyword arguments to pass to the constructor.

Returns:

The created ApproximateMOCSampler object.

Return type:

ApproximateMOCSampler

plot_footprint(*, depth=None, fig=None, ax=None, **kwargs)[source]

Plot the MOC footprint using matplotlib.

Parameters:

depth (int, optional) – The healpix depth to use for plotting. If None, uses the depth of the sampler.
fig (matplotlib.figure.Figure, optional) – An existing matplotlib figure to use. If None, a new figure is created.
ax (matplotlib.pyplot.Axes or None, optional) – The axes to use for the plot. If None, new axes will be created on the figure.
**kwargs (dict, optional) – Additional keyword arguments to pass to the plot_moc function.

Returns:

fig (matplotlib.figure.Figure) – The figure containing the plot.
ax (matplotlib.pyplot.Axes) – The axes containing the plot.

compute(graph_state, rng_info=None, **kwargs)[source]

Return the given values.

Parameters:

graph_state (GraphState) – An object mapping graph parameters to their values. This object is modified in place as it is sampled.
rng_info (numpy.random._generator.Generator, optional) – A given numpy random number generator to use for this computation. If not provided, the function uses the node’s random number generator.
**kwargs (dict, optional) – Additional function arguments.

Returns:

(ra, dec) – If a single sample is generated, returns a tuple of floats. Otherwise, returns a tuple of np.ndarrays.

Return type:

tuple of floats or np.ndarray

class CatalogRADECSampler(data, *, dedup_threshold=0.0, **kwargs)[source]

Bases: ObsTableRADECSampler

A FunctionNode that randomly samples RA and dec from a given catalog of objects.

Note

This is a thin convenience wrapper around ObsTableRADECSampler.

Parameters:

data (Pandas DataFrame, NestedFrame, or dict) – The data to use for sampling. Must contain ‘ra’ and ‘dec’ columns.
dedup_threshold (float, optional) – The deduplication threshold in degrees. If two rows have RA and dec values that are within this threshold, only one of them will be kept for sampling. Use 0.0 to keep all rows. Default: 0.0
**kwargs (dict, optional) – Additional keyword arguments to pass to the parent class constructor.

class MilkyWayCoordSampler(density_model=None, seed=None, **kwargs)[source]

Bases: lightcurvelynx.math_nodes.np_random.NumpyRandomFunc

A FunctionNode that samples (RA, dec, distance) positions according to a Milky Way stellar density model.

By default this uses the MilkyWayDensityJuric2008 model (Juric et al. 2008), but any subclass of MilkyWayDensityBase can be supplied. Spherical coordinates are returned in degrees, and the distance is in parsecs.

References

Juric et al., 2008, ApJ, 673, 864 https://iopscience.iop.org/article/10.1086/523619/pdf

density_model[source]

The stellar density model used for sampling.

Type:: MilkyWayDensityBase

Parameters:

density_model (MilkyWayDensityBase or None, optional) – The Milky Way stellar density model to use for sampling. If None a MilkyWayDensityJuric2008 instance with default parameters is created. Default: None
seed (int or None, optional) – Seed for the internal random number generator. Default: None
**kwargs (dict, optional) – Additional keyword arguments passed to the parent class.

Examples

>>> import numpy as np
>>> from lightcurvelynx.math_nodes.ra_dec_sampler import MilkyWayCoordSampler
>>> sampler = MilkyWayCoordSampler(seed=42, node_label="mw")
>>> (ra, dec, dist) = sampler.generate(num_samples=1)
>>> 0.0 <= ra <= 360.0
True
>>> -90.0 <= dec <= 90.0
True
>>> dist >= 0.0
True

density_model = None[source]

compute(graph_state, rng_info=None, **kwargs)[source]

Sample (RA, dec, distance_pc) positions from the Milky Way density model.

Parameters:

graph_state (GraphState) – An object mapping graph parameters to their values. This object is modified in place as it is sampled.
rng_info (numpy.random.Generator, optional) – A given numpy random number generator to use for this computation. If not provided, the node’s internal generator is used.
**kwargs (dict, optional) – Additional function arguments (unused).

Returns:

results – A three-element list containing the sampled right ascension, declination, and distance values. RA and dec are in degrees, and distance is in parsecs. Each element is a float when num_samples == 1, otherwise a numpy array.

Return type:

list of [ra, dec, distance_pc]