mocpy.MOC¶

class mocpy.MOC(store_index)[source]¶

Multi-order spatial coverage class.

A MOC describes the coverage of an arbitrary region on the unit sphere. MOCs are usually used for describing the global coverage of catalog/image surveys such as GALEX or SDSS. A MOC corresponds to a list of HEALPix cells at different depths. This class gives you the possibility to:

Define MOC objects:

From a FITS file that stores HEALPix cells (see load(path, 'fits')).
Directly from a list of HEALPix cells expressed either as a numpy structural array (see from_healpix_cells) or a simple python dictionary (see from_json).
From a list of sky coordinates (see from_skycoords, from_lonlat).
From a convex/concave polygon (see from_polygon).
From a cone (will be implemented in a next version).

Perform fast logical operations between MOC objects:

The intersection
The union
The difference
The complement

Plot the MOC objects:

Draw the MOC with its HEALPix cells (see fill)
Draw the perimeter of a MOC (see border)

Get the sky coordinates defining the border(s) of MOC objects (see get_boundaries).
Serialize MOC objects to astropy.io.fits.HDUList or JSON dictionary and save it to a file.

Is a Spatial Coverage (S-MOC).

Args:: create_key: Object ensure __init__ is called by super-class/class-methods only store_index: index of the S-MOC in the rust-side storage

MAX_ORDER = np.uint8(29)¶

add_neighbours()¶

Extend the MOC instance so that it includes the HEALPix cells touching its border.

The depth of the HEALPix cells added at the border is equal to the maximum depth of the MOC instance.

Returns:

mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: self extended by one degree of neighbours.

barycenter()[source]¶

Return the Barycenter of the MOC.

Examples

>>> from mocpy import MOC
>>> import astropy.units as u
>>> MOC.from_cone(6*u.deg, 15*u.deg,
...               radius=10*u.arcmin, max_depth=13).barycenter()
<SkyCoord (ICRS): (ra, dec) in deg
    (6.00000618, 14.99968594)>

border(ax, wcs, **kw_mpl_pathpatch)[source]¶

Draw the MOC border.s on a matplotlib axis.

This performs the projection of the sky coordinates defining the perimeter of the MOC to the pixel image coordinate system. You are able to specify various styling kwargs for matplotlib.patches.PathPatch (see the list of valid keywords).

Parameters:

axmatplotlib.axes.Axes: Matplotlib axis.
wcsastropy.wcs.WCS: WCS defining the World system <-> Image system projection.
kw_mpl_pathpatch: Plotting arguments for matplotlib.patches.PathPatch

Examples

>>> from mocpy import MOC
>>> from astropy.coordinates import Latitude, Longitude
>>> import astropy.units as u
>>> import matplotlib.pyplot as plt
>>> # Create a MOC
>>> lon = Longitude([5, -5, -5, 5], u.deg)
>>> lat = Latitude([5, 5, -5, -5], u.deg)
>>> moc = MOC.from_polygon(lon, lat)
>>> # Plot the MOC using matplotlib
>>> fig = plt.figure(figsize=(10, 10))
>>> wcs = moc.wcs(fig)
>>> ax = fig.add_subplot(projection=wcs)
>>> moc.border(ax, wcs, color='blue')

complement()¶

Return the complement of the MOC instance.

Returns:

mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The resulting MOC.

contains(lon, lat, keep_inside=True)[source]¶

Test wether a MOC contains –or not– the given points. Returns a boolean mask array.

Deprecated since version 0.11.1: contains is replaced by contains_lonlat for naming consistency. Please consider switching.

Parameters:

lonastropy.coordinates.Longitude or its supertype astropy.units.Quantity: Right ascension array in deg
latastropy.coordinates.Latitude or its supertype astropy.units.Quantity: Declination array in deg
keep_insidebool, optional: True by default. If so the mask describes coordinates lying inside the MOC. If keep_inside is false, contains will return the mask of the coordinates lying outside the MOC.

Returns:

arrayndarray: A mask boolean array

See also

contains_skycoords
contains_lonlat

contains_lonlat(lon, lat, keep_inside=True)[source]¶

Test wether a MOC contains (or not) the given points. Returns a boolean mask array.

The coordinates should be expressed in equatorial coordinates using the ICRS reference. We follow the Space MOC standard.

Parameters:

lonastropy.coordinates.Longitude or its supertype astropy.units.Quantity: Right ascension array in deg
latastropy.coordinates.Latitude or its supertype astropy.units.Quantity: Declination array in deg
keep_insidebool, optional: True by default. If so the mask describes coordinates lying inside the MOC. If keep_inside is false, contains will return the mask of the coordinates lying outside the MOC.

Returns:

ndarray: A mask boolean array

Raises:

ValueErrorIf lon and lat have mismatched shapes.

See also

contains_skycoords

Examples

>>> from mocpy import MOC
>>> from astropy.coordinates import Angle
>>> # create lists of coordinates
>>> lon = Angle([1, 2, 3, -2, -40, -5], unit="deg")
>>> lat = Angle([20, 25, 10, -60, 80, 0], unit="deg")
>>> # create a polygonal moc from these
>>> moc = MOC.from_polygon(lon=lon, lat=lat, max_depth=12)
>>> moc.contains_lonlat(lon=lon, lat=lat) # returns all true
array([ True,  True,  True, True,  True,  True])

contains_skycoords(skycoords, keep_inside=True)[source]¶

Return a boolean mask array of the positions lying inside (or outside) the MOC instance.

Parameters:

skycoordsastropy.coordinates.SkyCoord: The sky coordinates that will be tested.
keep_insidebool, optional: True by default. If so the mask describes coordinates lying inside the MOC. If keep_inside is false, contains will return the mask of the coordinates lying outside the MOC.

Returns:

ndarray: A mask boolean array

See also

contains_lonlat

Examples

>>> from mocpy import MOC
>>> from astropy.coordinates import SkyCoord
>>> moc = MOC.from_string("0/0-11") # all the sky
>>> coords = SkyCoord([0, 180, 90], [0, 0, 0], unit="deg")
>>> moc.contains_skycoords(coords)
array([ True,  True,  True])
>>> moc = MOC.from_string("3/0")
>>> coords = SkyCoord([45, 180], [0, 0], unit="deg")
>>> moc.contains_skycoords(coords)
array([ True, False])

contracted()¶

Return the MOC contracted by removing the internal border made of cells at the MOC maximum depth.

The only difference with respect to remove_neighbours is that contracted returns a new MOC instead of modifying the existing one.

Returns:

mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The extended MOC

degrade_to_order(new_order)[source]¶

Degrade the MOC instance to a new, less precise, MOC.

The maximum depth (i.e. the depth of the smallest HEALPix cells that can be found in the MOC) of the degraded MOC is set to new_order.

Parameters:

new_orderint: Maximum depth of the output degraded MOC.

Returns:

MOC: The degraded MOC.

Examples

>>> from mocpy import MOC
>>> moc = MOC.from_string("10/2000-2200")
>>> moc.degrade_to_order(5)
5/1-2

difference(another_moc, *mocs)¶

Difference between the MOC instance and other MOCs.

Parameters:

another_mocmocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The MOC used that will be subtracted to self.
mocsmocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: Other additional MOCs to perform the difference with.

Returns:

mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The resulting MOC.

Examples

>>> from mocpy import MOC
>>> moc1 = MOC.from_string("3/0-7")
>>> moc2 = MOC.from_string("3/0-3")
>>> moc3 = MOC.from_string("3/4-7")
>>> moc1.difference(moc2, moc3) # should the empty MOC of order 3 (3/)
3/

display_preview(y_size=300)[source]¶

Display a preview of the MOC (calling internally the to_rgba method).

Parameters:

y_sizethe number of pixels along the y-axis, default value is 300

empty()¶

(e.g. a numpy boolean array).

Returns:

bool: True if the MOC instance is empty.

extended()¶

Return the MOC extended by the external border made of cells at the MOC maximum depth.

The only difference with respect to add_neighbours is that extended returns a new MOC instead of modifying the existing one.

Returns:

mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The extended MOC

fill(ax, wcs, optimize=True, **kw_mpl_pathpatch)[source]¶

Draw the MOC on a matplotlib axis.

This performs the projection of the cells from the world coordinate system to the pixel image coordinate system. You can provide style keyword arguments as in matplotlib.patches.PathPatch (see the list of valid keywords).

Parameters:

axmatplotlib.axes.Axes: Matplotlib axis.
wcsastropy.wcs.WCS: WCS defining the World system <-> Image system projection.
optimizebool, optional: If this is set to True, the MOC will be degraded so that no HEALPix will be smaller than one pixel as defined by the WCS. It can be useful to deactivate this optimization for svg outputs or if you take an insert of a WCS. Default is True.
kw_mpl_pathpatch: Plotting arguments for matplotlib.patches.PathPatch.

Examples

>>> from mocpy import MOC
>>> import astropy.units as u
>>> import matplotlib.pyplot as plt
>>> # Create a MOC
>>> moc = MOC.from_ring(external_radius=2*u.deg,
...                     internal_radius=1*u.deg,
...                     lat=0*u.rad, lon=0*u.rad,
...                     max_depth=13,
...                    )
>>> # Plot the MOC using matplotlib
>>> fig = plt.figure(figsize=(10, 10))
>>> wcs = moc.wcs(fig)
>>> ax = fig.add_subplot(projection=wcs)
>>> moc.fill(ax, wcs, color='blue')

flatten()¶: Return the list of indices of all cells in the MOC at the MOC depth.

classmethod from_astropy_regions(region, max_depth: int)[source]¶

Create a SMOC from an astropy regions.

This creates the MOC of the requested order that contains entirely the astropy region. See https://github.com/astropy/regions.

Parameters:

regionSkyRegion: The supported sky regions are CircleSkyRegion, CircleAnnulusSkyRegion, EllipseSkyRegion, RectangleSkyRegion, PolygonSkyRegion, PointSkyRegion, Regions.
max_depthint: The maximum HEALPix cell resolution of the MOC. Should be comprised between 0 and 29.

Returns:

MOC

Notes

For the Regions, the returned MOC will be the union of all the regions.
For the PolygonSkyRegion and the RectangleSkyRegion, the MOC will consider the sides to follow great circles on the sky sphere while in astropy-regions the sides follow straight lines in the projected space (depending on a given WCS, see issue https://github.com/astropy/regions/issues/564).

Examples

>>> from astropy.coordinates import SkyCoord
>>> point = SkyCoord("+23h20m48.3s +61d12m06s")
>>> point_region = regions.PointSkyRegion(point)
>>> moc_point = MOC.from_astropy_regions(point_region, max_depth=10)
>>> moc_point
10/3663728

classmethod from_box(lon, lat, a, b, angle, max_depth)[source]¶

Create a MOC from a box/rectangle.

The box is centered around the (lon, lat) position. The sides and cross from the center follow great circles. As such, the box is the intersection between two orthogonal spherical wedges having the same center. The coordinates should be expressed in equatorial coordinates using the ICRS reference. We follow the Space MOC standard.

Parameters:

lonLongitude or its supertype Quantity: The longitude of the center of the cone.
latLatitude or its supertype Quantity: The latitude of the center of the cone.
aAngle: The semi-major axis of the box, i.e. half of the box’s width.
bAngle: The semi-minor axis of the box, i.e. half of the box’s height.
angleastropy.coordinates.Angle: The tilt angle between the north and the semi-major axis, east of north.
max_depthint: Maximum HEALPix cell resolution.

Returns:

MOC: The resulting MOC

Examples

>>> from mocpy import MOC
>>> from astropy.coordinates import Angle, Longitude, Latitude
>>> moc = MOC.from_box(
...  lon=Longitude("0d"),
...  lat=Latitude("0d"),
...  a=Angle("10d"),
...  b=Angle("2d"),
...  angle=Angle("30d"),
...  max_depth=10
... )

classmethod from_boxes(lon, lat, a, b, angle, max_depth, *, n_threads=None, union_strategy=None)[source]¶

Create a MOC from a box/rectangle.

The boxes are centered around the (lon, lat) positions. The coordinates should be expressed in equatorial coordinates using the ICRS reference. We follow the Space MOC standard.

Parameters:

lonLongitude or its supertype Quantity: The longitude of the center of the cone.
latLatitude or its supertype Quantity: The latitude of the center of the cone.
aAngle or its supertype Quantity: The semi-major axis of the box, i.e. half of the box’s width.
bAngle or its supertype Quantity: The semi-minor axis of the box, i.e. half of the box’s height.
angleastropy.coordinates.Angle or its supertype Quantity: The tilt angle between the north and the semi-major axis, east of north.
max_depthint: Maximum HEALPix cell resolution.
n_threadsint, optional: The number of threads to be used. If this is set to None (default value), all available threads will be used.
union_strategystr, optional: Return the union of all the boxes instead of the list of MOCs. Can be either “small_boxes” or “large_boxes”. The “small_boxes” strategy will be faster for non-overlapping boxes and the “large_boxes” for the other case.

Returns:

list[MOC] or MOC: The resulting list of MOCs. If ‘union_strategy’ is not None, returns the MOC of the union of all boxes instead.

Examples

>>> from mocpy import MOC
>>> import astropy.units as u
>>> # similar boxes, same size and orientation
>>> moc_list = MOC.from_boxes(
...  lon=[1, 2]*u.deg,
...  lat=[1, 2]*u.deg,
...  a=10*u.deg,
...  b=5*u.deg,
...  angle=30*u.deg,
...  max_depth=10
... )
>>> # different boxes
>>> moc_list = MOC.from_boxes(
...  lon=[1, 2]*u.deg,
...  lat=[1, 2]*u.deg,
...  a=[10, 20]*u.deg,
...  b=[5, 10]*u.deg,
...  angle=[30, 10]*u.deg,
...  max_depth=10,
...  union_strategy="small_boxes"
... )

classmethod from_cone(lon, lat, radius, max_depth, *, delta_depth=2)[source]¶

Create a MOC from a cone.

The cone is centered around the (lon, lat) position with a radius expressed by radius. The coordinates should be expressed in equatorial coordinates using the ICRS reference. We follow the Space MOC standard.

Parameters:

lonastropy.coordinates.Longitude or its supertype astropy.units.Quantity: The longitude of the center of the cone.
latastropy.coordinates.Latitude or its supertype astropy.units.Quantity: The latitude of the center of the cone.
radiusastropy.coordinates.Angle: The radius angle of the cone.
max_depthint: Maximum HEALPix cell resolution.
delta_depthint, optional: To control the approximation, you can choose to perform the computations at a deeper depth using the delta_depth parameter. The depth at which the computations will be made will therefore be equal to max_depth + delta_depth.

Returns:

MOC: The resulting MOC

Examples

>>> from mocpy import MOC
>>> import astropy.units as u
>>> from astropy.coordinates import Angle, Longitude, Latitude
>>> moc = MOC.from_cone(
...  lon=Longitude(0 * u.deg),
...  lat=Latitude(0 * u.deg),
...  radius=Angle(10, u.deg),
...  max_depth=10
... )

classmethod from_cones(lon, lat, radius, max_depth, *, union_strategy=None, delta_depth=2, n_threads=None)[source]¶

Create a list of MOCs from cones.

Each cone is centered around the (lon, lat) position with a radius expressed by radius. The coordinates should be expressed in equatorial coordinates using the ICRS reference. We follow the Space MOC standard.

Parameters:

lonastropy.coordinates.Longitude or its supertype astropy.units.Quantity: The longitude of the center of the cone. Can be scalar or a list of longitudes.
latastropy.coordinates.Latitude or its supertype astropy.units.Quantity: The latitude of the center of the cone. Can be scalar or a list of latitudes.
radiusastropy.coordinates.Angle or its supertype astropy.units.Quantity: The radius angle of the cone. Can be scalar or a list of radii.
max_depthint: Maximum HEALPix cell resolution.
union_strategystr, optional: Return the union of all the cones instead of the list of MOCs. Can be either “small_cones” or “large_cones”. The “small_cone” strategy will be faster for non-overlapping cones and the “large_cones” for the other case.
delta_depthint, optional: To control the approximation, you can choose to perform the computations at a deeper depth using the delta_depth parameter. The depth at which the computations will be made will therefore be equal to max_depth + delta_depth.
n_threadsint, optional: The number of threads to be used. If this is set to None (default value), all available threads will be used.

Returns:

List[MOC] or MOC: The resulting list of MOCs, or if ‘union_strategy’ is not None, the MOC of the union of all the cones.

Examples

>>> from mocpy import MOC
>>> import astropy.units as u
>>> moc = MOC.from_cones(
...  lon=[1, 4] * u.deg,
...  lat=[2, 5] * u.deg,
...  radius=1 * u.arcmin,
...  max_depth=12,
...  union_strategy="small_cones"
... )

classmethod from_depth29_ranges(max_depth, ranges=None)[source]¶

Create a MOC from a set of ranges of HEALPix Nested indices at order 29.

For each range, the lower bound is inclusive and the upper bound is exclusive. The range [0, 12*4^29[ represents the full-sky.

Parameters:

max_depthint, The resolution of the MOC
rangesndarray, optional: a N x 2 numpy array representing the set of depth 29 HEALPix nested ranges. defaults to np.zeros((0, 2), dtype=np.uint64)

Returns:

mocMOC: The MOC

Examples

>>> from mocpy import MOC
>>> import numpy as np
>>> # Create an empty MOC using depth29 ranges
>>> ranges = np.zeros((0, 2), dtype='uint64')
>>> MOC.from_depth29_ranges(25, np.array([[10000, 20000], [40000, 50000]]))
23/3 10-11
24/10-11 16-18 39 48
25/39 76-78

classmethod from_elliptical_cone(lon, lat, a, b, pa, max_depth, *, delta_depth=2)[source]¶

Create a MOC from an elliptical cone.

The ellipse is centered around the (lon, lat) position. a (resp. b) corresponds to the semi-major axis magnitude (resp. semi-minor axis magnitude). pa is expressed as a Angle and defines the position angle of the elliptical cone. The coordinates should be expressed in equatorial coordinates using the ICRS reference. We follow the convention for Space MOCs.

Parameters:

lonastropy.coordinates.Longitude or its supertype astropy.units.Quantity: The longitude of the center of the elliptical cone.
latastropy.coordinates.Latitude or its supertype astropy.units.Quantity: The latitude of the center of the elliptical cone.
aastropy.coordinates.Angle: The semi-major axis angle of the elliptical cone.
bastropy.coordinates.Angle: The semi-minor axis angle of the elliptical cone.
paastropy.coordinates.Angle: The position angle (i.e. the angle between the north and the semi-major axis, east-of-north).
max_depthint: Maximum HEALPix cell resolution.
delta_depthint, optional: To control the approximation, you can choose to perform the computations at a deeper depth using the delta_depth parameter. The depth at which the computations will be made will therefore be equal to depth + delta_depth.

Returns:

MOC: The resulting MOC

Examples

>>> from mocpy import MOC
>>> import astropy.units as u
>>> from astropy.coordinates import Angle, Longitude, Latitude
>>> moc = MOC.from_elliptical_cone(
...  lon=Longitude(0 * u.deg),
...  lat=Latitude(0 * u.deg),
...  a=Angle(10, u.deg),
...  b=Angle(5, u.deg),
...  pa=Angle(0, u.deg),
...  max_depth=10
... )

classmethod from_fits(path_or_url, timeout=1000)¶

Load a MOC from a FITS file.

The specified FITS file must store the MOC (i.e. the list of HEALPix cells it contains) in a binary HDU table.

Parameters:

path_or_urlstr: The path to the FITS file.
timeoutfloat: Timeout for the query, defaults to 1000s

Returns:

mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The resulting MOC.

classmethod from_fits_image(hdu, max_norder, mask=None, approximate=False)[source]¶

Create a MOC from an image stored as a FITS file.

Parameters:

hduHDU object: HDU containing the data of the image
max_norderint: The moc resolution.
masknumpy.ndarray, optional: A boolean array of the same shape than the image where True valued pixels are part of the final MOC and False valued pixels are not.

Returns:

MOC: The resulting MOC.

Notes

When giving a mask, the MOC computed will only take into account the center of the image pixels and not the whole pixel borders. This leads to an approximate resulting MOC.

classmethod from_fits_images(path_l, max_norder, hdu_index=0, approximate=False)[source]¶

Load a MOC from a set of FITS file images.

Parameters:

path_l[str]: A list of path where the fits images are located.
max_norderint: The MOC resolution.
hdu_indexint, optional: Index of the the HDUs containing the image in each FITS file (default = 0) If set to -1, all the HUD will be taken in account, and only the ones corresponding to images will be kept.
approximatebool, optional: A faster but less precise way to build the MOC out of the images. This does not mask the boolean values, and will approximate each image as a polygon defined by the footprint deduced from the WCS. Default is False.

Returns:

mocMOC: The union of all the MOCs created from the paths found in path_l.

classmethod from_healpix_cells(ipix, depth, max_depth)[source]¶

Create a MOC from a set of HEALPix cells at various depths.

Parameters:

ipixnumpy.ndarray: HEALPix cell indices in the NESTED notation. dtype must be np.uint64
depthnumpy.ndarray or int: Depth of the HEALPix cells. Must be of the same size of ipix. dtype must be np.uint8. Corresponds to the level of an HEALPix cell in astropy.healpix.
max_depthint, The resolution of the MOC (degrades on the fly input cells if necessary)

Returns:

MOC: The MOC

Raises:

IndexError: When ipix and depth do not have the same shape

Examples

>>> from mocpy import MOC
>>> import numpy as np
>>> # Create HEALPix cells at order 3
>>> ipix = np.array([5, 10, 15, 20, 25], dtype='uint64')
>>> depth = np.array([3] * 5, dtype='uint8')
>>> moc = MOC.from_healpix_cells(ipix, depth, max_depth=3)
>>> moc
3/5 10 15 20 25

classmethod from_ivorn(ivorn, max_depth: int = 8, nside=None)[source]¶

Create a MOC object from a given IVORN.

IVORNs are standardized unique identifiers used within the virtual observatory. This method queries the MOCServer, a CDS service that can also be found through its webpages https://alasky.cds.unistra.fr/MocServer/query

Parameters:

ivornstr: A valid Virtual Observatory IVORN
max_depthint, defaults to 8: The depth at which the MOC should be retrieved.
nsideint, optional and deprecated: It is deprecated in favor of max_depth since version 0.6.0

Returns:

MOC: The resulting MOC.

Notes

This is a rudimentary way to retrieve MOCs from the MOCServer. For a more complete implementation, see the MOCServer module in the astroquery library.

Examples

>>> from mocpy import MOC
>>> MOC.from_ivorn("ivo://CDS/J/A+AS/133/387/table5")
7/96462 96481 96484-96486
8/385839 385852 385854-385855 385933 385948-385950 385969 385984 385986

classmethod from_json(json_moc)¶

Create a MOC from a dictionary of HEALPix cell arrays indexed by their depth.

Parameters:

json_mocdict(str[int]: A dictionary of HEALPix cell arrays indexed by their depth.

Returns:

mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: the MOC.

classmethod from_lonlat(lon, lat, max_norder)[source]¶

Create a MOC from astropy lon, lat astropy.units.Quantity.

The coordinates should be expressed in equatorial coordinates using the ICRS reference. We follow the Space MOC standard.

Parameters:

lonastropy.coordinates.Longitude or its supertype astropy.units.Quantity: The longitudes of the sky coordinates belonging to the MOC.
latastropy.coordinates.Latitude or its supertype astropy.units.Quantity: The latitudes of the sky coordinates belonging to the MOC.
max_norderint: The depth of the smallest HEALPix cells contained in the MOC.

Returns:

MOC: The resulting MOC

Examples

>>> from mocpy import MOC
>>> from astropy.coordinates import Longitude, Latitude
>>> lon = Longitude([0, 1, 2], unit="deg")
>>> lat = Latitude([0, 1, 2], unit="deg")
>>> moc = MOC.from_lonlat(lon, lat, max_norder=5)
>>> moc # the three coordinates are in the same two cells of order 5
5/4864-4865

classmethod from_multiordermap_fits_file(path, cumul_from=0.0, cumul_to=1.0, asc=False, strict=True, no_split=True, reverse_decent=False)[source]¶

Create a MOC from a mutli-order map FITS file.

HEALPix cells are first sorted by their values. The MOC contains the cells from which the cumulative value is between cumul_from and cumul_to. Cells being on the fence are recursively splitted and added until the depth of the cells is equal to max_norder.

For compatibility with Aladin, use no_split=False and reverse_decent=True

Remark: using no_split=False, the way the cells overlapping with the low and high thresholds are split is somewhat arbitrary.

Parameters:

pathstr or pathlib.Path: The path to the file to save the MOC in.
cumul_fromfloat: Cumulative value from which cells will be added to the MOC
cumul_tofloat: Cumulative value to which cells will be added to the MOC
asc: boolean: the cumulative value is computed from lower to highest densities instead of from highest to lowest
strict: boolean: (sub-)cells overlapping the cumul_from or cumul_to values are not added
no_split: boolean: cells overlapping the cumul_from or cumul_to values are not recursively split
reverse_decent: boolean: perform the recursive decent from the highest cell number to the lowest (to be compatible with Aladin)

Returns:

MOC: The resulting MOC

classmethod from_polygon(lon, lat, complement=False, max_depth=10)[source]¶

Create a MOC from a polygon.

The polygon is given as lon and lat astropy.units.Quantity that define the vertices of the polygon. Concave, convex and self-intersecting polygons are accepted. The coordinates should be expressed in equatorial coordinates using the ICRS reference. We follow the Space MOC standard.

Parameters:

lonastropy.coordinates.Longitude or its supertype astropy.units.Quantity: The longitudes defining the polygon.
latastropy.coordinates.Latitude or its supertype astropy.units.Quantity: The latitudes defining the polygon. Can describe convex and concave polygons but not self-intersecting ones.
complementreturn the complement of the polygon. Set to False by default.: The default polygon is the smallest one.
max_depthint, optional: The resolution of the MOC. Set to 10 by default.

Returns:

MOC: The resulting MOC

See also

from_polygons
from_polygons_skycoord

Examples

>>> from mocpy import MOC
>>> from astropy.coordinates import Angle
>>> lon = Angle([0, 10, 10, 0], unit="deg")
>>> lat = Angle([0, 0, 10, 10], unit="deg")
>>> moc = MOC.from_polygon(lon, lat, max_depth=5)
>>> moc
4/1131 1134 1216-1217 1219-1222
5/4517-4519 4521-4523 4528 4530-4531 4540 4542-4543 4873 4892 4901 4912
>>> moc.barycenter()
<SkyCoord (ICRS): (ra, dec) in deg
    (4.92337884, 5.40015256)>

classmethod from_polygon_skycoord(skycoord, complement=False, max_depth=10)[source]¶

Create a MOC from a polygon.

The polygon is given as an astropy.coordinates.SkyCoord that contains the vertices of the polygon. Concave, convex and self-intersecting polygons are accepted.

Parameters:

skycoordastropy.coordinates.SkyCoord: The sky coordinates defining the vertices of a polygon.
complementreturn the complement of the polygon. Set to False by default.: The default polygon is the smallest one.
max_depthint, optional: The resolution of the MOC. Set to 10 by default.

Returns:

MOC: The resulting MOC

See also

from_polygon
from_polygons

Examples

>>> from astropy.coordinates import SkyCoord
>>> from mocpy import MOC
>>> MOC.from_polygon_skycoord(SkyCoord([80, 82, 76], [36, 33, 33], unit="deg"))
6/1293
7/5149-5151 5165 5169-5171 5176-5177 5180-5181 5186 5192 5194 5216 5218-5219
...

classmethod from_polygons(list_vertices, complement=False, max_depth=10, n_threads=None)[source]¶

Create a list of MOCs list from a list of polygons.

Parameters:

list_verticeslist[SkyCoord] OR numpy.ndarray: If list_vertices is a list of SkyCoord objects, each SkyCoord object should contain more than three vertices and they should each describe a polygon. If list_vertices is a numpy.ndarray, it should be in the form [lon_array1, lat_array1, lon_array2, lat_array2, lon_array3, lat_array3, …]. They should be valid longitudes and latitudes in degrees in ICRS.
complementreturn the complement of the polygon. Set to False by default.: The default polygon is the smallest one.
max_depthint, optional: The resolution of the MOC. Set to 10 by default.
n_threadsint, optional: The number of threads to be used. If this is set to None (default value), all available threads will be used.

Returns:

list[mocpy.MOC]

See also

from_polygon
from_polygon_skycoord

Examples

>>> from astropy.coordinates import SkyCoord
>>> from mocpy import MOC
>>> list_vertices = [
...     SkyCoord([-4, 4, 4, -4], [4, 4, -4, -4], unit="deg"),
...     SkyCoord([0, 6, 0, -6], [6, 0, -6, 0], unit="deg")
... ]
>>> list_mocs = MOC.from_polygons(list_vertices)
>>> # without the SkyCoord object, we need to adapt the coordinates
>>> list_vertices = [[356, 4, 4, 356], [4, 4, -4, -4],
...                  [0, 6, 0, 354], [6, 0, -6, 0]]
>>> list_mocs_no_check_no_wrap = MOC.from_polygons(list_vertices)
>>> list_mocs == list_mocs_no_check_no_wrap
True

classmethod from_ring(lon, lat, internal_radius, external_radius, max_depth, delta_depth=2)[source]¶

Create a MOC from a ring.

The cone is centered around the (lon, lat) position with an internal radius expressed by internal_radius and an external radius expressed by external_radius. The coordinates should be expressed in equatorial coordinates using the ICRS reference. We follow the Space MOC standard.

Parameters:

lonastropy.coordinates.Longitude or its supertype astropy.units.Quantity: The longitude of the center of the ring.
latastropy.coordinates.Latitude or its supertype astropy.units.Quantity: The latitude of the center of the ring.
internal_radiusastropy.coordinates.Angle: The internal radius angle of the ring.
external_radiusastropy.coordinates.Angle: The external radius angle of the ring.
max_depthint: Maximum HEALPix cell resolution.
delta_depthint, optional: To control the approximation, you can choose to perform the computations at a deeper depth using the delta_depth parameter. The depth at which the computations will be made will therefore be equal to max_depth + delta_depth.

Returns:

MOC: The resulting MOC

Examples

>>> from mocpy import MOC
>>> import astropy.units as u
>>> from astropy.coordinates import Angle, Longitude, Latitude
>>> moc = MOC.from_ring(
...  lon=Longitude(0 * u.deg),
...  lat=Latitude(0 * u.deg),
...  internal_radius=Angle(5, u.deg),
...  external_radius=Angle(10, u.deg),
...  max_depth=10
... )

classmethod from_sfmoc_frequency_fold(fmoc, sfmoc)[source]¶

Build a S-MOC from the fold operation of the given SF-MOC by the given F-MOC.

Parameters:

fmocFrequencyMOC
sfmocSFMOC

Returns:

MOC

Examples

>>> from mocpy import MOC, FrequencyMOC, SFMOC
>>> sfmoc = SFMOC.from_string('''
... f15/0-10
... s12/0-100
... f15/11-20
... s12/101-200
... ''')
>>> fmoc = FrequencyMOC.from_string("15/0-2")
>>> MOC.from_sfmoc_frequency_fold(fmoc, sfmoc)
9/0
10/4-5
11/24
12/100

classmethod from_skycoords(skycoords, max_norder)[source]¶

Create a MOC from an astropy.coordinates.SkyCoord.

Parameters:

skycoordsastropy.coordinates.SkyCoord: The sky coordinates that will belong to the MOC.
max_norderint: The depth of the smallest HEALPix cells contained in the MOC.

Returns:

MOC: The resulting MOC

Examples

>>> from mocpy import MOC
>>> from astropy.coordinates import SkyCoord
>>> coords = SkyCoord([0, 1, 2], [0, 1, 2], unit="deg")
>>> moc = MOC.from_skycoords(coords, max_norder=5)
>>> moc # the three coordinates are in the same two cells of order 5
5/4864-4865

classmethod from_stcs(stcs, max_depth, delta_depth=2)[source]¶

Create a MOC from a STC-S.

Time, Spectral and Redshift sub-phrases are ignored.

Parameters:

stcsstr: The STC-S string.
max_depthint: Maximum HEALPix cell resolution.
delta_depthint, optional: To control the approximation, you can choose to perform the computations at a deeper depth using the delta_depth parameter. The depth at which the computations will be made will therefore be equal to max_depth + delta_depth.

Returns:

MOC: The resulting MOC

Warning

There is so far no implicit conversion, so the STC-S string will be rejected if: * the frame is different from ICRS * the flavor is different from Spher2 * the units are different from degrees The implementation is not (yet?) fully compliant with the STC standard (see MOC Lib rust for more details): * DIFFERENCE is so far interpreted as a symmetrical difference (XOR) while it is a MINUS in the STC standard * Self-intersecting Polygons are supported, and the “interior” usually has the smallest area

Examples

>>> from mocpy import MOC
>>> moc1 = MOC.from_stcs("Circle ICRS 147.6 69.9 0.4", max_depth=14)
>>> moc2 = MOC.from_cone(lon=147.6 * u.deg, lat=69.9 * u.deg,
...                      radius=Angle(0.4, u.deg), max_depth=14)
>>> moc1 == moc2
True

classmethod from_stmoc_time_fold(tmoc, stmoc)[source]¶

Build a new S-MOC from the fold operation of the given ST-MOC by the given T-MOC.

Parameters:

tmocTimeMOC
stmocSTMOC

Returns:

MOC

Examples

>>> from mocpy import MOC, TimeMOC, STMOC
>>> from astropy.time import Time
>>> import astropy.units as u
>>> from astropy.coordinates import Angle, Longitude, Latitude
>>> time_min = Time("2026-01-01")
>>> time_max = Time("2026-01-10")
>>> tmoc = TimeMOC.from_time_ranges(time_min, time_max)
>>> moc = MOC.from_cone(0*u.deg, 0*u.deg, radius=10*u.arcmin, max_depth=5)
>>> stmoc = STMOC.from_spatial_coverages(time_min, time_max, [moc])
>>> MOC.from_stmoc_time_fold(tmoc, stmoc)
5/4351 4522 4693 4864

classmethod from_str(value)¶

Create a MOC from a string.

This grammar is expressed is the MOC IVOA specification at section 2.3.2.

Parameters:

valuestr: The MOC as a string following the grammar rules.

Returns:

mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The resulting MOC

See also

from_string: a duplicate of this method, with added fold option

Examples

>>> from mocpy import MOC
>>> moc = MOC.from_str("2/2-25 28 29 4/0 6/")

classmethod from_string(value, format='ascii')[source]¶

Deserialize the Spatial MOC from the given string.

Format can be ‘ascii’ or ‘json’, though the json format is not officially supported by the IVOA.

WARNING: the serialization must be strict, i.e. must not contain overlapping elements

Parameters:

formatstr, optional: The format in which the MOC will be serialized before being saved. Possible formats are “ascii” or “json”. By default, format is set to “ascii”.

Returns:

MOC

Examples

>>> from mocpy import MOC
>>> MOC.from_string("3/0-1")
3/0-1

classmethod from_url(url)[source]¶

Create a MOC object from a given url.

Parameters:

urlstr: The url of a FITS file storing a MOC.

Returns:

MOC: The resulting MOC.

classmethod from_valued_healpix_cells(uniq, values, max_depth=None, values_are_densities=False, cumul_from=0.0, cumul_to=1.0, asc=False, strict=True, no_split=True, reverse_decent=False)[source]¶

Create a MOC from a list of uniq associated with values.

HEALPix cells are first sorted by their values. The MOC contains the cells from which the cumulative value is between cumul_from and cumul_to. Cells being on the fence are recursively splitted and added until the depth of the cells is equal to max_norder.

For compatibility with Aladin, use no_split=False and reverse_decent=True

Remark: using no_split=False, the way the cells overlapping with the low and high thresholds are split is somewhat arbitrary.

Parameters:

uniqnumpy.ndarray: HEALPix cell indices written in uniq. dtype must be np.uint64
valuesnumpy.ndarray: Value associated with each uniq cells. dtype must be np.float64
max_depthint: The max depth of the MOC, should be at least as large as the depth corresponding of the smallest HEALPix cell found in uniq. Warnings: 1 - the depth of the returned MOC will be at least as deep as the smallest HEALPix cell found in uniq. 2 - contrary to MOCPy before v0.12, the user has to degrade the MOC if max_depth < smallest HEALPix cell depth.
values_are_densities: tell whether the values depend on the cell area or not
cumul_fromfloat: Cumulative value from which cells will be added to the MOC
cumul_tofloat: Cumulative value to which cells will be added to the MOC
asc: boolean: the cumulative value is computed from lower to highest densities instead of from highest to lowest
strict: boolean: (sub-)cells overlapping the cumul_from or cumul_to values are not added
no_split: boolean: cells overlapping the cumul_from or cumul_to values are not recursively split
reverse_decent: boolean: perform the recursive decent from the highest cell number to the lowest (to be compatible with Aladin)

Returns:

MOC: The resulting MOC

classmethod from_vizier_table(table_id, max_depth=None, nside=None)[source]¶

Create a MOC object from a VizieR table or catalog.

Parameters:

table_idstr: Table or catalog identifier
max_depthint, optional: The depth at which the MOC should be retrieved. The default (which is also the most precise available on the server) is order 11 for tables and order 10 for catalogs.
nsideint, optional and deprecated: It is deprecated in favor of max_depth since version 0.6.0 You can switch to max_depth by calculating max_depth = log2(nside).

Returns:

MOC: The resulting MOC.

Notes

VizieR is organized by catalogs that correspond to published articles or to data releases. These catalogs contain one or more tables.

Here are two webpages where you can read the list of catalogs and the list of tables currently available.

Examples

>>> from mocpy import MOC
>>> moc = MOC.from_vizier_table("J/A+A/675/A154") # download the MOC
>>> round(moc.sky_fraction, 6) # let's print the sky fraction of the MOC
1.6e-05

classmethod from_zone(coordinates, max_depth)[source]¶

Create a MOC from a zone.

The zone is defined by a range of longitudes and latitudes. Its sides follow great circles in longitudes and small circles for latitudes. The bottom and left sides are included in the MOC, while the top and right sides are not.

Parameters:

coordinatesSkyCoord: A couple of coordinates for the bottom left and the upper right corner of the zone.
max_depthint: Maximum HEALPix cell resolution.

Returns:

MOC: The resulting MOC

Examples

>>> from mocpy import MOC
>>> from astropy.coordinates import SkyCoord
>>> moc = MOC.from_zone(
...  SkyCoord([[0, 0], [20, 20]], unit="deg"),
...  max_depth=5
... )

get_boundaries(order=None)[source]¶

Return the sky coordinates defining the border(s) of the MOC.

The border(s) are expressed as a list of SkyCoord. Each SkyCoord refers to the coordinates of one border of the MOC (i.e. either a border of a connected MOC part or a border of a hole located in a connected MOC part). This function is currently not stable: encoding a vertex of a HEALPix cell (N, E, S, W) should not depend on the position of the vertex but rather on the uniq value (+ 2 bits to encode the direction of the vertex).

Parameters:

orderint: The depth of the MOC before computing its boundaries. A shallow depth leads to a faster computation. By default the maximum depth of the MOC is taken.

Returns:

[SkyCoord]: A list of SkyCoord each describing one border.

Raises:

DeprecationWarning: This method is not stable and not tested! A future more stable algorithm will be implemented!

Examples

>>> from mocpy import MOC
>>> from astropy.coordinates import SkyCoord
>>> moc = MOC.from_string("3/0-7")
>>> boundaries = moc.get_boundaries()
>>> boundaries
[<SkyCoord (ICRS): (ra, dec) in deg
    [(50.625, 24.62431835), (45.   , 19.47122063), (39.375, 14.47751219),
     (33.75 ,  9.59406823), (39.375,  4.78019185), (45.   ,  0.        ),
     (50.625,  4.78019185), (56.25 ,  9.59406823), (61.875, 14.47751219),
     (67.5  , 19.47122063), (61.875, 24.62431835), (56.25 , 30.        )]>]

intersection(another_moc, *mocs)¶

Intersection between the MOC instance and other MOCs.

Parameters:

another_mocmocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The MOC to do the intersection with.
mocsmocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: Other additional MOCs to perform the intersection with.

Returns:

mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The resulting MOC.

Examples

>>> from mocpy import FrequencyMOC
>>> import astropy.units as u
>>> fmoc_large_band = FrequencyMOC.from_frequency_ranges(order=42,
...                                                      min_freq=0.1*u.Hz,
...                                                      max_freq=100*u.Hz)
>>> fmoc_sharp_band = FrequencyMOC.from_frequency_ranges(order=42,
...                                                      min_freq=10*u.Hz,
...                                                      max_freq=20*u.Hz)
>>> fmoc_sharp_band.intersection(fmoc_large_band) == fmoc_sharp_band
True

largest_distance_from_coo_to_vertices(coo)[source]¶

Return the largest distance between the given coordinates and vertices of the MOC cells.

Examples

>>> from mocpy import MOC
>>> from astropy.coordinates import SkyCoord
>>> coo = SkyCoord(0, 0, unit="deg")
>>> moc = MOC.from_string("15/600")
>>> moc.largest_distance_from_coo_to_vertices(coo).to("deg")
<Quantity 44.99314494 deg>

classmethod load(path, format='fits')[source]¶

Load the Spatial MOC from a file.

Format can be ‘fits’, ‘ascii’, or ‘json’, though the json format is not officially supported by the IVOA.

Parameters:

pathstr or pathlib.Path: The path to the file to load the MOC from.
formatstr, optional: The format from which the MOC is loaded. Possible formats are “fits”, “ascii” or “json”. By default, format is set to “fits”.

Returns:

MOC

mask_uniq(uniq, uniq_mask=None, fully_covered_only=False)[source]¶

Get a mask for an array of uniq cells intersecting the MOC.

Parameters:

uniqarray: An array on integers corresponding to HEALPix cells in the uniq notation.
uniq_maskarray, optional: An optional array to mask the uniq array. Set to True where the values of the uniq array should be ignored (following the numpy masked_array convention).
fully_covered_onlybool, optional: If True, keep only uniq cells that are fully covered by the MOC. Otherwise, also keep cells that intersect the MOC. By default False.

Returns:

array: A mask that is True where the uniq cell is comprised (or at least intersects depending on ‘fully_covered_only’) in the MOC and False otherwise

Examples

>>> from mocpy import MOC
>>> uniq = [4 * 4**3 + x for x in range(8)] # corresponds to 3/0-7
>>> moc = MOC.from_str("3/4-20")
>>> moc.mask_uniq(uniq) # the first four cells are NOT intersecting
array([False, False, False, False,  True,  True,  True,  True])

property max_index¶: Return the largest index (at the deepest absolute resolution) the MOC contains.

property max_order¶

Depth/order of the S-MOC.

Examples

>>> from mocpy import MOC
>>> MOC.from_string("3/0-1").max_order
3

property min_index¶: Return the smallest index (at the deepest absolute resolution) the MOC contains.

classmethod n_cells(depth)[source]¶

Get the number of cells for a given depth.

Parameters:

depthint: The depth. It is comprised between 0 and MAX_ORDER

Returns:

int: The number of cells at the given order

Examples

>>> from mocpy import MOC
>>> MOC.n_cells(0)
12

classmethod new_empty(max_depth)[source]¶

Create a new empty MOC of given depth.

Parameters:

max_depthint, The resolution of the MOC

Returns:

mocMOC: The MOC

Examples

>>> from mocpy import MOC
>>> moc = MOC.new_empty(max_depth=5)
>>> moc.empty()
True

static order_to_spatial_resolution(order)[source]¶

Convert a depth to its equivalent spatial resolution.

Parameters:

orderint: Spatial depth.

Returns:

spatial_resolutionAngle: Spatial resolution.

Examples

>>> from mocpy import MOC
>>> MOC.order_to_spatial_resolution(0)
<Angle 1.02332671 rad>
>>> MOC.order_to_spatial_resolution(5).to("deg")
<Angle 1.83225942 deg>

plot(title='MOC', frame=None)[source]¶

Plot the MOC object using a mollweide projection.

Deprecated: New fill and border methods produce more reliable results and allow you to specify additional matplotlib style parameters.

Parameters:

titlestr: The title of the plot
frameastropy.coordinates.BaseCoordinateFrame, optional: Describes the coordinate system the plot will be (ICRS, Galactic are the only coordinate systems supported).

classmethod probabilities_in_multiordermap(mocs, multiordermap, n_threads=None)[source]¶

Calculate the probabilities in the intersection between the multiordermap and the MOCs.

Multi-MOC version of probability_in_multiordermap. This is parallelized.

Parameters:

mocslist[mocpy.MOC]: A list of mocpy.MOC.
multiordermapastropy.table.Table, or astropy.table.QTable: Should have a column UNIQ that corresponds to HEALPix cells and a PROBDENSITY column.
n_threadsint: Number of threads to be used (all available threads by default)

Returns:

list[float]: A list containing the probability for each MOC

See also

probability_in_multiordermap: calculates the probability for a single MOC

Notes

In wasm compilations (ex for pyodide), this won’t raise an error, but will be single-threaded.

Examples

>>> from mocpy import MOC
>>> import numpy as np
>>> from astropy.table import Table
>>> moc1 = MOC.from_str("0/0-11")
>>> moc2 = MOC.from_str("0/0-11")
>>> # Create a multiorder map
>>> uniq = [4 + x for x in range(20)]
>>> probdensity = np.arange(20, dtype='float64') / 1000
>>> multi_order_map = Table([uniq, probdensity], names=("UNIQ", "PROBDENSITY"))
>>> probabilities = MOC.probabilities_in_multiordermap([moc1, moc2], multi_order_map)
>>> [round(p, 4) for p in probabilities]
[np.float64(0.1016), np.float64(0.1016)]

probability_in_multiordermap(multiordermap)[source]¶

Calculate the probability in the intersection between the multiordermap and the MOC.

PROBDENSITY values are multiplied by the area of their associated HEALPix cell before summing them. For cells that are not complete, the ratio of the area is used.

Parameters:

multiordermapstr, pathlib.Path, astropy.table.Table, or astropy.table.QTable: If multiordermap is given as a string or Path, the probability will be read from the column PROBDENSITY of the FITS file. If it is an Table, then it should have a column UNIQ that corresponds to HEALPix cells and a PROBDENSITY column.

Returns:

float: The probability in the intersection between the MOC and the Multi-Order-Map coverages.

See also

probabilities_in_multiordermap: makes this calculation for a list of MOCs

Examples

>>> from mocpy import MOC
>>> import numpy as np
>>> from astropy.table import Table
>>> all_sky = MOC.from_str("0/0-11")
>>> # Let's create a meaningless multiorder map
>>> uniq = [4 * 4**4 + x for x in range(20)]
>>> rng = np.random.default_rng(0)
>>> probdensity = rng.random(20) / 100
>>> multi_order_map = Table([uniq, probdensity], names=("UNIQ", "PROBDENSITY"))
>>> # The probability to be in the intersection with the all sky is
>>> round(all_sky.probability_in_multiordermap(multi_order_map), 4)
0.0004

query_simbad(*, max_rows=20, timeout=100, select: List[str] | None = None, output_format: Literal['csv', 'votable', 'astropy_table', 'raw_votable'] = 'astropy_table')[source]¶

Query a view of SIMBAD data for SIMBAD objects in the coverage of the MOC instance.

Parameters:

select: list[str], optional: list of columns names to get
output_format: str: format of the output. Can be astropy_table, csv, votable. Defaults to astropy_table.
max_rowsint, optional: maximum number of row returned
timeoutfloat, optional: timeout before aborting the query, default to 1000s

Examples

>>> from mocpy import MOC
>>> moc = MOC.from_string("8/8")
>>> moc.query_simbad(select=["main_id", "main_type", "ra", "dec"])
<Table length=20>
         main_id          main_type        ra          dec
                                          deg          deg
          str47             str24       float64      float64
------------------------- ---------- ------------- ------------
         UCAC4 452-003925       Star 44.6443212394 0.3253648570
  2MASS J02583486+0018256  Low-Mass* 44.6452974235 0.3071523434
 SDSS J025833.42+001827.8     Galaxy 44.6392515000 0.3077166944
 SDSS J025834.86+001909.4     Galaxy 44.6452449583 0.3192827222

query_vizier_table(table_id: str, *, max_rows=20, timeout=1000, select: List[str] | None = None, output_format: Literal['csv', 'votable', 'astropy_table', 'raw_votable'] = 'astropy_table')[source]¶

Query a VizieR table for sources in the coverage of the MOC instance.

Parameters:

table_idstr: corresponds to a VizieR table id
max_rowsint, optional: maximum number of row returned. Defaults to 20.
select: list[str], optional: list of columns names to get
output_format: str: format of the output. Can be astropy_table, csv, votable, raw_votable. Defaults to astropy_table.
timeoutfloat, optional: timeout before aborting the query, default to 1000s

Examples

>>> from mocpy import MOC
>>> moc = MOC.from_string("8/8")
>>> moc.query_vizier_table("I/356/galcand", select=["_RAJ2000", "_DEJ2000", "Source", "Class"])
<Table length=14>
     _RAJ2000          _DEJ2000         Source     Class
       deg               deg
     float64           float64          int64      str15
----------------- ----------------- -------------- ------
 44.6843243031726   0.3791206034138 71227737716736 GALAXY
 44.7188162775362   0.4228615299936 72950020326912 GALAXY
 44.7729085577324   0.4505931771995 73431056703232
 44.7136268288791   0.4730577467229 74491913012736
 44.7287948285102   0.4925353924758 74633647504896
 44.5342650132047   0.4027725848738 75045964534784 GALAXY
 44.5263730061065   0.4071591551830 75110388154496 GALAXY
 44.6285193604069   0.4605212441601 75561360607616 GALAXY
 44.5245963539355   0.4362714696582 75973677274624 GALAXY
 44.5604330887281   0.4596071816413 76420353872128 GALAXY
 44.6325844046418   0.4818690478764 77279347329280 GALAXY
 44.6964365662775   0.5070763948648 77622944909184 GALAXY
 44.7234359415639   0.5170502484962 77691664219008 GALAXY
 44.6847962277679   0.5404173644997 77996606346240 GALAXY

refine_to_order(new_order)[source]¶

Refine the order of the MOC instance to a more precise order.

This is an in-place operation.

Parameters:

new_orderint: New maximum order for this MOC.

Returns:

mocpy.MOC: Returns itself, after in-place modification.

Examples

>>> from mocpy import MOC
>>> moc = MOC.from_str("3/10")
>>> moc.refine_to_order(5)
3/10
5/

remove_neighbours()¶

Remove from the MOC instance the HEALPix cells located at its border.

The depth of the HEALPix cells removed is equal to the maximum depth of the MOC instance.

Returns:

mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: self minus its HEALPix cells located at its border.

save(path, format='fits', overwrite=False, v1_compatible=False, fold=0, fits_keywords=None, pre_v2=None)¶

Write the MOC to a file.

Format can be ‘fits’, ‘ascii’, or ‘json’, though the json format is not officially supported by the IVOA.

Parameters:

pathstr or pathlib.Path: The path to the file to save the MOC in.
formatstr, optional: The format in which the MOC is saved. Possible formats are “fits”, “ascii” or “json”. By default, format is set to “fits”.
overwritebool, optional: If the file already exists and you want to overwrite it, then set the overwrite keyword. Default to False.
v1_compatiblebool, optional: If True, write a v2 MOC that can be read by v1 parsers (using NUNIQ ordering for spatial MOCs). Default to False (MOC 2.0 standard range-encoded).
fold: int: if >0, print ascii or json output with a maximum line width
fits_keywords: dict, optional: Additional keywords to add to the FITS header.
pre_v2bool, optional: Deprecated since v0.21.0. Use v1_compatible instead.

serialize(format='fits', optional_kw_dict=None, v1_compatible=False, pre_v2=None)¶

Serialize the MOC into a specific format.

Possible formats are FITS, JSON and STRING

Parameters:

formatstr: ‘fits’ by default. The other possible choice is ‘json’ or ‘str’.
optional_kw_dictdict: Optional keywords arguments added to the FITS header. Only used if format equals to ‘fits’.
v1_compatiblebool, optional: If True, write a v2 MOC that can be read by v1 parsers (using NUNIQ ordering for spatial MOCs). Default to False (MOC 2.0 standard range-encoded).
pre_v2bool, optional: Deprecated since v0.21.0. Use v1_compatible instead.

Returns:

resultastropy.io.fits.HDUList or JSON dictionary: The result of the serialization.

property sky_fraction¶

Sky fraction covered by the MOC.

Examples

>>> from mocpy import MOC
>>> MOC.from_string("0/0-11").sky_fraction # all sky
1.0

static spatial_resolution_to_order(spatial_resolution)[source]¶

Convert a spatial resolution to a MOC order.

Parameters:

spatial_resolutionAngle: Spatial resolution

Returns:

orderint: The order corresponding to the spatial resolution

Examples

>>> from mocpy import MOC
>>> from astropy.coordinates import Angle
>>> MOC.spatial_resolution_to_order(Angle(1, "deg"))
np.uint8(6)
>>> MOC.spatial_resolution_to_order(Angle(5, "arcsec"))
np.uint8(16)

split(include_indirect_neighbours=False)[source]¶

Return the disjoint MOCs this MOC contains.

Parameters:

include_indirect_neighboursbool: if false, only consider cells having a common edge as been part of a same MOC if true, also consider cells having a common vertex as been part of the same MOC

Returns:

MOC

Notes

Use split_count first to ensure the number is not too high

Examples

>>> from mocpy import MOC
>>> moc = MOC.from_string("3/0-3")
>>> len(moc.split())
1
>>> mocs = MOC.from_string("5/0 5/12").split()
>>> mocs[0]
5/0
>>> mocs[1]
5/12

split_count(include_indirect_neighbours=False)[source]¶

Return the number of disjoint MOCs the given MOC contains.

Parameters:

include_indirect_neighboursbool: if false, only consider cells having a common edge as been part of a same MOC if true, also consider cells having a common vertex as been part of the same MOC

Returns:

int

Examples

>>> from mocpy import MOC
>>> moc = MOC.from_string("3/0-3")
>>> moc.split_count()
1
>>> moc = MOC.from_string("5/0 5/12")
>>> moc.split_count()
2

sum_in_multiordermap(multiordermap: Table, column: str)[source]¶

Calculate the sum of a column from a multiordermap in the intersection with the MOC.

Parameters:

multiordermapastropy.table.Table: The table should have a column UNIQ that corresponds to HEALPix cells in the uniq notation.
columnstr: The name of the column to sum. It should be compatible with a float conversion.

Returns:

float: The sum of the values in the intersection between the MOC and the multiorder map coverages.

Examples

>>> from mocpy import MOC
>>> import numpy as np
>>> from astropy.table import Table
>>> all_sky = MOC.from_str("0/0-11")
>>> # Let's create a meaningless multiorder map
>>> uniq = [4 * 4**5 + x for x in np.arange(200)]
>>> rng = np.random.default_rng(0)
>>> column = rng.random(200)
>>> multi_order_map = Table([uniq, column], names=("UNIQ", "column"))
>>> round(all_sky.sum_in_multiordermap(multi_order_map, "column"), 4)
107.9259

symmetric_difference(another_moc, *mocs)¶

Symmetric difference (XOR) between the MOC instance and other MOCs.

a XOR b == (a and not b) or (not a and b) It is not implemented yet for STMOCs

Parameters:

another_mocmocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The MOC used that will be subtracted to self.
mocsmocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: Other additional MOCs to perform the difference with.

Returns:

mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The resulting MOC.

Examples

>>> from mocpy import MOC
>>> moc1 = MOC.from_string("3/0-1 362-363")
>>> moc2 = MOC.from_string("3/0 2 277 279")
>>> moc1.symmetric_difference(moc2)
3/1-2 277 279 362-363

property to_depth29_ranges¶

Return the list of order 29 HEALPix nested ranges this MOC contains.

Examples

>>> from mocpy import MOC
>>> moc = MOC.from_string("0/0-1")
>>> moc.to_depth29_ranges
array([[                 0, 576460752303423488]], dtype=uint64)

to_order(new_order)[source]¶

Create a new S-MOC with the new order.

This is a convenience method for a quick change of order. Using ‘degrade_to_order’ and ‘refine_to_order’ depending on the situation is more efficient and avoids copying the MOC when it is not needed.

Parameters:

new_orderint: The new order for the S-MOC. Can be either more or less precise than the current max_order of the S-MOC

Returns:

MOC: A new S-MOC instance with the given max order.

See also

degrade_to_order: to create a new less precise MOC
refine_to_order: to change the order to a more precise one in place (no copy)

Examples

>>> from mocpy import MOC
>>> moc = MOC.from_string("15/0-100")
>>> moc.to_order(15) # creates a copy
12/0
13/4-5
14/24
15/100

to_rgba(y_size=300)[source]¶

Create a matplotlib compatible RGBA preview of the given MOC.

Parameters:

y_sizethe number of pixels along the y-axis

Returns:

arrayA (2 * y_size, y_size, 4) array of 0-255 int values.

to_string(format='ascii', fold=0)¶

Write the MOC into a string.

Format can be ‘ascii’ or ‘json’, though the json format is not officially supported by the IVOA.

Parameters:

formatstr, optional: The format in which the MOC will be serialized before being saved. Possible formats are “ascii” or “json”. By default, format is set to “ascii”.
fold: int: if >0, print ascii or json output with a maximum line width

union(another_moc, *mocs)¶

Union between the MOC instance and other MOCs.

Parameters:

another_mocmocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The MOC to do the union with.
mocsmocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: Other additional MOCs to perform the union with.

Returns:

mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC: The resulting MOC.

Examples

>>> from mocpy import TimeMOC
>>> from astropy.time import Time, TimeDelta
>>> older = TimeMOC.from_time_ranges(min_times=Time('1999-01-01T00:00:00.123456789'),
...                                  max_times=Time('2005-01-01T00:00:00'),
...                                  delta_t = TimeDelta(1, format='jd')
...                                 )
>>> newer = TimeMOC.from_time_ranges(min_times=Time('2000-01-01T00:00:00'),
...                                  max_times=Time('2010-01-01T00:00:00'),
...                                  delta_t = TimeDelta(1, format='jd')
...                                 )
>>> union = older.union(newer) # == older + newer
>>> print(round(union.min_time.jyear, 4), round(union.max_time.jyear, 4))
1998.9985 2010.0018

property uniq_gen¶

Return a np.array of the generic uniq indices of the cell in the MOC.

Warning

This is not defined in the MOC standard and is not HEALPix scpecific.

Notes

It consists on the regular index with a sentinel bit placed at the immediate left of the index’s MSB. At a given depth, the sentinel bit is always put o the same bit.
Because the uniq HEALPix encoding is not adapted for non-HEALPIx indices.

property uniq_hpx¶

Return a np.array of the uniq HEALPIx indices of the cell in the MOC.

Notes

The output is not sorted, the order follow the order of HEALPix cells in the underlying sorted array of depth29 nested ranges, i.e. the natural order of the cells is the underlying z-order curve.

Examples

>>> from mocpy import MOC
>>> moc = MOC.from_string("0/0-11")
>>> moc.uniq_hpx
array([ 4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15], dtype=uint64)

property uniq_zorder¶

Return a np.array of the zorder uniq indices of the cell in the MOC.

Warning

This is not defined in the MOC standard and is not HEALPix specific.

Notes

It consists on a regular index shifted on the left so that indices at all level have the same MSB. Plus a sentinel bit placed at the immediate right of the LSB.
Because the uniq HEALPix encoding is not adapted for non-HEALPIx indices AND because the natural ordering of such indices follow the same order as the zorder indices (which is very useful for streaming processing, e.g. when dealing with multi-order maps)

values_and_weights_in_multiordermap(multiordermap: Table, column: str)[source]¶

Calculate the sum of a column from a multiordermap in the intersection with the MOC.

Parameters:

multiordermapastropy.table.Table: The table should have a column UNIQ that corresponds to HEALPix cells in the uniq notation.
columnstr: The name of the column to return. It should be compatible with a float conversion.

Returns:

Tuple(np.ndarray, np.ndarray)

Examples

>>> from mocpy import MOC
>>> import numpy as np
>>> from astropy.table import Table
>>> all_sky = MOC.from_str("0/0-11")
>>> # Create a multiorder map with order 0 cells
>>> uniq = [4 + x for x in range(8)]
>>> column = np.arange(8, dtype='float64')
>>> multi_order_map = Table([uniq, column], names=("UNIQ", "column"))
>>> values, weights = all_sky.values_and_weights_in_multiordermap(multi_order_map, "column")
>>> values
array([0., 1., 2., 3., 4., 5., 6., 7.])
>>> weights
array([1.04719755, 1.04719755, 1.04719755, 1.04719755, 1.04719755,
       1.04719755, 1.04719755, 1.04719755])

wcs(fig, coordsys='icrs', projection='AIT', rotation=None)[source]¶

Get a wcs that can be given to matplotlib to plot the MOC.

Parameters:

figfigure: The matplotlib figure used for plotting the MOC.
coordsysstr, optional: Coordinate system. Default to “icrs”. Must be in [“icrs”, “galactic”].
projectionstr, optional: World base -> Image base projection type. See http://docs.astropy.org/en/stable/wcs/#supported-projections for the projections currently supported in astropy. Default to Aitoff.
rotationAngle, optional: The angle of rotation. Default to no rotation.

Returns:

wcsWCS: The WCS that can be passed to mocpy.MOC.fill/border.

Examples

>>> from mocpy import MOC
>>> import matplotlib.pyplot as plt
>>> moc = MOC.from_str("2/2-25 28 29 4/0 6/")
>>> fig = plt.figure()
>>> moc.wcs(fig)
WCS Keywords

Number of WCS axes: 2
CTYPE : 'RA---AIT'  'DEC--AIT'
CRVAL : 92.29966711743452  54.33295312309193
CRPIX : 320.5  240.5
PC1_1 PC1_2  : 1.0  -0.0
PC2_1 PC2_2  : 0.0  1.0
CDELT : -0.27794934051515896  0.27794934051515896
NAXIS : 0  0

write(path, format='fits', overwrite=False, optional_kw_dict=None, v1_compatible=False, pre_v2=None)¶

Write the MOC to a file.

Format can be ‘fits’ or ‘json’, though only the fits format is officially supported by the IVOA.

Parameters:

pathstr: The path to the file to save the MOC in.
formatstr, optional: The format in which the MOC will be serialized before being saved. Possible formats are “fits” or “json”. By default, format is set to “fits”.
overwritebool, optional: If the file already exists and you want to overwrite it, then set the overwrite keyword. Default to False.
optional_kw_dictoptional: Optional keywords arguments added to the FITS header. Only used if format equals to ‘fits’.
v1_compatiblebool, optional: If True, write a v2 MOC that can be read by v1 parsers (using NUNIQ ordering for spatial MOCs). Default to False (MOC 2.0 standard range-encoded).
pre_v2bool, optional: Deprecated since v0.21.0. Use v1_compatible instead.

Navigation

mocpy.MOC¶