Merge pull request #147 from cds-astro/fix-documentation-on-plots

miscellaneous documentation and maintenance points

CHANGELOG.md

@@ -23,6 +23,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * a new method `MOC.from_cones` allows to create a list of MOCs from a list of centers
 and radii. This is multi-threaded.
 * new method `MOC.from_boxes` allows to create lists of MOCs from boxes. This is multi-threaded.
+* the `mocpy.WCS` class can now accept a sequence of angles as its fov argument rather than always
+representing square areas of the sky.
+* `MOC.from_polygons` and `MOC.from_polygons` now accept a boolean `complement` that allows to chose
+between the small MOC described by the polygon or the bigger one (its complement)
 
 ### Changed
 

Cargo.toml

@@ -14,6 +14,7 @@ categories = ["algorithms", "science"]
 repository = "https://github.com/cds-astro/mocpy"
 description = "MOC parsing and manipulation in Python"
 documentation = "https://cds-astro.github.io/mocpy"
+exclude = [".*", "binder/", "docs/", "notebooks/", "resources/"]
 
 [badges]
 maintenance = { status = "actively-developed" }

docs/api.rst

@@ -1,5 +1,5 @@
-API
-===
+Detailed list of all methods
+============================
 
 Auto-generated API documentation for MOCpy.
 

docs/examples/bayestar.py

@@ -1,10 +1,10 @@
 import astropy.units as u
-import astropy_healpix as ah
 import matplotlib.pyplot as plt
 import numpy as np
-from astropy.coordinates import Angle, SkyCoord
 from astropy.io import fits
-from mocpy import MOC, WCS
+from astropy.visualization.wcsaxes.frame import EllipticalFrame
+from astropy.wcs import WCS
+from mocpy import MOC
 
 # this can be found in mocpy's repository
 # https://github.com/cds-astro/mocpy/blob/master/resources/bayestar.multiorder.fits
@@ -19,8 +19,8 @@
 probdensity = data["PROBDENSITY"]
 
 # let's convert the probability density into a probability
-level, ipix = ah.uniq_to_level_ipix(uniq)
-area = ah.nside_to_pixel_area(ah.level_to_nside(level)).to_value(u.steradian)
+orders = (np.log2(uniq // 4)) // 2
+area = 4 * np.pi / np.array([MOC.n_cells(int(order)) for order in orders]) * u.sr
 prob = probdensity * area
 
 # now we create the mocs corresponding to different probability thresholds
@@ -32,32 +32,40 @@
 
 
 # Plot the MOC using matplotlib
-fig = plt.figure(111, figsize=(15, 10))
-# Define a astropy WCS easily
-with WCS(
-    fig,
-    fov=50 * u.deg,
-    center=SkyCoord(315, 15, unit="deg", frame="icrs"),
-    coordsys="icrs",
-    rotation=Angle(0, u.degree),
-    projection="AIT",
-) as wcs:
-    ax = fig.add_subplot(1, 1, 1, projection=wcs)
-    # Call fill with a matplotlib axe and the `~astropy.wcs.WCS` wcs object.
-    for moc, c, col in zip(mocs, cumul_to, colors):
-        moc.fill(
-            ax=ax,
-            wcs=wcs,
-            alpha=0.5,
-            linewidth=0,
-            fill=True,
-            color=col,
-            label="confidence probability " + str(round(c * 100)) + "%",
-        )
-        moc.border(ax=ax, wcs=wcs, alpha=0.5, color=col)
-    ax.legend()
+fig = plt.figure(111)
+# Define a astropy WCS
+wcs = WCS(
+    {
+        "naxis": 2,
+        "naxis1": 3240,
+        "naxis2": 3240,
+        "crpix1": 1620.5,
+        "crpix2": 1620.5,
+        "cdelt1": -0.0353,
+        "cdelt2": 0.0353,
+        "ctype1": "RA---SIN",
+        "ctype2": "DEC--SIN",
+    },
+)
+
+ax = fig.add_subplot(1, 1, 1, projection=wcs, frame_class=EllipticalFrame)
+# Call fill with a matplotlib axe and the `~astropy.wcs.WCS` wcs object.
+for moc, c, col in zip(mocs, cumul_to, colors):
+    moc.fill(
+        ax=ax,
+        wcs=wcs,
+        alpha=0.5,
+        linewidth=0,
+        fill=True,
+        color=col,
+        label="confidence proba " + str(round(c * 100)) + "%",
+    )
+    moc.border(ax=ax, wcs=wcs, alpha=0.5, color=col)
+ax.legend(loc="upper center", bbox_to_anchor=(0, 1))
+ax.set_aspect(1.0)
 plt.xlabel("ra")
 plt.ylabel("dec")
 plt.title("Bayestar")
 plt.grid(color="black", linestyle="dotted")
+plt.tight_layout()
 plt.show()

docs/examples/calculate_moc_sky_area.py

@@ -1,8 +1,8 @@
-import numpy as np
 import astropy.units as u
+import numpy as np
 from mocpy import MOC
 
 ALL_SKY = 4 * np.pi * u.steradian
-moc = MOC.from_string("0/0-11") # any other MOC instance will work
+moc = MOC.from_string("0/0-11")  # any other MOC instance will work
 area = moc.sky_fraction * ALL_SKY
 area = area.to(u.deg**2).value

docs/examples/compute_borders.py

@@ -4,7 +4,6 @@
 from astropy.coordinates import Angle, SkyCoord
 from matplotlib.patches import PathPatch
 from matplotlib.path import Path
-
 from mocpy import MOC, WCS
 
 moc = MOC.from_fits("polygon_moc.fits")

docs/examples/filter_image_pixels.py

@@ -4,7 +4,6 @@
 from astropy.io import fits
 from astropy.visualization import simple_norm
 from astropy.wcs import WCS as WCS
-
 from mocpy import MOC
 
 # load 2MASS cutout covering the galactic plane

docs/examples/logical_operations.py

@@ -1,8 +1,7 @@
-import astropy.units as u
 import matplotlib.pyplot as plt
-from astropy.coordinates import Angle, SkyCoord
-
-from mocpy import MOC, WCS
+from astropy.visualization.wcsaxes.frame import EllipticalFrame
+from astropy.wcs import WCS
+from mocpy import MOC
 
 # Load Galex and SDSS
 sdss = MOC.from_fits("./../../resources/P-SDSS9-r.fits")
@@ -11,41 +10,46 @@
 inter = sdss & galex
 union = sdss + galex
 # Plot the MOC using matplotlib
-fig = plt.figure(111, figsize=(10, 10))
-# Define a astropy WCS easily
-with WCS(
-    fig,
-    fov=160 * u.deg,
-    center=SkyCoord(0, 0, unit="deg", frame="icrs"),
-    coordsys="icrs",
-    rotation=Angle(0, u.degree),
-    projection="AIT",
-) as wcs:
-    ax = fig.add_subplot(1, 1, 1, projection=wcs)
-    # Call fill with a matplotlib axe and the `~astropy.wcs.WCS` wcs object.
-    union.fill(
-        ax=ax,
-        wcs=wcs,
-        alpha=0.5,
-        fill=True,
-        color="red",
-        linewidth=0,
-        label="Union",
-    )
-    union.border(ax=ax, wcs=wcs, alpha=1, color="red")
-
-    inter.fill(
-        ax=ax,
-        wcs=wcs,
-        alpha=0.5,
-        fill=True,
-        color="green",
-        linewidth=0,
-        label="Intersection",
-    )
-    inter.border(ax=ax, wcs=wcs, alpha=1, color="green")
-    ax.legend()
+fig = plt.figure(111, figsize=(10, 8))
+# Define a astropy WCS
+wcs = WCS(
+    {
+        "naxis": 2,
+        "naxis1": 3240,
+        "naxis2": 1620,
+        "crpix1": 1620.5,
+        "crpix2": 810.5,
+        "cdelt1": -0.1,
+        "cdelt2": 0.1,
+        "ctype1": "RA---AIT",
+        "ctype2": "DEC--AIT",
+    },
+)
+ax = fig.add_subplot(1, 1, 1, projection=wcs, frame_class=EllipticalFrame)
+# Call fill with a matplotlib axe and the `~astropy.wcs.WCS` wcs object.
+union.fill(
+    ax=ax,
+    wcs=wcs,
+    alpha=0.5,
+    fill=True,
+    color="blue",
+    linewidth=0,
+    label="Union",
+)
+union.border(ax=ax, wcs=wcs, alpha=1, color="black")
 
+inter.fill(
+    ax=ax,
+    wcs=wcs,
+    alpha=0.5,
+    fill=True,
+    color="green",
+    linewidth=0,
+    label="Intersection",
+)
+inter.border(ax=ax, wcs=wcs, alpha=1, color="black")
+ax.legend()
+ax.set_aspect(1.0)
 plt.xlabel("ra")
 plt.ylabel("dec")
 plt.title("Logical operations between SDSS and GALEX")

docs/examples/plot_SDSS_r.py

@@ -1,20 +1,32 @@
-import astropy.units as u
 import matplotlib.pyplot as plt
-from astropy.coordinates import Angle
-
+from astropy.visualization.wcsaxes.frame import EllipticalFrame
+from astropy.wcs import WCS
 from mocpy import MOC
 
 # Load a MOC
 filename = "./../../resources/P-SDSS9-r.fits"
 moc = MOC.from_fits(filename)
 # Plot the MOC using matplotlib
 fig = plt.figure(111, figsize=(15, 10))
-# Define a astropy WCS easily
-wcs = moc.wcs(fig, coordsys="icrs", rotation=Angle(0, u.degree), projection="AIT")
-ax = fig.add_subplot(1, 1, 1, projection=wcs)
+# Define a astropy WCS
+wcs = WCS(
+    {
+        "naxis": 2,
+        "naxis1": 1620,
+        "naxis2": 810,
+        "crpix1": 810.5,
+        "crpix2": 405.5,
+        "cdelt1": -0.2,
+        "cdelt2": 0.2,
+        "ctype1": "RA---AIT",
+        "ctype2": "DEC--AIT",
+    },
+)
+ax = fig.add_subplot(1, 1, 1, projection=wcs, frame_class=EllipticalFrame)
 # Call fill with a matplotlib axe and the `~astropy.wcs.WCS` wcs object.
 moc.fill(ax=ax, wcs=wcs, alpha=0.5, fill=True, color="green")
 moc.border(ax=ax, wcs=wcs, alpha=0.5, color="black")
+ax.set_aspect(1.0)
 plt.xlabel("ra")
 plt.ylabel("dec")
 plt.title("Coverage of P-SDSS9-r")

docs/examples/polygon_coverage.py

@@ -30,10 +30,7 @@
     ],
 )
 skycoord = SkyCoord(vertices, unit="deg", frame="icrs")
-# A point that we say it belongs to the inside of the MOC
-inside = SkyCoord(ra=10, dec=5, unit="deg", frame="icrs")
-moc = MOC.from_polygon_skycoord(skycoord, max_depth=9)
-moc.save("polygon_moc.fits", format="fits", overwrite=True)
+moc = MOC.from_polygon_skycoord(skycoord, complement=False, max_depth=9)
 
 # Plot the MOC using matplotlib
 fig = plt.figure(111, figsize=(10, 10))

docs/examples/user_documentation.rst

@@ -11,12 +11,12 @@ Gallery of notebooks examples using SMOCs
 
 .. nbgallery::
     ../_collections/notebooks/00-MOCpy_introduction
-    ../_collections/notebooks/compute_moc_borders.ipynb
+    ../_collections/notebooks/compute_moc_borders
     ../_collections/notebooks/filtering_astropy_table
     ../_collections/notebooks/FITS-image-pixels-intersecting-MOC
     ../_collections/notebooks/from_astropy_table.ipynb
-    ../_collections/notebooks/from-astropy-regions
-    ../_collections/notebooks/from_polygon
+    ../_collections/notebooks/01-Creating_MOCs_from_shapes
+    ../_collections/notebooks/02-Creating_MOCs_from_astropy_regions
     ../_collections/notebooks/from_fits_and_intersection
     ../_collections/notebooks/from_image_with_mask
     ../_collections/notebooks/from_vizier_table
@@ -59,14 +59,18 @@ This example:
 .. plot:: examples/logical_operations.py
     :include-source:
 
-Create a MOC from a concave polygon
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Create a MOC from a polygon
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This example shows how to call :py:meth:`mocpy.moc.MOC.from_polygon` or :py:meth:`mocpy.moc.MOC.from_polygon_skycoord`.
 
 .. plot:: examples/polygon_coverage.py
     :include-source:
 
+For a more extended description on how to create MOCs from shapes, you can check the example notebooks
+:doc:`../_collections/notebooks/01-Creating_MOCs_from_shapes` and
+:doc:`../_collections/notebooks/02-Creating_MOCs_from_astropy_regions`.
+
 Get the border(s) of a MOC
 ~~~~~~~~~~~~~~~~~~~~~~~~~~