mocpy.STMOC¶

class mocpy.STMOC(store_index)[source]¶

Time-Spatial Coverage class.

Is a Time-Spatial Coverage (ST-MOC).

Args:: store_index: index of the ST-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(times, lon, lat, inside=True)[source]¶

Return a boolean mask array of the (times, positions) lying inside (or outside) the Space-Time coverage.

Parameters:

timesastropy.time.Time: The times of each sky coordinates.
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.
insidebool, optional: True by default. The returned mask array has true values for (time, position) lying inside the Space-Time coverage.

Returns:

arrayndarray: A mask boolean array

Raises:

ValueErrorIf times, lon and lat do not have the same length.

Examples

>>> from mocpy import STMOC, MOC
>>> import astropy.units as u
>>> from astropy.time import Time
>>> moc = MOC.from_cone(0*u.deg, 0*u.deg, radius=10*u.deg, max_depth=10)
>>> stmoc = STMOC.from_spatial_coverages(Time("2000-01-01"), Time("2020-01-01"),
...                                      moc, time_depth=40)
>>> # one inside, one outside
>>> stmoc.contains(Time(["2005-01-01", "1990-01-01"]),
...                [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:

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_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(times_start, times_end, spatial_coverages, time_depth=61)[source]¶

Create a 2D Coverage from a set of time ranges and spatial coverages associated to them.

Parameters:

times_startastropy.time.Time: The starting times of each observations.
times_endastropy.time.Time: The ending times of each observations.
spatial_coverageslist: List of mocpy.MOC spatial coverage objects.
time_depthint, optional: Time depth. By default, the time resolution chosen is 1µs.

Returns:

resultSTMOC: The resulting Spatial-Time Coverage map.

Examples

>>> from mocpy import STMOC, MOC
>>> 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")
>>> moc = MOC.from_cone(0*u.deg, 0*u.deg, radius=10*u.arcmin, max_depth=15)
>>> stmoc = STMOC.from_spatial_coverages(time_min, time_max, [moc])

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:

STMOC: The ST-MOC build from the given string.

Examples

>>> from mocpy import STMOC
>>> stmoc = STMOC.from_string("t20/500-600 s29/ 3/0-1")
>>> stmoc
t14/8
16/36
17/63 74
18/125
20/600
s3/0-1
29/
t20/ s29/

classmethod from_time_ranges_positions(times_start, times_end, lon, lat, time_depth=61, spatial_depth=29)[source]¶

Create a 2D Coverage from a set of times and positions associated to each time.

Its first dimension refers to astropy.time.Time times.
Its second dimension refers to lon, lat astropy.units.Quantity positions.

Parameters:

times_startastropy.time.Time: The starting times of each observations.
times_endastropy.time.Time: The ending times of each observations.
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.
time_depthint, optional: Time depth. By default, the time resolution chosen is 1µs.
spatial_depthint, optional: Spatial depth. By default, the space resolution chosen is 393.2μas.

Returns:

resultSTMOC: The resulting Spatial-Time Coverage map.

Examples

>>> from mocpy import STMOC
>>> from astropy.time import Time
>>> from astropy import units as u
>>> time_start = Time(["2020-01-01", "2020-01-02"])
>>> time_end = Time(["2020-01-10", "2020-01-12"])
>>> lon = [0, 10] * u.deg
>>> lat = [0, 10] * u.deg
>>> stmoc = STMOC.from_time_ranges_positions(time_start, time_end, lon, lat,
...                                          time_depth=20, spatial_depth=8)
>>> stmoc
t20/96608
s8/311296 312689
t20/96609
s8/312689
t20/ s8/

classmethod from_times_positions(times, time_depth, lon, lat, spatial_depth)[source]¶

Create a 2D Coverage from a set of times and positions associated to each time.

Its first dimension refers to astropy.time.Time times.
Its second dimension refers to lon, lat astropy.units.Quantity positions.

Parameters:

timesastropy.time.Time: The times of each sky coordinates.
time_depthint: Time depth.
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.
spatial_depthint: Spatial depth.

Returns:

resultSTMOC: The resulting Spatial-Time Coverage map.

Examples

>>> from mocpy import STMOC
>>> from astropy.time import Time
>>> from astropy import units as u
>>> times = Time(["2020-01-01", "2020-01-02"])
>>> lon = [0, 10] * u.deg
>>> lat = [0, 10] * u.deg
>>> stmoc = STMOC.from_times_positions(times, 20, lon, lat, 12)
>>> stmoc
t20/96608
s12/79691776 80048632
t20/ s12/

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-Time coverage is empty.

Returns:

bool: True if the ST-MOC is empty, False otherwise.

Examples

>>> from mocpy import STMOC
>>> STMOC.new_empty(42, 12).is_empty()
True

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

Load the Space-Time 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:

STMOC

property max_depth¶

Return max depth in time and space of the MOC (alias of max_order).

Returns:

Tuple: The maximum order (temporal, spatial) of the ST-MOC.

Examples

>>> from mocpy import STMOC, MOC
>>> from astropy.time import Time
>>> import astropy.units as u
>>> moc = MOC.from_cone(0 * u.deg, 0* u.deg, radius=10 * u.arcmin, max_depth=10)
>>> stmoc = STMOC.from_spatial_coverages(Time("2000-01-01"), Time("2020-01-01"), [moc])
>>> stmoc.max_depth
(61, 10)

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

property max_order¶

Return max order in time and space of the Space-Time MOC.

Returns:

Tuple: The maximum order (temporal, spatial) of the ST-MOC.

Examples

>>> from mocpy import STMOC, MOC
>>> from astropy.time import Time
>>> import astropy.units as u
>>> moc = MOC.from_cone(0 * u.deg, 0* u.deg, radius=10 * u.arcmin, max_depth=10)
>>> stmoc = STMOC.from_spatial_coverages(Time("2000-01-01"), Time("2020-01-01"), [moc])
>>> stmoc.max_order
(61, 10)

property max_time¶

Return the maximum time of the ST-MOC.

Returns:

astropy.time.Time: The maximum time of the ST-MOC.

Examples

>>> from mocpy import STMOC, MOC
>>> from astropy.time import Time
>>> import astropy.units as u
>>> moc = MOC.from_cone(0 * u.deg, 0* u.deg, radius=10 * u.arcmin, max_depth=10)
>>> stmoc = STMOC.from_spatial_coverages(Time("2000-01-01"), Time("2020-01-01"), [moc])
>>> stmoc.max_time.iso
'2020-01-01 00:01:30.222'

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

property min_time¶

Return the minimum time of the ST-MOC.

Returns:

astropy.time.Time: The minimum time of the ST-MOC.

Examples

>>> from mocpy import STMOC, MOC
>>> from astropy.time import Time
>>> import astropy.units as u
>>> moc = MOC.from_cone(0 * u.deg, 0* u.deg, radius=10 * u.arcmin, max_depth=10)
>>> stmoc = STMOC.from_spatial_coverages(Time("2000-01-01"), Time("2020-01-01"), [moc])
>>> stmoc.min_time.iso
'2000-01-01 00:01:15.436'

classmethod n_cells(depth, dimension)[source]¶

Get the number of cells for a given depth.

Parameters:

depthint: The depth. It is comprised between 0 and MAX_ORDER if dimension=’space’ and between 0 and MAX_ORDER if dimension=’time’.
dimensionstr: Can be either ‘time’ or ‘space’.

Returns:

int: The number of cells at the given order

Examples

>>> from mocpy import STMOC
>>> STMOC.n_cells(0, dimension='space')
12

classmethod new_empty(max_depth_time, max_depth_space)[source]¶

Create a new empty STMOC.

Parameters:

max_depth_timeint: The time resolution of the STMOC. Should be comprised between 0 and 61.
max_depth_spaceint: The space resolution of the STMOC. Should be comprised between 0 and 29.

Returns:

STMOC

Examples

>>> from mocpy import STMOC
>>> STMOC.new_empty(42, 12)
t42/ s12/

query_by_space(smoc)[source]¶

Query the ST-MOC by space coverage.

This will perform the union of all the time ranges whose associated spatial coverages lie in moc.

Parameters:

smocMOC: The spatial coverage.

Returns:

TimeMOC: The time ranges observing in the spatial_coverage

Examples

>>> from mocpy import STMOC, MOC, TimeMOC
>>> from astropy.time import Time
>>> time_min = Time("2026-01-01")
>>> time_max = Time("2026-01-10")
>>> moc = MOC.from_string("3/0-1")
>>> stmoc = STMOC.from_spatial_coverages(time_min, time_max, [moc])
>>> stmoc.query_by_space(moc).max_time.iso
'2026-01-10 00:01:33.171'

query_by_time(tmoc)[source]¶

Query the ST-MOC by time T-MOC.

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

Parameters:

tmoc~mocpy.tmoc.TimeMOC``: Time ranges. Must be a Nx2 shaped astropy time array.

Returns:

MOC: The spatial coverage being observed within the input time ranges

Examples

>>> from mocpy import STMOC, MOC, TimeMOC as TMOC
>>> from astropy.time import Time
>>> time_min = Time("2026-01-01")
>>> time_max = Time("2026-01-10")
>>> moc = MOC.from_string("4/4 5/15 20")
>>> tmoc = TMOC.from_time_ranges(time_min, time_max)
>>> stmoc = STMOC.from_spatial_coverages(time_min, time_max, [moc])
>>> stmoc.query_by_time(tmoc)
4/4
5/15 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, 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.

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(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_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, 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.STMOC¶