mocpy.TimeMOC¶

class mocpy.TimeMOC(store_index)[source]¶

Multi-order time coverage class. Experimental.

Is a Time Coverage (T-MOC).

Args:: store_index: index of the S-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.

property consistency¶

Get a percentage of fill between the min and max time the moc is defined.

A value near 0 shows a sparse temporal moc (i.e. the moc does not cover a lot of time and covers very distant times. A value near 1 means that the moc covers a lot of time without big pauses.

Returns:

resultfloat: fill percentage (between 0 and 1.)

contains(times, keep_inside=True)[source]¶

Get a mask array (e.g. a numpy boolean array) of times being inside (or outside) the TMOC instance.

Parameters:

timesastropy.time.Time: astropy times to check whether they are contained in the TMOC or not.
keep_insidebool, optional: True by default. If so the filtered table contains only observations that are located the MOC. If keep_inside is False, the filtered table contains all observations lying outside the MOC.

Returns:

arraydarray: A mask boolean array

contains_with_timeresolution(times, keep_inside=True, delta_t=<TimeDelta object: scale='tdb' format='sec' value=1800.0>)[source]¶

Get a mask array (e.g. a numpy boolean array) of times being inside (or outside) the TMOC instance.

Parameters:

timesastropy.time.Time: astropy times to check whether they are contained in the TMOC or not.
keep_insidebool, optional: True by default. If so the filtered table contains only observations that are located the MOC. If keep_inside is False, the filtered table contains all observations lying outside the MOC.
delta_tastropy.time.TimeDelta, optional: the duration of one observation. It is set to 30 min by default. This data is used to compute the more efficient TimeMOC order to represent the observations (Best order = the less precise order which is able to discriminate two observations separated by delta_t).

Returns:

arraydarray: A mask boolean array

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

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

The maximum depth (i.e. the depth of the smallest Time 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:

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

difference_with_timeresolution(another_moc, delta_t=<TimeDelta object: scale='tdb' format='sec' value=1800.0>)[source]¶

Difference between self and moc.

delta_t gives the possibility to the user to set a time resolution for performing the tmoc diff.

Parameters:

another_mocAbstractMOC: the MOC/TimeMoc to substract from self
delta_tTimeDelta, optional: the duration of one observation. It is set to 30 min by default. This data is used to compute the more efficient TimeMoc order to represent the observations. (Best order = the less precise order which is able to discriminate two observations separated by delta_t)

Returns:

resultMOC or TimeMoc: MOC object whose interval set corresponds to : self - moc

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_depth61_ranges(max_depth, ranges)[source]¶

Create a TimeMOC from a set of Time ranges at order 61 (i.e. ranges of microseconds since JD=0).

Parameters:

max_depthint, The resolution of the TimeMOC
ranges: `~numpy.ndarray`: a N x 2 numpy array representing the set of depth 61 ranges.

Returns:

mocTimeMOC: The MOC

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_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_stmoc_space_fold(smoc, stmoc)[source]¶

Build a new T-MOC from the fold operation of the given ST-MOC by the given S-MOC.

Parameters:

smocMoc
stmocSTMoc

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 Time MOC from the given string.

Format can be ‘ascii’ or ‘json’, though the json format is not officially supported by the IVOA.

WARNING: the serialization must be strict, i.e. must not contain overlapping elements

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

classmethod from_time_ranges(min_times, max_times, delta_t=<TimeDelta object: scale='tdb' format='sec' value=1800.0>)[source]¶

Create a TimeMOC from a range defined by two astropy.time.Time.

Parameters:

min_timesastropy.time.Time: astropy times defining the left part of the intervals
max_timesastropy.time.Time: astropy times defining the right part of the intervals
delta_tastropy.time.TimeDelta, optional: the duration of one observation. It is set to 30 min by default. This data is used to compute the more efficient TimeMOC order to represent the observations (Best order = the less precise order which is able to discriminate two observations separated by delta_t).

Returns:

time_mocTimeMOC

classmethod from_time_ranges_approx(min_times, max_times, delta_t=<TimeDelta object: scale='tdb' format='sec' value=1800.0>)[source]¶

Create a TimeMOC from a range defined by two astropy.time.Time.

Uses the following approximation: simple take the JD time and multiply by the number of microseconds in a day.

Parameters:

min_timesastropy.time.Time: astropy times defining the left part of the intervals
max_timesastropy.time.Time: astropy times defining the right part of the intervals
delta_tastropy.time.TimeDelta, optional: the duration of one observation. It is set to 30 min by default. This data is used to compute the more efficient TimeMOC order to represent the observations (Best order = the less precise order which is able to discriminate two observations separated by delta_t).

Returns:

time_mocTimeMOC

classmethod from_times(times, delta_t=<TimeDelta object: scale='tdb' format='sec' value=1800.0>)[source]¶

Create a TimeMOC from a astropy.time.Time.

Parameters:

timesastropy.time.Time: Astropy observation times
delta_tastropy.time.TimeDelta, optional: The duration of one observation. It is set to 30 min by default. This data is used to compute the more efficient TimeMOC order to represent the observations (Best order = the less precise order which is able to discriminate two observations separated by delta_t).

Returns:

time_mocTimeMOC

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

intersection_with_timeresolution(another_moc, delta_t=<TimeDelta object: scale='tdb' format='sec' value=1800.0>)[source]¶

Intersection between self and moc.

delta_t gives the possibility to the user to set a time resolution for performing the tmoc intersection

Parameters:

another_mocAbstractMOC: the MOC/TimeMOC used for performing the intersection with self
delta_tTimeDelta, optional: the duration of one observation. It is set to 30 min by default. This data is used to compute the more efficient TimeMoc order to represent the observations. (Best order = the less precise order which is able to discriminate two observations separated by delta_t)

Returns:

resultMOC or TimeMOC: MOC object whose interval set corresponds to : self & moc

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

Load the 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”.

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

property max_order¶: Depth/order of the T-MOC.

property max_time¶

Get the Time time of the tmoc last observation.

Returns:

max_timeTime: time of the last observation

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

property min_time¶

Get the Time time of the tmoc first observation.

Returns:

min_timeastropy.time.Time: time of the first observation

classmethod n_cells(depth)[source]¶

Get the number of cells for a given depth.

Parameters:

depthint: The depth. It is comprised between 0 and MAX_ORDER

Returns:

int: The number of cells at the given order

Examples

>>> from mocpy import TimeMOC
>>> TimeMOC.n_cells(0)
2

classmethod new_empty(max_depth)[source]¶

Create a new empty TimeMOC of given depth.

Parameters:

max_depthint, The resolution of the TimeMOC

Returns:

mocTimeMOC: The MOC

static order_to_time_resolution(order)[source]¶

Convert an TimeMoc order to its equivalent time.

Parameters:

orderint: order to convert

Returns:

delta_tTimeDelta: time equivalent to order

plot(title='TimeMoc', view=(None, None), figsize=(9.5, 5), **kwargs)[source]¶

Plot the TimeMoc in a time window.

This method uses interactive matplotlib. The user can move its mouse through the plot to see the time (at the mouse position).

Parameters:

titlestr, optional: The title of the plot. Set to ‘TimeMoc’ by default.
view(Time, Time), optional: Define the view window in which the observations are plotted. Set to (None, None) by default (i.e. all the observation time window is rendered).

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

static time_resolution_to_order(delta_time)[source]¶

Convert a time resolution to a TimeMoc order.

Parameters:

delta_timeTimeDelta: time to convert

Returns:

orderint: The less precise order which is able to discriminate two observations separated by delta_time.

property to_depth61_ranges¶: Return the list of ranges this TimeMOC contains, in microsec since JD=0.

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

to_time_ranges()[source]¶: Return the time ranges this TimeMOC contains.

property total_duration¶

Get the total duration covered by the temporal moc.

Returns:

durationTimeDelta: total duration of all the observation times of the tmoc total duration of all the observation times of the tmoc

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]

union_with_timeresolution(another_moc, delta_t=<TimeDelta object: scale='tdb' format='sec' value=1800.0>)[source]¶

Union between self and moc.

delta_t gives the possibility to the user to set a time resolution for performing the tmoc union

Parameters:

another_mocAbstractMOC: the MOC/TimeMoc to bind to self
delta_tTimeDelta, optional: the duration of one observation. It is set to 30 min by default. This data is used to compute the more efficient TimeMoc order to represent the observations. (Best order = the less precise order which is able to discriminate two observations separated by delta_t)

Returns:

resultMOC or TimeMoc: MOC object whose interval set corresponds to : self | moc

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

Navigation

mocpy.TimeMOC¶