survey.healpix

survey.healpix#

This module provides HEALPix-based functions for handling survey observations on the sky.

skysurvey.survey.healpix.get_ipix_in_range(nside, ra_range=None, dec_range=None, in_rad=False)[source]#

Get the healpix pixel index (ipix) that are with a given ra and dec range.

Parameters:

  • nside (int) – Healpix nside.

  • ra_range (2d-array, None, optional) – Min and max to define a coordinate range to be considered. None means no limit.

  • dec_range (2d-array, None, optional) – Min and max to define a coordinate range to be considered. None means no limit.

  • in_rad (bool, optional) – Are the ra and dec coordinates in radian (True) or degree (False).

Returns:

List of healpix pixel index ipix.

Return type:

list

class skysurvey.survey.healpix.HealpixSurvey(nside, data=None)[source]#

Bases: BaseSurvey

The HealpixSurvey class.

Parameters:

  • nside (int) – healpix nside parameter

  • data (pandas.DataFrame) – observing data.

See also

from_data()

loads the instance given observing data.

from_random()

generate random observing data and loads the instance.

classmethod from_data(nside, data)[source]#

Load an instance given survey data and healpix size (nside).

Parameters:

  • nside (int) – healpix nside parameter

  • data (pandas.DataFrame) – observing data.

Return type:

instance

See also

from_random()

generate random observing data and loads the instance.

classmethod from_random(nside, size, bands, mjd_range, skynoise_range, ra_range=None, dec_range=None, rng=None, **kwargs)[source]#

Load an instance with random observing data.

Parameters:

  • nside (int) – healpix nside parameter

  • size (int) – number of observations to draw

  • bands (list of str) – list of bands that should be drawn.

  • mjd_range (list or array) – min and max mjd for the random drawing.

  • skynoise_range (list or array) – min and max skynoise for the random drawing.

  • ra_range (2d-array, None) – min and max to define a coordinate range to be considered. None means no limit.

  • dec_range (2d-array, None) – min and max to define a coordinate range to be considered. None means no limit.

  • rng (None, int, (Bit)Generator, optional) – seed for the random number generator. (doc adapted from numpy’s np.random.default_rng docstring. See that documentation for details.) If None, an unpredictable entropy will be pulled from the OS. If an int, (>0), it will set the initial BitGenerator state. If a (Bit)Generator, it will be returned as a Generator unaltered.

  • **kwargs – goes to the draw_random() method

Return type:

HealpixSurvey

classmethod from_pointings(nside, data, footprint=None, moc=None, rakey='ra', deckey='dec', backend='polars', use_pyarrow_extension_array=False, **kwargs)[source]#

Loads an instance given observing poitings of a survey.

This loads an polygon.PolygonSurvey using from_pointing and converts that into an healpix using the to_healpix() method.

Parameters:

  • nside (int) – healpix nside parameter

  • data (pandas.DataFrame or dict) – observing data, must contain the rakey and deckey columns.

  • footprint (shapely.geometry) – footprint in the sky of the observing camera

  • moc (mocpy.MOC) – MOC representation of the observing camera

  • rakey (str) – name of the R.A. column (in deg)

  • deckey (str) – name of the Declination column (in deg)

  • backend (str) – which backend to use to merge the data (speed issue): - polars (fastest): requires polars installed -> converted to pandas at the end - pandas (classic): the normal way - dask (lazy): as persisted dask.dataframe is returned

  • use_pyarrow_extension_array (bool) – = ignored in backend != ‘polars’ or polars_to_pandas is not True = should the pandas dataframe be based on numpy array (slow to load but faster then) or based on pyarrow array (like in polars) ; faster but numpy.asarray will be used by pandas when need (which will then slow things down).

  • **kwargs – goes to polygon.PolygonSurvey.from_pointings

Return type:

instance

get_field_area()[source]#

Area (deg**2) of a healpy pixel.

get_observed_area(min_obs=1)[source]#

Get the observed area (in deg**2). A healpix is consider observed if present more than min_obs time.

Parameters:

min_obs (int) – minimum number of observations to consider a field as observed.

Return type:

float

get_polygons(observed_fields=False, as_vertices=False, origin=180)[source]#

Get a list of polygons.

Parameters:

  • observed_fields (bool, optional) – Should this be limited to observed fields?

  • as_vertices (bool, optional) – Should this returns a list of shapely.geometry.Polygon (False) or its vertices (shape N [fields], 2 [ra, dec], 4[corners]).

  • origin (float, optional) – Origin of the R.A. coordinate (center of image).

Returns:

(as_vertices)

  • list of polygon

  • list of vertices

Return type:

list

get_skyarea(as_multipolygon=True, buffer=0.01)[source]#

Get multipolygon (or list) of field geometries.

Parameters:

  • as_multipolygon (bool, optional) – If True, returns a multipolygon. Otherwise, returns unary_union of polygons

  • buffer (float, None, optional) – buffer (in deg) around the polygon. This helps joining edges and reduces the number of isolated sky-pixels which may artificially slow down computation

Return type:

shapely.geometry.MultiPolygon or list

radec_to_fieldid(radec, origin=180, observed_fields=False)[source]#

Get the fieldid associated to the given coordinates.

Parameters:

  • radec (pandas.DataFrame or 2d array) – Coordinates in degree.

  • origin (float, optional) – Value of the central R.A.

  • observed_fields (bool, optional) – Should this be limited to fields actually observed? This is ignored is self.data is None.

Return type:

pandas.DataFrame

get_field_centroid(origin=180)[source]#

Get the centroid of the fields.

Parameters:

origin (float, optional) – Origin of the ra coordinates.

Returns:

ra, dec

Return type:

(array, array)

draw_random(size, bands, mjd_range, skynoise_range, gain_range=1, zp_range=25, ra_range=None, dec_range=None, inplace=False, nside=None, rng=None, **kwargs)[source]#

Draw observations.

Parameters:

  • size (int) – number of observations to draw

  • bands (list of str) – list of bands that should be drawn.

  • ra_range (2d-array, None) – min and max to define a coordinate range to be considered. None means no limit.

  • dec_range (2d-array, None) – min and max to define a coordinate range to be considered. None means no limit.

  • skynoise_range (2d-array, float, int) – range to be considered. If float or int, this value will always be used. otherwise, uniform distribution between the range assumed.

  • gain_range (2d-array, float, int) – range to be considered. If float or int, this value will always be used. otherwise, uniform distribution between the range assumed.

  • zp_range (2d-array, float, int) – range to be considered. If float or int, this value will always be used. otherwise, uniform distribution between the range assumed.

  • inplace (bool) – shall this method replace the current self.data or return a new instance of the class with the generated observing data.

  • nside (int) – = ignore if inplace is set to True = provide a new healpix nside parameters.

Returns:

see the inplace option.

Return type:

class instance or None

See also

from_random()

generate random observing data and loads the instance.

set_data

set the observing data to the instance.

show(stat='size', column=None, title=None, data=None, vmin=None, vmax=None, seed=None, **kwargs)[source]#

Shows the sky coverage using healpy.mollview.

Parameters:

  • stat (str) – element to be passed to groupby.agg() could be e.g.: ‘mean’, ‘std’ etc. If stat = ‘size’, this returns data[“fieldid”].value_counts() (slightly faster than groupby(“fieldid”).size()).

  • columns (str) – column of the dataframe the stat should be applied to. = ignored if stat=’size’ =

  • title (str) – title of the healpy.mollview plot. (healpy.mollview option)

  • data (pandas.DataFrame, None) – data you want this to be applied to. if None, a copy of self.data is used. = leave to None if unsure =

Return type:

None

See also

get_fieldstat()

get observing statistics for the fields

property nside#

Healpix nside parameter (defines the ‘fields’ size and number).

property nfields#

Number of fields (shortcut to npix).

property npix#

Number of healpix pixels.

property fieldids#

Id of the individual fields.

metadata()[source]#

Pandas Series containing meta data information.

Return type:

pandas.Series