The MOC Class


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

from pymoc import 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
>>> m = MOC(10, (1234, 4321))
>>> m.cells
>>> m = MOC(name='example', moctype='IMAGE')
>>> m.type

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]

Length operator for MOC objects.

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

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

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]

Equality test operator.

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

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])]>'

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])]>

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])]>

In-place subtraction operator.

Removes areas which overlap with the given MOC.


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.


The highest order at which the MOC has cells.

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

The type of MOC (IMAGE or CATALOG).

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

Whether the MOC has been normalized or not.

>>> m = MOC()
>>> m.add(1, (0,))
>>> m.add(2, (1,))
>>> m.normalized
>>> m.normalize()
>>> m.normalized

The area enclosed by the MOC, in steradians.

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

The area enclosed by the MOC, in square degrees.

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

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
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
>>> m.add(5, (88, 89))
>>> m.cells

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.


Clears all cells from a MOC.

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

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)
>>> m.contains(0, 1, True)
>>> m.contains(0, 1, False)
>>> m.contains(1, 4)
>>> m.contains(1, 5)
>>> m.contains(2, 19)
>>> m.contains(2, 21)

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])]>

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
>>> m.normalize()
>>> m.cells
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 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 write functions (write_moc_fits, write_moc_json or write_moc_ascii). This can be used, for example, to set clobber=True when writing FITS files.