API

The interfaces to QLSC are described here.

QLSC Class

class qlsc.QLSC(depth=30)[source]

A class that describes a quadrilaterized spherical cube (QLSC).

The quadrilaterized sphere is divided into six faces. The bin level defines the number times a face is subdivided. A bin level of 1 divides each face into four “pixels”; bin level two divides each of those pixels again into four, etc.

At the lowest resolution where bin level=0 there is 1 bin per face for a total of 6 bins. The next bin level 1 divides each face into four bins, i.e. a total of 24 bins. Higher bin levels further divide each bin four more times.

A scheme can be defined by the bin level where:

no. bins per face        = (2**depth)**2
number of bins on sphere = no. bins per face * 6

Each bin has a pixel number called an “ipix”, which is an integer encoded with the location of the bin.

The default value of depth = 30 that divides the sphere into 6,442,450,944 bins (i.e. nside=1,073,741,824), is the one used by the Q3C PostgreSQL plugin. This value is used if neither nside or bin_size are specified.

Parameters

depth (int) – number of times each bin in each face is subdivided by four

ang2ipix(ra=None, dec=None, points=None)[source]

Convert ra,dec positions to an ipix number.

This method accepts scalar values or NumPy arrays. Slices of any other NumPy array are accepted. Note that arrays are required to be dtype.double; copies will be made of arrays of any other type.

Right ascension values outside of the range [0,360] are handled efficiently. Declination values outside of [-90,90] are handled, but may result in arrays being copied. (This is only important when working with extremely large arrays.)

Example usage:

ipix = ang2ipix(45,60)
ipix = ang2ipix(ra=45,dec=60)
ipix = ang2ipix(points=np.array([[45,60],[0,55]])
ipix = ang2ipix(ra=catalog[:,4], dec=catalog[:,5])
Parameters

  • ra (Union[float, Iterable, None]) – right ascension (degrees)

  • dec (Union[float, Iterable, None]) – declination (degrees)

  • points (Optional[Iterable]) – an array of [ra,dec] points, shape=(n,2)

Return type

Union[float, ndarray]

Returns

the ipix integer if a single point is provided, an array of ipix integers if an array of values is provided

ang2ipix_at_depth(ra, dec, depth)[source]

Return the ipix value at the specified coordinate for any given bin level. Returns the ipix value of the pixel center at certain pixel depth covering the specified (ra,dec). [??]

Parameters

  • ra (float) – right ascension (degrees); must be in [0,360]

  • dec (float) – declination (degrees); must be in [-90,90]

  • depth (int) – ; must be in the integer range [1-30]

Return type

int

Returns

ang2ipix_xy(ra=None, dec=None, points=None)[source]

Convert an ra,dec position to an ipix number; also returns the face number, and (x,y) location on the square face.

Parameters

  • ra (Optional[float]) – right ascension angle (degrees)

  • dec (Optional[float]) – declination angle (degrees), must be in [-90,90]

  • points – an array of ra,dec coordinates (shape: (n,2)) NOT YET SUPPORTED

Return type

dict

Returns

a dictionary with the keys: [facenum, ipix, x, y]

face_number(ra, dec, ipix=None)[source]

Return the cube face number for the provided coordinate.

Cube faces are numbered as the following:

face 0 = top
face 1 = -45° ≤ α < 45
face 2 = 45° ≤ α < 135
face 3 = 135° ≤ α < 225
face 4 = 225° ≤ α < 315
face 5 = bottom
Parameters

  • ra (float) – right ascension in degrees; must be in [0,360]

  • dec (float) – declination in degrees; must be in [-90,90]

  • ipix (Optional[int]) – the pixel identifier number

Return type

int

Returns

the cube face number

ipix2ang(ipix)[source]

Convert an ipix number to the ra,dec coordinate of the “lower left” corner of the pixel, in degrees.

See the method ipix2ang_center() to return the center of the pixel.

This method matches that of the Q3C PostgreSQL plugin.

Parameters

ipix (int) – ipix number

Return type

Tuple[float, float]

Returns

ra,dec in degrees as a tuple of the lower left corner of the pixel

ipix2ang_center(ipix)[source]

Convert an ipix number to the ra,dec coordinate of the center of the pixel, in degrees.

See the method ipix2ang() to return the “lower left” corner of the pixel which matches what is returned by the Q3C PostgreSQL plugin.

The pixel “center” here is defined in the x,y coordinates; the point projected on the sphere is the one returned.

Parameters

ipix (int) – ipix number

Return type

Tuple[float, float]

Returns

ra,dec in degrees as a tuple of the center of the pixel

ipix2face(ipix)[source]

Return the face number the given ipix value falls on.

Return type

int

ipix2polygon(ipix=None, duplicate_endpoint=False)[source]

Returns the points that describe the polygon that define this pixel.

All lines between each coordinate in the polygon should be drawn on great circles. The Cornish library can be useful for this.

Parameters

  • ipix (Optional[int]) – the pixel identifier number

  • duplicate_endpoint – if True, repeat the first coordinate in the polygon as the last element

Returns

an array of ra,dec coordinates in degrees

ipix2xy(ipix)[source]

Convert an ipix value to the (x,y) position on the corresponding square face; returns (facenum,x,y).

Parameters

ipix (int) – ipix number

Return type

Tuple[int, float, float]

Returns

(facenum,x,y) as a tuple

ipix_area(ipix, depth)[source]

Return the area of a given QLSC pixel in steradians for a given ipix.

NOTE: currently this method returns the average bin size and ignores the ipix and depth values!

Not all pixels are guaranteed to be the same size, but they are very close, i.e. the size of any one pixel is a good approximation to any other.

pixel area ≈ 4π / no. pixels on sphere

Parameters

ipix (int) – the pixel identifier number

Return type

float

Returns

the area of the specified pixel in steradians

ipix_down(ipix)[source]

Returns the four ipix values at the next higher depth.

Parameters

ipix (int) – the ipix value at the resolution of this object’s scheme.

Return type

Iterable[int]

ipix_up(ipix)[source]

Returns the ipix value value at the next lower depth.

Parameters

ipix (int) – the ipix value at the resolution of this object’s scheme.

property nbins: int

Returns the total number of bins in this pixellation scheme (number of divisions per face * 6).

Return type

int

property nside: int

Number of bins along one edge of the cube face.

Return type

int

xy2ang(facenum=None, x=None, y=None, points=None)[source]

Convert an x,y coordinate pair on the given face number to (ra,dec).

Parameters

  • facenum (Optional[int]) – the number of the cube face (0=top, 1-4=sides, 5=bottom)

  • x (Optional[float]) – x coordinate on cube face

  • y (Optional[float]) – y coordinate on cube face

  • points (Optional[Iterable]) – an array containing (x,y) coordinate pairs; shape = (n,2)

Returns

tuple of (ra,dec) corresponding to the location on the cube face

xy2ipix(facenum=None, x=None, y=None)[source]

Convert an x,y coordinate pair on the given face number to the ipix value.

Parameters

  • facenum (Optional[int]) – the number of the cube face (0=top, 1-4=sides, 5=bottom)

  • x (Optional[float]) – x coordinate on cube face

  • y (Optional[float]) – y coordinate on cube face

Return type

int

QLSC Index

class qlsc.QLSCIndex(qlsc=<qlsc.QLSC at 0x7f4c3b0a8290, depth=30>, filepath=None, name=None, description=None)[source]

An object that stores (ra,dec) coordinates on a sphere and performs fast cone searches.

The QLSCIndex object can be provided with a file path to save the index for repeated use, e.g.

qlsc = QLSC(depth=30)
sdss_catalog = QLSCIndex(qlsc=qlsc, filepath='/path/to/save/file.qlscidx')

The filename and extension can be anything, but .qlscidx is suggested to remember what kind of file it is. If no filepath parameter is provided, an index is created in memory, but note that it will no longer exist after the program ends. If an existing file is found at the file path provided, an attempt will be made to open it and, if a valid QLSCIndex file, it will be used. The file path can be provided in the form of a URI, e.g. file:///Users/meerkat/catalog.qlscidx.

The underlying storage is an SQLite database, but this should be considered an implementation detail and can change. (This may be documented for expanded use in the future.)

Parameters

  • qlsc (QLSC) – an instance of QLSC set to the desired segmentation level

  • filepath (Union[PathLike, str, None]) – the file path (string path, pathlib.Path, or ``file://` URL) where a persistent index will be stored; the default is to create the index in memory

  • name (Optional[str]) – a user-provided name for the index

  • description (Optional[str]) – a user-provided description of the index

add_point(ra=None, dec=None, key=None)[source]

Add a single coordinate point to the index.

This method can be called multiple times with the same coordinate, but duplicate entries will be discarded. Key values are not required to be unique. If a coordinate is added to the index without a key and again later with a key, it will not be added to the index (and vice versa).

Parameters

  • ra (Optional[float]) – a single right ascension value, in degrees

  • dec (Optional[float]) – a single declination value, in degrees

  • key (Optional[str]) – a unique identifier for the coordinate (optional)

add_points(ra=None, dec=None, points=None, keys=None)[source]

Add a collection of points to the index.

This method can be called multiple times with the same coordinate, but duplicate entries will be discarded. Key values are not required to be unique. If a coordinate is added to the index without a key and again later with a key, it will not be added to the index (and vice versa).

This method is preferred for a large number of points over using add_point() in a loop.

Note that if the dec values are not in the range [-90,90], a copy of the ra,dec arrays will be made to normalize the points first. This may only be an issue when providing an extremely large number of points.

Parameters

  • ra (Optional[Iterable]) – an Iterable (e.g. NumPy array) of right ascension points in degrees

  • dec (Optional[Iterable]) – an Iterable of declination points in degrees

  • points (Optional[Iterable[Tuple]]) – an Iterable of tuples of (ra,dec) pairs

  • key – an Iterable of unique identifiers for each point

property number_of_points: int

Return the number of coordinate points in the index.

Return type

int

radial_query(ra, dec, radius, return_key=False)[source]

Given an ra,dec coordinate and a radius (all in degrees), return the points that fall in the cone search.

The returned numpy.recarray has the keys “ra”, “dec”, and (if requested), “key”.

Parameters

  • ra (float) – right ascension (degrees)

  • dec (float) – declination (degrees)

  • radius (Union[float, ForwardRef]) – radius (degrees), accepts a float value or astropy.units.Quantity

  • return_key (bool) – if set to True, returns the key value as provided when added to the index

Return type

recarray

Returns

if return_key=True, returns a numpy.recarray with keys ra,dec,key; otherwise an array of matches, shape (n,2)

Point Generation

The method below is useful to generate a number of evenly distributed points at deterministic locations for testing purposes.

qlsc.generate.sunflower_points_on_sphere(n=1000, radians=False, polar_angle_from_zenith=False)[source]

Generate a list of points on a sphere using the golden spiral method.

The default values return points that can be taken as ra,dec in degrees.

Points can be returned where the polar angle θ is measured from the zenith where 0 ≤ 0 ≤ π (polar_angle_from_zenith=True) or else from the reference plane where -π/2 ≤ θ ≤ π/2 (polar_angle_from_zenith=False). The QLSC index requires the latter.

Points are returned in degrees by default, as required by the QLSC index. The same points will always be returned for the same values of n. The points array is sorted in descending order by the polar angle, from the zenith down.

It can be useful to set radians=True for plotting.

Ref: https://stackoverflow.com/a/44164075/2712652

Parameters

  • n (int) – number of points to generate

  • radians (bool) – returns points in radians if True, degrees if False

  • polar_angle_from_zenith (bool) – returns 

Returns

array of points on sphere as polar angle, azimuthal angle: (φ,θ)