mocpy.SFMOC

class mocpy.SFMOC(store_index)[source]

Spatial-Frequency Coverage class.

Is a Spatial-Frequency Coverage (SF-MOC).

Args:

store_index: index of the SF-MOC in the rust-side storage

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.

complement()

Return the complement of the MOC instance.

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

The resulting MOC.

contains(frequencies, lon, lat)[source]

Test if the Frequency-Space combinations fall within the SFMOC.

Parameters:
frequenciesQuantity

Astropy quantities of physical type frequency.

lonastropy.units.Quantity

The longitudes of the sky coordinates observed with a specific frequency.

latastropy.units.Quantity

The latitudes of the sky coordinates observed with a specific frequency.

Returns:
array

A boolean array with the same length than the given Frequency-Position couples. True if the Frequency-Position is within the SFMOC, False otherwise.

Examples

>>> from mocpy import SFMOC, MOC
>>> import astropy.units as u
>>> moc = MOC.from_cone(0*u.deg, 0*u.deg, radius=10*u.deg, max_depth=10)
>>> sfmoc = SFMOC.from_spatial_coverages(0.01*u.Hz, 100*u.Hz,
...                                      moc, max_order_frequency=40)
>>> # one inside, one outside
>>> sfmoc.contains([10, 10000]*u.Hz, [0.1, 20]*u.deg, [0.1, 20]*u.deg)
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)

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

The maximum depth (i.e. the depth of the smallest 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:
mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC, mocpy.STMOC

The degraded MOC.

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/
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

flatten()

Return the list of indices of all cells in the MOC at the MOC depth.

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:
pathstr

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_frequencies_and_positions(frequencies, lon, lat, *, max_order_frequency, max_order_space)[source]

Create a Space-Frequency Coverage from a set of frequencies and positions.

Parameters:
frequenciesastropy.units.Quantity

An astropy Quantity of physical type ‘frequency’

lonastropy.units.Quantity

The longitudes of the sky coordinates corresponding to the frequencies.

latastropy.units.Quantity

The latitudes of the sky coordinates corresponding to the frequencies.

max_order_frequencyint

Frequency order. Should be comprised between 0 and 59.

max_order_spaceint

Spatial order.

Returns:
SFMOC

Examples

>>> import astropy.units as u
>>> from mocpy import SFMOC
>>> frequencies = [1, 2, 3] * u.Hz
>>> lon = [0, 1, 2] * u.deg
>>> lat = [0, 1, 2] * u.deg
>>> sfmoc = SFMOC.from_frequencies_and_positions(frequencies, lon, lat,
...                                              max_order_frequency=20,
...                                              max_order_space=12)
>>> sfmoc
f20/770048
s12/79691776
f20/778240
s12/79697029
f20/782336
s12/79712788
f20/ s12/
classmethod from_frequency_ranges_and_positions(frequencies_min, frequencies_max, lon, lat, *, max_order_frequency, max_order_space)[source]

Create a SF coverage from a range of frequencies for each position.

Parameters:
frequencies_minastropy.units.Quantity

An astropy Quantity of physical type ‘frequency’

frequencies_maxastropy.units.Quantity

An astropy Quantity of physical type ‘frequency’

lonastropy.units.Quantity

The longitudes of the sky coordinates observed at a specific time.

latastropy.units.Quantity

The latitudes of the sky coordinates observed at a specific time.

max_order_frequencyint

Frequency order.

max_order_spaceint

Spatial order.

Returns:
SFMOC

The resulting Space-Frequency Coverage map.

Examples

>>> import astropy.units as u
>>> from mocpy import SFMOC
>>> frequencies_min = [0.01, 0.02, 0.03] * u.Hz
>>> frequencies_max = [0.1, 0.2, 0.3] * u.Hz
>>> lon = [0, 1, 2] * u.deg
>>> lat = [0, 1, 2] * u.deg
>>> sfmoc = SFMOC.from_frequency_ranges_and_positions(frequencies_min,
...                                                   frequencies_max, lon, lat,
...                                                   max_order_frequency=10,
...                                                   max_order_space=12)
>>> sfmoc
f8/175
9/349 352
10/
s12/79691776
f9/353-354
10/710
s12/79691776 79697029
f7/89
8/180
10/711 724
s12/79691776 79697029 79712788
f8/182
9/363
10/725 732
s12/79697029 79712788
f9/367-368
10/733
s12/79712788
f10/ s12/
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_spatial_coverages(frequencies_min, frequencies_max, spatial_coverages, *, max_order_frequency)[source]

Create a ST coverage from frequency ranges associated to spatial coverages.

Parameters:
frequencies_minQuantity

An astropy Quantity of physical type ‘frequency’

frequencies_maxQuantity

An astropy Quantity of physical type ‘frequency’

spatial_coverageslist[MOC]

List of spatial coverages.

max_order_frequencyint

Frequency order.

Returns:
SFMOC

Examples

>>> import astropy.units as u
>>> from mocpy import MOC, SFMOC
>>> sfmoc = SFMOC.from_spatial_coverages(
...             frequencies_min=[0.1]*u.Hz, frequencies_max=[10]*u.Hz,
...             spatial_coverages=[MOC.from_string("5/14-21")],
...             max_order_frequency=10)
>>> sfmoc
f5/23
7/91 96
8/181
9/388
10/
s4/4
5/14-15 20-21
f10/ s5/
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.

Parameters:
formatstr, optional

The format in which the MOC is serialized. Possible formats are “ascii” or “json”. By default, format is set to “ascii”.

Returns:
SFMOC

The ST-MOC build from the given string.

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
is_empty()[source]

Check whether the Space-Frequency coverage is empty.

Returns:
bool

Examples

>>> from mocpy import SFMOC
>>> sfmoc = SFMOC.new_empty(20, 12)
>>> sfmoc.is_empty()
True
classmethod load(path, format='fits')[source]

Load the Space-Frequency 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:
SFMOC
property max_frequency

Return SFMOC max frequency.

property max_index

Return the largest index (at the deepest absolute resolution) the MOC contains.

property max_order

Maximum order of the SF-MOC.

Returns:
(int, int)

(max_order_frequency, max_order_space)

property min_frequency

Return SFMOC min frequency.

property min_index

Return the smallest index (at the deepest absolute resolution) the MOC contains.

classmethod n_cells(order, *, dimension)[source]

Get the number of cells for a given order.

Parameters:
orderint

The order. It is comprised between 0 and MAX_ORDER if dimension=’space’ and between 0 and MAX_ORDER if dimension=’frequency’.

dimensionstr

Can be either ‘frequency’ or ‘space’.

Returns:
int

The number of cells at the given order

Examples

>>> from mocpy import SFMOC
>>> SFMOC.n_cells(0, dimension='space')
12
classmethod new_empty(max_order_frequency, max_order_space)[source]

Create a new empty SFMOC.

Parameters:
max_order_frequencyint

The frequency resolution of the SFMOC. Should be comprised between 0 and 59.

max_order_spaceint

The space resolution of the SFMOC. Should be comprised between 0 and 29.

Returns:
SFMOC

Examples

>>> from mocpy import SFMOC
>>> SFMOC.new_empty(20, 12)
f20/ s12/
query_by_frequency(fmoc)[source]

Query the SF-MOC by frequency F-MOC.

This will perform the union of all the spatial coverages lying in a set of time ranges.

Parameters:
fmoc~mocpy.FrequencyMOC``

Frequency MOC.

Returns:
MOC

The spatial coverage being observed within the input frequency ranges

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
query_by_space(smoc)[source]

Query the SF-MOC by space coverage.

This will perform the union of all the frequency ranges which associated spatial coverages fall within the given spatial MOC.

Parameters:
smocMOC

The spatial coverage.

Returns:
FrequencyMOC

The Frequency coverage corresponding to the Spatial MOC

Examples

>>> from mocpy import MOC, SFMOC, FrequencyMOC as FMOC
>>> sfmoc = SFMOC.from_string('''f10/0-20
... s12/0-100
... f10/21-40
... s12/101-200
... ''')
>>> moc = MOC.from_string("12/0-100")
>>> fmoc = FMOC.from_sfmoc_space_fold(sfmoc, moc)
>>> fmoc
6/0
8/4
10/20
refine_to_order(new_order)

Refine the MOC instance to a more precise order.

This is an in-place operation.

Parameters:
new_orderint

New maximum order for the MOC.

Returns:
mocpy.MOC, mocpy.TimeMOC, mocpy.FrequencyMOC

Returns itself, after in-place modification.

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, pre_v2=False, fold=0, fits_keywords=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.

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.

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

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’.

Returns:
resultastropy.io.fits.HDUList or JSON dictionary

The result of the serialization.

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
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(union.min_time.jyear, union.max_time.jyear)
[1998.99847987] [2010.00183614]
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_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)

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

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’.