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:
- frequencies
Quantity
Astropy quantities of physical type
frequency
.- lon
astropy.units.Quantity
The longitudes of the sky coordinates observed with a specific frequency.
- lat
astropy.units.Quantity
The latitudes of the sky coordinates observed with a specific frequency.
- frequencies
- 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 thatcontracted
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_moc
mocpy.MOC
,mocpy.TimeMOC
,mocpy.FrequencyMOC
,mocpy.STMOC
The MOC used that will be subtracted to self.
- mocs
mocpy.MOC
,mocpy.TimeMOC
,mocpy.FrequencyMOC
,mocpy.STMOC
Other additional MOCs to perform the difference with.
- another_moc
- 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 thatextended
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:
- frequencies
astropy.units.Quantity
An astropy Quantity of physical type ‘frequency’
- lon
astropy.units.Quantity
The longitudes of the sky coordinates corresponding to the frequencies.
- lat
astropy.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.
- frequencies
- Returns:
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_min
astropy.units.Quantity
An astropy Quantity of physical type ‘frequency’
- frequencies_max
astropy.units.Quantity
An astropy Quantity of physical type ‘frequency’
- lon
astropy.units.Quantity
The longitudes of the sky coordinates observed at a specific time.
- lat
astropy.units.Quantity
The latitudes of the sky coordinates observed at a specific time.
- max_order_frequencyint
Frequency order.
- max_order_spaceint
Spatial order.
- frequencies_min
- 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:
- Returns:
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_moc
mocpy.MOC
,mocpy.TimeMOC
,mocpy.FrequencyMOC
,mocpy.STMOC
The MOC to do the intersection with.
- mocs
mocpy.MOC
,mocpy.TimeMOC
,mocpy.FrequencyMOC
,mocpy.STMOC
Other additional MOCs to perform the intersection with.
- another_moc
- 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:
- 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 andMAX_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:
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:
- smoc
MOC
The spatial coverage.
- smoc
- 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:
- result
astropy.io.fits.HDUList
or JSON dictionary The result of the serialization.
- result
- 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_moc
mocpy.MOC
,mocpy.TimeMOC
,mocpy.FrequencyMOC
,mocpy.STMOC
The MOC used that will be subtracted to self.
- mocs
mocpy.MOC
,mocpy.TimeMOC
,mocpy.FrequencyMOC
,mocpy.STMOC
Other additional MOCs to perform the difference with.
- another_moc
- 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_moc
mocpy.MOC
,mocpy.TimeMOC
,mocpy.FrequencyMOC
,mocpy.STMOC
The MOC to do the union with.
- mocs
mocpy.MOC
,mocpy.TimeMOC
,mocpy.FrequencyMOC
,mocpy.STMOC
Other additional MOCs to perform the union with.
- another_moc
- 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’.