Skip to content

Commit 07e45c7

Browse files
ManonMarchandManonMarchand
committed
docs: create sections in Space MOC doc
1 parent e1ff4bf commit 07e45c7

File tree

3 files changed

+90
-34
lines changed

3 files changed

+90
-34
lines changed

‎docs/examples/all_sky.py

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
from mocpy import MOC
2+
3+
all_sky = MOC.from_str("0/0-11") # the 12 cells of HEALPix at order 0
4+
all_sky.display_preview() # the inside of the MOC is represented in red with display_preview

‎docs/examples/odd_cells.py

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
from mocpy import MOC
2+
3+
moc = MOC.from_json({"1": [i for i in range(12 * 4) if i % 2 == 1]})
4+
moc.display_preview()

‎docs/examples/user_documentation.rst

+82-34
Original file line numberDiff line numberDiff line change
@@ -6,27 +6,95 @@ User documentation
66
SMOC (a.k.a MOC): Spatial coverages
77
***********************************
88

9-
Gallery of notebooks examples using SMOCs
10-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9+
Introduction to Space-MOCs
10+
==========================
11+
12+
Space MOCs are an ensemble of HEALPix cells of mixed orders. They represent sky regions
13+
in an approximate way. They are designed for efficient calculations between sky regions.
14+
15+
The coordinates for Space-MOCs are always in IRCS at epoch J2000 by definition.
16+
17+
Space-MOCs can represent arbitrary shapes. Common examples are an approximated cone, an
18+
ensemble of approximated cones, or the coverage of a specific survey.
19+
20+
The following notebook is an introduction to manipulation of Space-MOCs with MOCPy:
1121

1222
.. nbgallery::
1323
../_collections/notebooks/00-MOCpy_introduction
14-
../_collections/notebooks/compute_moc_borders
15-
../_collections/notebooks/filtering_astropy_table
16-
../_collections/notebooks/FITS-image-pixels-intersecting-MOC
17-
../_collections/notebooks/from_astropy_table.ipynb
24+
25+
As you saw, Space-MOCs can be visualized with either astropy+matplotlib or with the
26+
ipyaladin widget.
27+
28+
Space-MOC creation methods
29+
==========================
30+
31+
Reading a MOC from a file or from a server
32+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
33+
34+
There are diverse ways to instantiate a MOC. A first approach is to get a MOC from a
35+
FITS file on our disk, or from a distant server that already has a pre-calculated MOC.
36+
37+
.. nbgallery::
38+
../_collections/notebooks/from_fits_and_intersection
39+
../_collections/notebooks/from_vizier_table
40+
41+
Calculating a MOC on the fly from a region of the sky
42+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43+
44+
Here is a simple example of the creation of a MOC that fully covers a polygon defined
45+
by its vertices on the sky. The vertices are linked by great circles.
46+
47+
.. plot:: examples/polygon_coverage.py
48+
:include-source:
49+
50+
For a more extended description on how to create MOCs from diverse shapes, you can check
51+
the example notebooks :doc:`../_collections/notebooks/01-Creating_MOCs_from_shapes` and
52+
:doc:`../_collections/notebooks/02-Creating_MOCs_from_astropy_regions`.
53+
54+
.. nbgallery::
1855
../_collections/notebooks/01-Creating_MOCs_from_shapes
1956
../_collections/notebooks/02-Creating_MOCs_from_astropy_regions
20-
../_collections/notebooks/from_fits_and_intersection
57+
../_collections/notebooks/from_astropy_table.ipynb
2158
../_collections/notebooks/from_image_with_mask
22-
../_collections/notebooks/from_vizier_table
23-
../_collections/notebooks/query_vizier_table
2459

25-
Here are some code examples manipulating :py:class:`MOC` objects.
60+
Instantiating a MOC when we already know its HEALPix cells
61+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2662

27-
Examples use cases
28-
==================
63+
This can be done with methods like :py:meth:`~mocpy.moc.MOC.from_string`,
64+
:py:meth:`~mocpy.moc.MOC.from_healpix_cells`, :py:meth:`~mocpy.moc.MOC.from_depth29_ranges`.
65+
A simple MOC that represents the full sky is the MOC of order 0 that contains all the 12
66+
HEALPix cells of the order 0. Creating it from a string looks like:
2967

68+
.. plot:: examples/all_sky.py
69+
:include-source:
70+
71+
We could also take only odd numbered cells of order 1. Let's use
72+
:py:meth:`~mocpy.moc.MOC.from_json` that takes a dictionary:
73+
74+
.. plot:: examples/odd_cells.py
75+
:include-source:
76+
77+
Useful methods
78+
==============
79+
80+
Calculating a Space-MOC sky area
81+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
82+
83+
This example shows how to calculate the sky area of a Space-MOC.
84+
85+
.. plot:: examples/calculate_moc_sky_area.py
86+
:include-source:
87+
88+
Other examples (operations, use-cases)
89+
======================================
90+
91+
Here are some other code examples manipulating :py:class:`MOC` objects.
92+
93+
.. nbgallery::
94+
../_collections/notebooks/compute_moc_borders
95+
../_collections/notebooks/filtering_astropy_table
96+
../_collections/notebooks/FITS-image-pixels-intersecting-MOC
97+
../_collections/notebooks/query_vizier_table
3098

3199
Loading and plotting the MOC of SDSS
32100
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -38,7 +106,7 @@ This example:
38106

39107
1. Defining a matplotlib figure.
40108
2. Defining an astropy WCS representing the field of view of the plot.
41-
3. Call the :py:meth:`mocpy.moc.MOC.fill` and :py:meth:`mocpy.moc.MOC.border` so that mocpy plot on a matplotlib axis.
109+
3. Call the :py:meth:`~mocpy.moc.MOC.fill` and :py:meth:`~mocpy.moc.MOC.border` so that mocpy plot on a matplotlib axis.
42110
4. Set the axis labels, a title, enable the grid and plot the final figure.
43111

44112

@@ -59,22 +127,10 @@ This example:
59127
.. plot:: examples/logical_operations.py
60128
:include-source:
61129

62-
Create a MOC from a polygon
63-
~~~~~~~~~~~~~~~~~~~~~~~~~~~
64-
65-
This example shows how to call :py:meth:`mocpy.moc.MOC.from_polygon` or :py:meth:`mocpy.moc.MOC.from_polygon_skycoord`.
66-
67-
.. plot:: examples/polygon_coverage.py
68-
:include-source:
69-
70-
For a more extended description on how to create MOCs from shapes, you can check the example notebooks
71-
:doc:`../_collections/notebooks/01-Creating_MOCs_from_shapes` and
72-
:doc:`../_collections/notebooks/02-Creating_MOCs_from_astropy_regions`.
73-
74130
Get the border(s) of a MOC
75131
~~~~~~~~~~~~~~~~~~~~~~~~~~
76132

77-
This example shows how to call `mocpy.moc.MOC.get_boundaries`. The borders are returned as a list of `~astropy.coordinates.SkyCoord` each defining one border.
133+
This example shows how to call `~mocpy.moc.MOC.get_boundaries`. The borders are returned as a list of `~astropy.coordinates.SkyCoord` each defining one border.
78134
In this example:
79135

80136
1. The sky coordinates defining the border of the MOC are projected to the pixel image system.
@@ -98,14 +154,6 @@ By definition the MOC which has 100% of chance of containing a GW is the full sk
98154
.. plot:: examples/bayestar.py
99155
:include-source:
100156

101-
Calculate MOC sky area
102-
~~~~~~~~~~~~~~~~~~~~~~
103-
104-
This example shows how to Calculate the sky area of a MOC instance.
105-
106-
.. plot:: examples/calculate_moc_sky_area.py
107-
:include-source:
108-
109157
Performing computation on the pixels of an FITS image lying in a MOC
110158
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
111159

0 commit comments

Comments
 (0)