The MOC Class

pymoc

The pymoc module imports the MOC class from the pymoc.moc module, allowing it to be imported as follows:

from pymoc import MOC

pymoc.moc

class pymoc.moc.MOC(order=None, cells=None, filename=None, filetype=None, name=None, mocid=None, origin=None, moctype=None)

Class representing Multi-Order Coverage maps.

Apart from the properties listed below, the MOC also includes the following attributes:

  • id

  • name

  • origin

__init__(order=None, cells=None, filename=None, filetype=None, name=None, mocid=None, origin=None, moctype=None)

Construct new MOC object.

By default the new MOC will be empty, but if an order and a collection of cells are specified, then these will be added to the new MOC. If a filename is specified then data from the given file will be read into the new object, and if it is a FITS file, the metadata will also be read, although this can be overridden by values given explicitly as constructor arguments.

Additional metadata can be added to the MOC using the name, mocid, origin and moctype arguments, or added at a later time using the corresponding attributes and properties. The metadata values can be read from and written to FITS files, but are not included when a MOC is written to the other formats (JSON or ASCII).

>>> from pymoc import MOC
>>> m = MOC()
>>> m.cells
0
>>> m = MOC(10, (1234, 4321))
>>> m.cells
2
>>> m = MOC(name='example', moctype='IMAGE')
>>> m.name
'example'
>>> m.type
'IMAGE'
__iter__()

Iterator for MOC objects.

This yields an (order, cell collection) pair for each order at which there are cells. The results will be returned in ascending order of the order number.

>>> m = MOC(0, (1, 2))
>>> m.add(1, (0,))
>>> for (order, cells) in m:
...     print(str(order) + ' ' + str(sorted(cells)))
0 [1, 2]
1 [0]
__len__()

Length operator for MOC objects.

Returns the number of orders at which the MOC has cells.

>>> m = MOC(0, (1, 2))
>>> len(m)
1
__getitem__(order)

Subscripting operator for MOC objects.

This retrieves a collection of cells at the given order of the MOC.

>>> m = MOC(5, (6, 7))
>>> sorted(m[5])
[6, 7]
__eq__(other)

Equality test operator.

>>> MOC(1, (4, 5, 6, 7)) == MOC(0, (1,))
True
>>> MOC(2, (0, 1)) == MOC(0, (0,))
False
>>> MOC(1, (5, 6)) != MOC(1, (1, 2))
True
>>> MOC(2, (8, 9, 10, 11)) != MOC(1, (2,))
False
__iadd__(other)

In-place addition operator.

Updates the MOC to represent the union of itself and the other MOC.

>>> p = MOC(4, (5, 6))
>>> p += MOC(4, (7, 8))
>>> repr(p)
'<MOC: [(4, [5, 6, 7, 8])]>'
__add__(other)

Addition operator.

Returns a MOC which is the union of two MOCs.

>>> MOC(4, (5, 6)) + MOC(4, (7, 8))
<MOC: [(4, [5, 6, 7, 8])]>
__sub__(other)

Subtraction operator.

Returns a MOC which is the copy of the first MOC with the intersection with the second MOC removed.

>>> MOC(0, (0,)) - MOC(2, (15,))
<MOC: [(1, [0, 1, 2]), (2, [12, 13, 14])]>
__isub__(other)

In-place subtraction operator.

Removes areas which overlap with the given MOC.

__repr__()

Generate printable representation.

Since the constructor only accepts cells at one order and we may be generating a representation for a MOC with cells at multiple orders we can’t try to give an expression which would construct the object. Instead show a description in angle brackets.

property order

The highest order at which the MOC has cells.

>>> m = MOC(4, (3, 2, 1))
>>> m.order
4
property type

The type of MOC (IMAGE or CATALOG).

>>> m = MOC(moctype='IMAGE')
>>> m.type
'IMAGE'
>>> m.type = 'CATALOG'
>>> m.type
'CATALOG'
property normalized

Whether the MOC has been normalized or not.

>>> m = MOC()
>>> m.add(1, (0,))
>>> m.add(2, (1,))
>>> m.normalized
False
>>> m.normalize()
>>> m.normalized
True
property area

The area enclosed by the MOC, in steradians.

>>> m = MOC(0, (0, 1, 2))
>>> round(m.area, 2)
3.14
property area_sq_deg

The area enclosed by the MOC, in square degrees.

>>> from math import sqrt
>>> m = MOC(0, (0,))
>>> round(sqrt(m.area_sq_deg), 2)
58.63
property cells

The number of cells in the MOC.

This gives the total number of cells at all orders, with cells from every order counted equally.

>>> m = MOC(0, (1, 2))
>>> m.cells
2
add(order, cells, no_validation=False)

Add cells at a given order to the MOC.

The cells are inserted into the MOC at the specified order. This leaves the MOC in an un-normalized state. The cells are given as a collection of integers (or types which can be converted to integers).

>>> m = MOC()
>>> m.add(4, (20, 21))
>>> m.cells
2
>>> m.add(5, (88, 89))
>>> m.cells
4

The no_validation option can be given to skip validation of the cell numbers. They must already be integers in the correct range.

remove(order, cells)

Remove cells at a given order from the MOC.

clear()

Clears all cells from a MOC.

>>> m = MOC(4, (5, 6))
>>> m.clear()
>>> m.cells
0
copy()

Return a copy of a MOC.

>>> p = MOC(4, (5, 6))
>>> q = p.copy()
>>> repr(q)
'<MOC: [(4, [5, 6])]>'
contains(order, cell, include_smaller=False)

Test whether the MOC contains the given cell.

If the include_smaller argument is true then the MOC is considered to include a cell if it includes part of that cell (at a higher order).

>>> m = MOC(1, (5,))
>>> m.contains(0, 0)
False
>>> m.contains(0, 1, True)
True
>>> m.contains(0, 1, False)
False
>>> m.contains(1, 4)
False
>>> m.contains(1, 5)
True
>>> m.contains(2, 19)
False
>>> m.contains(2, 21)
True
intersection(other)

Returns a MOC representing the intersection with another MOC.

>>> p = MOC(2, (3, 4, 5))
>>> q = MOC(2, (4, 5, 6))
>>> p.intersection(q)
<MOC: [(2, [4, 5])]>
normalize(max_order=29)

Ensure that the MOC is “well-formed”.

This structures the MOC as is required for the FITS and JSON representation. This method is invoked automatically when writing to these formats.

The number of cells in the MOC will be minimized, so that no area of the sky is covered multiple times by cells at different orders, and if all four neighboring cells are present at an order (other than order 0), they are merged into their parent cell at the next lower order.

>>> m = MOC(1, (0, 1, 2, 3))
>>> m.cells
4
>>> m.normalize()
>>> m.cells
1
flattened(order=None, include_smaller=True)

Return a flattened pixel collection at a single order.

read(filename, filetype=None, include_meta=False, **kwargs)

Read data from the given file into the MOC object.

The cell lists read from the file are added to the current object. Therefore if the object already contains some cells, it will be updated to represent the union of the current coverge and that from the file.

The file type can be specified as “fits”, “json” or “ascii”, with “text” allowed as an alias for “ascii”. If the type is not specified, then an attempt will be made to guess from the file name, or the contents of the file.

Note that writing to FITS and JSON will cause the MOC to be normalized automatically.

Any additional keyword arguments (kwargs) are passed on to the corresponding pymoc.io read functions (read_moc_fits, read_moc_json or read_moc_ascii).

write(filename, filetype=None, **kwargs)

Write the coverage data in the MOC object to a file.

The filetype can be given or left to be inferred as for the read method.

Any additional keyword arguments (kwargs) are passed on to the corresponding pymoc.io write functions (write_moc_fits, write_moc_json or write_moc_ascii). This can be used, for example, to set overwrite=True (or clobber=True prior to Astropy version 2.0) when writing FITS files.