From 3e4e59d31ab5da338634ae964e1ebac11bab5733 Mon Sep 17 00:00:00 2001 From: Vidushi-GitHub Date: Mon, 29 Jul 2024 17:15:44 -0500 Subject: [PATCH 01/13] Healpix doc --- app/routes/docs.notices.healpix.mdx | 65 +++++++++++++++++++++++++++++ app/routes/docs.tsx | 3 ++ 2 files changed, 68 insertions(+) create mode 100644 app/routes/docs.notices.healpix.mdx diff --git a/app/routes/docs.notices.healpix.mdx b/app/routes/docs.notices.healpix.mdx new file mode 100644 index 000000000..4766c49a8 --- /dev/null +++ b/app/routes/docs.notices.healpix.mdx @@ -0,0 +1,65 @@ +--- +handle: + breadcrumb: HEALPix Maps +--- + +import { Highlight } from '~/components/Highlight' +import { Tab, Tabs } from '~/components/tabs' + +# HEALPix Sky Maps + +HEALPix stands for Hierarchical, Equal Area, and iso-Latitude Pixelisation is a scheme for indexing positions on the unit sphere. +For localization of events, the multi-messenger community uses the standard (HEALPix)[https://healpix.sourceforge.io] format with the file extension `.fits.gz`, as well as multi-resolution HEALPix format with the file extension `.multiorder.fits`. The preferred format is the multi-resolution HEALPix format, that is only format explicitly listed in the GCN. + +## Multi-Order Sky Maps + +GCN strongly encourages the use of multi-order sky maps. These are a more complex form of healpix sky maps that utilize a variable resolution, with higher probability regions having higher resolution and lower probability regions being encoded with a lower resolution. This is signicantly more efficient than single-resolution healpix sky maps with respect to storage footprint and read speed. However, interpreting these multi-order sky maps can be more complex. + +## Working with HEALPix Maps + +HEALPix data is distrubuted in standard format with the file extension '''.fits.gz'''. These files are FITS image files and can be utilized with many common FITS tools. These files usually stored as HEALPix projection, + +### Reading Sky Maps + +Sky maps can be parsed using python; to start, import a handful of packages (note: while this documentation covers the use of '''astropy-healpix''', there are several packages that are ab) +''' +import astropy_healpix as ah +import numpy as np + +from astropy import units as u +from astropy.table import QTable +''' + +A given sky map can then be read in as +''' +skymap = QTable.read('skymap.multiofits) +''' + +### Most Probable Sky Location + +The index of the highest probability point can be found by doing the following +''' +hp_index = np.argmax(skymap['PROBDENSITY']) +uniq = skymap[hq_index]['UNIQ'] + +level, ipix = ah.uniq_to_level_ipix(uniq) +nside = ah.level_to_nside(level) + +ra, dec = ah.healpix_to_lonlat(ipix, nside, order='nested') +''' + +### Probability Density at a Known Position + +Similarly, + +### Find the 90% Probability Region + +## Further documentation + +Additional information can be found the (LIGO website)[https://emfollow.docs.ligo.org/userguide/tutorial/multiorder_sky maps.html#what-problem-do-multi-resolution-sky-maps-solve] + +## Libraries for reference + +(mhealpy)[https://mhealpy.readthedocs.io/en/latest/] + +(astropy-healpix)[https://astropy-healpix.readthedocs.io/en/latest/] diff --git a/app/routes/docs.tsx b/app/routes/docs.tsx index e9f0beff5..51f8edfd0 100644 --- a/app/routes/docs.tsx +++ b/app/routes/docs.tsx @@ -177,6 +177,9 @@ export default function () { Unified Schema , + + HEALPix + , Archive , From 4cfb926490235a9171181f6318ba997bd1890f0b Mon Sep 17 00:00:00 2001 From: Tyler Barna Date: Tue, 30 Jul 2024 09:13:03 -0500 Subject: [PATCH 02/13] fix code markdown --- app/routes/docs.notices.healpix.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/app/routes/docs.notices.healpix.mdx b/app/routes/docs.notices.healpix.mdx index 4766c49a8..94535ebbc 100644 --- a/app/routes/docs.notices.healpix.mdx +++ b/app/routes/docs.notices.healpix.mdx @@ -17,28 +17,28 @@ GCN strongly encourages the use of multi-order sky maps. These are a more comple ## Working with HEALPix Maps -HEALPix data is distrubuted in standard format with the file extension '''.fits.gz'''. These files are FITS image files and can be utilized with many common FITS tools. These files usually stored as HEALPix projection, +HEALPix data is distrubuted in standard format with the file extension ```.fits.gz```. These files are FITS image files and can be utilized with many common FITS tools. These files usually stored as HEALPix projection, ### Reading Sky Maps -Sky maps can be parsed using python; to start, import a handful of packages (note: while this documentation covers the use of '''astropy-healpix''', there are several packages that are ab) -''' +Sky maps can be parsed using python; to start, import a handful of packages (note: while this documentation covers the use of ```astropy-healpix```, there are several packages that are ab) +``` import astropy_healpix as ah import numpy as np from astropy import units as u from astropy.table import QTable -''' +``` A given sky map can then be read in as -''' +``` skymap = QTable.read('skymap.multiofits) -''' +``` ### Most Probable Sky Location The index of the highest probability point can be found by doing the following -''' +``` hp_index = np.argmax(skymap['PROBDENSITY']) uniq = skymap[hq_index]['UNIQ'] @@ -46,7 +46,7 @@ level, ipix = ah.uniq_to_level_ipix(uniq) nside = ah.level_to_nside(level) ra, dec = ah.healpix_to_lonlat(ipix, nside, order='nested') -''' +``` ### Probability Density at a Known Position From c58d3fc554b369badd4699835880a414c82c199c Mon Sep 17 00:00:00 2001 From: Vidushi Sharma <103223246+Vidushi-GitHub@users.noreply.github.com> Date: Tue, 30 Jul 2024 10:12:16 -0500 Subject: [PATCH 03/13] Update app/routes/docs.notices.healpix.mdx Co-authored-by: Leo Singer --- app/routes/docs.notices.healpix.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/routes/docs.notices.healpix.mdx b/app/routes/docs.notices.healpix.mdx index 94535ebbc..343be5b78 100644 --- a/app/routes/docs.notices.healpix.mdx +++ b/app/routes/docs.notices.healpix.mdx @@ -17,7 +17,7 @@ GCN strongly encourages the use of multi-order sky maps. These are a more comple ## Working with HEALPix Maps -HEALPix data is distrubuted in standard format with the file extension ```.fits.gz```. These files are FITS image files and can be utilized with many common FITS tools. These files usually stored as HEALPix projection, +HEALPix data is distrubuted in standard format with the file extension `.fits.gz`. These files are FITS image files and can be utilized with many common FITS tools. These files usually stored as HEALPix projection, ### Reading Sky Maps From e3c495ef08f3853b88353e6f06f8be74113dac32 Mon Sep 17 00:00:00 2001 From: Vidushi-GitHub Date: Tue, 30 Jul 2024 11:35:13 -0500 Subject: [PATCH 04/13] Markdown for python --- app/routes/docs.notices.healpix.mdx | 36 +++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/app/routes/docs.notices.healpix.mdx b/app/routes/docs.notices.healpix.mdx index 343be5b78..d35f2c9e1 100644 --- a/app/routes/docs.notices.healpix.mdx +++ b/app/routes/docs.notices.healpix.mdx @@ -21,8 +21,9 @@ HEALPix data is distrubuted in standard format with the file extension `.fits.gz ### Reading Sky Maps -Sky maps can be parsed using python; to start, import a handful of packages (note: while this documentation covers the use of ```astropy-healpix```, there are several packages that are ab) -``` +Sky maps can be parsed using python; to start, import a handful of packages (note: while this documentation covers the use of `astropy-healpix`, there are several packages that are ab) + +```python import astropy_healpix as ah import numpy as np @@ -31,14 +32,16 @@ from astropy.table import QTable ``` A given sky map can then be read in as -``` + +```python skymap = QTable.read('skymap.multiofits) ``` ### Most Probable Sky Location The index of the highest probability point can be found by doing the following -``` + +```python hp_index = np.argmax(skymap['PROBDENSITY']) uniq = skymap[hq_index]['UNIQ'] @@ -54,6 +57,31 @@ Similarly, ### Find the 90% Probability Region +The estimation of a 90% probability region, involves sorting the pixel, calculating the area of each pixel, and then proceeding by the probability of each pixel. + +```python +#Sort the pixels by decending probability density +skymap.sort('PROBDENSITY', reverse=True) + +#Area of each pixel +level, ipix = ah.uniq_to_level_ipix(skymap['UNIQ']) +pixel_area = ah.nside_to_pixel_area(ah.level_to_nside(level)) + +#Pixel area times the probability +prob = pixel_area * skymap['PROBDENSITY'] + +#Cummulative sum of probability +cumprob = np.cumsum(prob) + +#Pixels for which cummulative is 0.9 +i = cumprob.searchsorted(0.9) + +#Sum of the areas of the pixels up to that one +area_90 = pixel_area[:i].sum() +area_90.to_value(u.deg**2) + +``` + ## Further documentation Additional information can be found the (LIGO website)[https://emfollow.docs.ligo.org/userguide/tutorial/multiorder_sky maps.html#what-problem-do-multi-resolution-sky-maps-solve] From 1cf3ef1e518850c42d6a38633e4a91aa3d5b6f69 Mon Sep 17 00:00:00 2001 From: Tyler Barna Date: Tue, 30 Jul 2024 14:33:39 -0500 Subject: [PATCH 05/13] correct hyperlinks previous commits had hyperlink brackets/parentheses used incorrectly --- app/routes/docs.notices.healpix.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/app/routes/docs.notices.healpix.mdx b/app/routes/docs.notices.healpix.mdx index d35f2c9e1..ab9f738f0 100644 --- a/app/routes/docs.notices.healpix.mdx +++ b/app/routes/docs.notices.healpix.mdx @@ -9,7 +9,7 @@ import { Tab, Tabs } from '~/components/tabs' # HEALPix Sky Maps HEALPix stands for Hierarchical, Equal Area, and iso-Latitude Pixelisation is a scheme for indexing positions on the unit sphere. -For localization of events, the multi-messenger community uses the standard (HEALPix)[https://healpix.sourceforge.io] format with the file extension `.fits.gz`, as well as multi-resolution HEALPix format with the file extension `.multiorder.fits`. The preferred format is the multi-resolution HEALPix format, that is only format explicitly listed in the GCN. +For localization of events, the multi-messenger community uses the standard [HEALPix](https://healpix.sourceforge.io) format with the file extension `.fits.gz`, as well as multi-resolution HEALPix format with the file extension `.multiorder.fits`. The preferred format is the multi-resolution HEALPix format, that is only format explicitly listed in the GCN. ## Multi-Order Sky Maps @@ -84,10 +84,10 @@ area_90.to_value(u.deg**2) ## Further documentation -Additional information can be found the (LIGO website)[https://emfollow.docs.ligo.org/userguide/tutorial/multiorder_sky maps.html#what-problem-do-multi-resolution-sky-maps-solve] +Additional information can be found the [LIGO website](https://emfollow.docs.ligo.org/userguide/tutorial/multiorder_sky maps.html) ## Libraries for reference -(mhealpy)[https://mhealpy.readthedocs.io/en/latest/] +[mhealpy](https://mhealpy.readthedocs.io/en/latest/) -(astropy-healpix)[https://astropy-healpix.readthedocs.io/en/latest/] +[astropy-healpix](https://astropy-healpix.readthedocs.io/en/latest/) From b5e90122dd565cf71b361b5529778c6a64347aa5 Mon Sep 17 00:00:00 2001 From: Tyler Barna Date: Tue, 30 Jul 2024 14:38:45 -0500 Subject: [PATCH 06/13] rewrite known prob density recreate lost content --- app/routes/docs.notices.healpix.mdx | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/app/routes/docs.notices.healpix.mdx b/app/routes/docs.notices.healpix.mdx index ab9f738f0..831246217 100644 --- a/app/routes/docs.notices.healpix.mdx +++ b/app/routes/docs.notices.healpix.mdx @@ -53,7 +53,20 @@ ra, dec = ah.healpix_to_lonlat(ipix, nside, order='nested') ### Probability Density at a Known Position -Similarly, +Similarly, one can calculate the probability density at a known position + +```python +ra, dec = 197.450341598 * u.deg, -23.3814675445 * u.deg + +level, ipix = ah.uniq_to_level_ipix(skymap['UNIQ']) +nside = ah.level_to_nside(level) + +match_ipix = ad.lonlat_to_healpix(ra, dec, nside, order='nested') + +match_index = np.flatnonzero(ipix == match_ipix)[0] + +prob_density = skymap[match_index]['PROBDENSITY'].to_value(u.deg**-2) +``` ### Find the 90% Probability Region From 54fc7bb83e785ad8fccda8c3b5f7ec7936a72074 Mon Sep 17 00:00:00 2001 From: Vidushi-GitHub Date: Wed, 31 Jul 2024 11:54:41 -0500 Subject: [PATCH 07/13] update reference --- app/routes/docs.notices.healpix.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/app/routes/docs.notices.healpix.mdx b/app/routes/docs.notices.healpix.mdx index 831246217..5b3920672 100644 --- a/app/routes/docs.notices.healpix.mdx +++ b/app/routes/docs.notices.healpix.mdx @@ -101,6 +101,10 @@ Additional information can be found the [LIGO website](https://emfollow.docs.lig ## Libraries for reference -[mhealpy](https://mhealpy.readthedocs.io/en/latest/) +[healpy](https://healpy.readthedocs.io/en/latest/): Official python library for handling the pixlated data on sphere -[astropy-healpix](https://astropy-healpix.readthedocs.io/en/latest/) +[astropy-healpix](https://pypi.org/project/astropy-healpix/) + +[mhealpy](https://mhealpy.readthedocs.io/en/latest/): Object-oriented wrapper of healpy for handling the multi-resolution maps + +[MOCpy](https://cds-astro.github.io/mocpy/): Python library allowing easy creation, parsing and manipulation of Multi-Order Coverage maps. From be44d76438176c505840946b93a936c12bcce0d4 Mon Sep 17 00:00:00 2001 From: Tyler Barna <57914086+tylerbarna@users.noreply.github.com> Date: Thu, 1 Aug 2024 11:46:17 -0500 Subject: [PATCH 08/13] Update app/routes/docs.notices.healpix.mdx --- app/routes/docs.notices.healpix.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/routes/docs.notices.healpix.mdx b/app/routes/docs.notices.healpix.mdx index 5b3920672..c0da21863 100644 --- a/app/routes/docs.notices.healpix.mdx +++ b/app/routes/docs.notices.healpix.mdx @@ -21,7 +21,7 @@ HEALPix data is distrubuted in standard format with the file extension `.fits.gz ### Reading Sky Maps -Sky maps can be parsed using python; to start, import a handful of packages (note: while this documentation covers the use of `astropy-healpix`, there are several packages that are ab) +Sky maps can be parsed using python; to start, import a handful of packages (note: while this documentation covers the use of `astropy-healpix`, there are several packages that can be used for this purpose; a number of alternatives are listed at the bottom of this page) ```python import astropy_healpix as ah From bb74178fcca5acc5b8fb1365214468fbf4c97e6f Mon Sep 17 00:00:00 2001 From: Vidushi-GitHub Date: Thu, 1 Aug 2024 23:23:01 -0500 Subject: [PATCH 09/13] mollweide, prob in cone, and papers --- app/routes/docs.notices.healpix.mdx | 88 +++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/app/routes/docs.notices.healpix.mdx b/app/routes/docs.notices.healpix.mdx index c0da21863..91eec611f 100644 --- a/app/routes/docs.notices.healpix.mdx +++ b/app/routes/docs.notices.healpix.mdx @@ -95,6 +95,78 @@ area_90.to_value(u.deg**2) ``` +### Flat Resolution HEALPix Sky maps + +Let's say you have a sky map fits file, read in Python with Healpy: + +```python +import healpy as hp +import numpy as np + +# Read both the HEALPix image data and the FITS header +hpx, header = hp.read_map('*.fits.gz,0', h=True) + +# Plotting a Mollweide-projection all-sky map +np.mollview(hpx) +``` + +Most Probable Sky Location + +```python +# Find the highest probability pixel +ipix_max = np.argmax(hpx) + +# Probability density per square degree at that position +hpx[ipix_max] / hp.nside2pixarea(nside, degrees=True) + +# Highest probability pixel on the sky +theta, phi = hp.pix2ang(nside, ipix_max) +ra = np.rad2deg(phi) +dec = np.rad2deg(0.5 * np.pi - theta) +ra, dec +``` + +### Integrated probability in a Circle + +We call hp.query_disc to obtain an array of indices for the pixels inside the circle. + +```python +# First define the Cartesian coordinates of the center of the Circle +ra = 180.0 +dec = -45.0 +radius = 2.5 + +# We convert to spherical polar coordinates +theta = 0.5 * np.pi - np.deg2rad(dec) +phi = np.deg2rad(ra) +radius = np.deg2rad(radius) + +# Calculate Cartesian coordinates of the center of the Circle +xyz = hp.ang2vec(theta, phi) + +# Obtain an array of indices for the pixels inside the circle +ipix_disc = hp.query_disc(nside, xyz, radius) + +# Sum the probability in all of the matching pixels: +hpx[ipix_disc].sum() + +``` + +### Integrated probability in a Polygon + +We can use the `hp.query_polygon` function to find the pixels inside a polygon and compute the probability that the source is inside the polygon by adding up the pixel values. + +```python +# Indices of the pixels within a polygon (defined by the Cartesian coordinates of its vertices) + +xyz = [[-0.5, -0.4, -0.5], + [-0.4, -0.4, -0.6], + [-0.6, -0.3, -0.6], + [-0.7 , -0.4, -0.5]] +ipix_poly = hp.query_polygon(nside, xyz) +hpx[ipix_poly].sum() +``` + ## Further documentation Additional information can be found the [LIGO website](https://emfollow.docs.ligo.org/userguide/tutorial/multiorder_sky maps.html) @@ -108,3 +180,19 @@ Additional information can be found the [LIGO website](https://emfollow.docs.lig [mhealpy](https://mhealpy.readthedocs.io/en/latest/): Object-oriented wrapper of healpy for handling the multi-resolution maps [MOCpy](https://cds-astro.github.io/mocpy/): Python library allowing easy creation, parsing and manipulation of Multi-Order Coverage maps. + +## Papers + +(1) Calabretta, M. R., & Roukema, B. F. 2007, Mon. Notices Royal Astron. Soc., 381, 865. [doi:10.1111/j.1365-2966.2007.12297.x](https://academic.oup.com/mnras/article/381/2/865/1021805?login=true) + +(2) Górski, K.M., Hivon, E., Banday, A.J., et al. 2005, Astrophys. J., 622, 759. [doi:10.1086/427976](https://iopscience.iop.org/article/10.1086/427976) + +(3) Górski, K. M., Wandelt, B. D., et al. 1999. [arXiv:astro-ph/9905275](https://arxiv.org/abs/astro-ph/9905275) + +(4) Fernique, P., Allen, et al. 2015, Astron. Astrophys., 578, A114. [doi:10.1051/0004-6361/201526075](https://www.aanda.org/articles/aa/full_html/2015/06/aa26075-15/aa26075-15.html) + +(5) Fernique, P., Boch, T., et al. 2014, IVOA Recommendation. [arXiv:1505.02937](https://arxiv.org/abs/1505.02937) + +(6) Martinez-Castellanos, I., Singer, L. P., et al. 2022, Astrophys. J., 163, 259. [doi:10.3847/1538-3881/ac6260](https://iopscience.iop.org/article/10.3847/1538-3881/ac6260) + +(7) Singer, L. P., & Price, L. R. 2016, Phys. Rev. D, 93, 024013. [doi:10.1103/PhysRevD.93.024013](https://journals.aps.org/prd/abstract/10.1103/PhysRevD.93.024013) From 74997634bdd798cea1d98cf9c085920748aa7c4e Mon Sep 17 00:00:00 2001 From: Tyler Barna Date: Fri, 2 Aug 2024 12:46:59 -0500 Subject: [PATCH 10/13] move documentation this relocates the documentation into the sample code page under the kafka client setup --- app/routes/docs.client.samples.md | 199 ++++++++++++++++++++++++++++ app/routes/docs.notices.healpix.mdx | 198 --------------------------- 2 files changed, 199 insertions(+), 198 deletions(-) delete mode 100644 app/routes/docs.notices.healpix.mdx diff --git a/app/routes/docs.client.samples.md b/app/routes/docs.client.samples.md index 059507b46..adae7a16a 100644 --- a/app/routes/docs.client.samples.md +++ b/app/routes/docs.client.samples.md @@ -164,3 +164,202 @@ for message in consumer.consume(end[0].offset - start[0].offset, timeout=1): continue print(message.value()) ``` + +--- + +handle: +breadcrumb: HEALPix Maps + +--- + +import { Highlight } from '~/components/Highlight' +import { Tab, Tabs } from '~/components/tabs' + +## HEALPix Sky Maps + +HEALPix stands for Hierarchical, Equal Area, and iso-Latitude Pixelisation is a scheme for indexing positions on the unit sphere. +For localization of events, the multi-messenger community uses the standard [HEALPix](https://healpix.sourceforge.io) format with the file extension `.fits.gz`, as well as multi-resolution HEALPix format with the file extension `.multiorder.fits`. The preferred format is the multi-resolution HEALPix format, that is only format explicitly listed in the GCN. + +### Multi-Order Sky Maps + +GCN strongly encourages the use of multi-order sky maps. These are a more complex form of healpix sky maps that utilize a variable resolution, with higher probability regions having higher resolution and lower probability regions being encoded with a lower resolution. This is signicantly more efficient than single-resolution healpix sky maps with respect to storage footprint and read speed. However, interpreting these multi-order sky maps can be more complex. + +### Working with HEALPix Maps + +HEALPix data is distrubuted in standard format with the file extension `.fits.gz`. These files are FITS image files and can be utilized with many common FITS tools. These files usually stored as HEALPix projection, + +#### Reading Sky Maps + +Sky maps can be parsed using python; to start, import a handful of packages (note: while this documentation covers the use of `astropy-healpix`, there are several packages that can be used for this purpose; a number of alternatives are listed at the bottom of this page) + +```python +import astropy_healpix as ah +import numpy as np + +from astropy import units as u +from astropy.table import QTable +``` + +A given sky map can then be read in as + +```python +skymap = QTable.read('skymap.multiofits) +``` + +#### Most Probable Sky Location + +The index of the highest probability point can be found by doing the following + +```python +hp_index = np.argmax(skymap['PROBDENSITY']) +uniq = skymap[hq_index]['UNIQ'] + +level, ipix = ah.uniq_to_level_ipix(uniq) +nside = ah.level_to_nside(level) + +ra, dec = ah.healpix_to_lonlat(ipix, nside, order='nested') +``` + +#### Probability Density at a Known Position + +Similarly, one can calculate the probability density at a known position + +```python +ra, dec = 197.450341598 * u.deg, -23.3814675445 * u.deg + +level, ipix = ah.uniq_to_level_ipix(skymap['UNIQ']) +nside = ah.level_to_nside(level) + +match_ipix = ad.lonlat_to_healpix(ra, dec, nside, order='nested') + +match_index = np.flatnonzero(ipix == match_ipix)[0] + +prob_density = skymap[match_index]['PROBDENSITY'].to_value(u.deg**-2) +``` + +#### Find the 90% Probability Region + +The estimation of a 90% probability region, involves sorting the pixel, calculating the area of each pixel, and then proceeding by the probability of each pixel. + +```python +#Sort the pixels by decending probability density +skymap.sort('PROBDENSITY', reverse=True) + +#Area of each pixel +level, ipix = ah.uniq_to_level_ipix(skymap['UNIQ']) +pixel_area = ah.nside_to_pixel_area(ah.level_to_nside(level)) + +#Pixel area times the probability +prob = pixel_area * skymap['PROBDENSITY'] + +#Cummulative sum of probability +cumprob = np.cumsum(prob) + +#Pixels for which cummulative is 0.9 +i = cumprob.searchsorted(0.9) + +#Sum of the areas of the pixels up to that one +area_90 = pixel_area[:i].sum() +area_90.to_value(u.deg**2) + +``` + +#### Flat Resolution HEALPix Sky maps + +Let's say you have a sky map fits file, read in Python with Healpy: + +```python +import healpy as hp +import numpy as np + +# Read both the HEALPix image data and the FITS header +hpx, header = hp.read_map('*.fits.gz,0', h=True) + +# Plotting a Mollweide-projection all-sky map +np.mollview(hpx) +``` + +Most Probable Sky Location + +```python +# Find the highest probability pixel +ipix_max = np.argmax(hpx) + +# Probability density per square degree at that position +hpx[ipix_max] / hp.nside2pixarea(nside, degrees=True) + +# Highest probability pixel on the sky +theta, phi = hp.pix2ang(nside, ipix_max) +ra = np.rad2deg(phi) +dec = np.rad2deg(0.5 * np.pi - theta) +ra, dec +``` + +#### Integrated probability in a Circle + +We call hp.query_disc to obtain an array of indices for the pixels inside the circle. + +```python +# First define the Cartesian coordinates of the center of the Circle +ra = 180.0 +dec = -45.0 +radius = 2.5 + +# We convert to spherical polar coordinates +theta = 0.5 * np.pi - np.deg2rad(dec) +phi = np.deg2rad(ra) +radius = np.deg2rad(radius) + +# Calculate Cartesian coordinates of the center of the Circle +xyz = hp.ang2vec(theta, phi) + +# Obtain an array of indices for the pixels inside the circle +ipix_disc = hp.query_disc(nside, xyz, radius) + +# Sum the probability in all of the matching pixels: +hpx[ipix_disc].sum() + +``` + +#### Integrated probability in a Polygon + +We can use the `hp.query_polygon` function to find the pixels inside a polygon and compute the probability that the source is inside the polygon by adding up the pixel values. + +```python +# Indices of the pixels within a polygon (defined by the Cartesian coordinates of its vertices) + +xyz = [[-0.5, -0.4, -0.5], + [-0.4, -0.4, -0.6], + [-0.6, -0.3, -0.6], + [-0.7 , -0.4, -0.5]] +ipix_poly = hp.query_polygon(nside, xyz) +hpx[ipix_poly].sum() +``` + +##### Further documentation + +Additional information can be found on the [LIGO website](https://emfollow.docs.ligo.org/userguide/tutorial/multiorder_sky maps.html) + +[healpy](https://healpy.readthedocs.io/en/latest/): Official python library for handling the pixlated data on sphere + +[astropy-healpix](https://pypi.org/project/astropy-healpix/) + +[mhealpy](https://mhealpy.readthedocs.io/en/latest/): Object-oriented wrapper of healpy for handling the multi-resolution maps + +[MOCpy](https://cds-astro.github.io/mocpy/): Python library allowing easy creation, parsing and manipulation of Multi-Order Coverage maps. + +## Papers + +(1) Calabretta, M. R., & Roukema, B. F. 2007, Mon. Notices Royal Astron. Soc., 381, 865. [doi:10.1111/j.1365-2966.2007.12297.x](https://academic.oup.com/mnras/article/381/2/865/1021805?login=true) + +(2) Górski, K.M., Hivon, E., Banday, A.J., et al. 2005, Astrophys. J., 622, 759. [doi:10.1086/427976](https://iopscience.iop.org/article/10.1086/427976) + +(3) Górski, K. M., Wandelt, B. D., et al. 1999. [arXiv:astro-ph/9905275](https://arxiv.org/abs/astro-ph/9905275) + +(4) Fernique, P., Allen, et al. 2015, Astron. Astrophys., 578, A114. [doi:10.1051/0004-6361/201526075](https://www.aanda.org/articles/aa/full_html/2015/06/aa26075-15/aa26075-15.html) + +(5) Fernique, P., Boch, T., et al. 2014, IVOA Recommendation. [arXiv:1505.02937](https://arxiv.org/abs/1505.02937) + +(6) Martinez-Castellanos, I., Singer, L. P., et al. 2022, Astrophys. J., 163, 259. [doi:10.3847/1538-3881/ac6260](https://iopscience.iop.org/article/10.3847/1538-3881/ac6260) + +(7) Singer, L. P., & Price, L. R. 2016, Phys. Rev. D, 93, 024013. [doi:10.1103/PhysRevD.93.024013](https://journals.aps.org/prd/abstract/10.1103/PhysRevD.93.024013) diff --git a/app/routes/docs.notices.healpix.mdx b/app/routes/docs.notices.healpix.mdx deleted file mode 100644 index 91eec611f..000000000 --- a/app/routes/docs.notices.healpix.mdx +++ /dev/null @@ -1,198 +0,0 @@ ---- -handle: - breadcrumb: HEALPix Maps ---- - -import { Highlight } from '~/components/Highlight' -import { Tab, Tabs } from '~/components/tabs' - -# HEALPix Sky Maps - -HEALPix stands for Hierarchical, Equal Area, and iso-Latitude Pixelisation is a scheme for indexing positions on the unit sphere. -For localization of events, the multi-messenger community uses the standard [HEALPix](https://healpix.sourceforge.io) format with the file extension `.fits.gz`, as well as multi-resolution HEALPix format with the file extension `.multiorder.fits`. The preferred format is the multi-resolution HEALPix format, that is only format explicitly listed in the GCN. - -## Multi-Order Sky Maps - -GCN strongly encourages the use of multi-order sky maps. These are a more complex form of healpix sky maps that utilize a variable resolution, with higher probability regions having higher resolution and lower probability regions being encoded with a lower resolution. This is signicantly more efficient than single-resolution healpix sky maps with respect to storage footprint and read speed. However, interpreting these multi-order sky maps can be more complex. - -## Working with HEALPix Maps - -HEALPix data is distrubuted in standard format with the file extension `.fits.gz`. These files are FITS image files and can be utilized with many common FITS tools. These files usually stored as HEALPix projection, - -### Reading Sky Maps - -Sky maps can be parsed using python; to start, import a handful of packages (note: while this documentation covers the use of `astropy-healpix`, there are several packages that can be used for this purpose; a number of alternatives are listed at the bottom of this page) - -```python -import astropy_healpix as ah -import numpy as np - -from astropy import units as u -from astropy.table import QTable -``` - -A given sky map can then be read in as - -```python -skymap = QTable.read('skymap.multiofits) -``` - -### Most Probable Sky Location - -The index of the highest probability point can be found by doing the following - -```python -hp_index = np.argmax(skymap['PROBDENSITY']) -uniq = skymap[hq_index]['UNIQ'] - -level, ipix = ah.uniq_to_level_ipix(uniq) -nside = ah.level_to_nside(level) - -ra, dec = ah.healpix_to_lonlat(ipix, nside, order='nested') -``` - -### Probability Density at a Known Position - -Similarly, one can calculate the probability density at a known position - -```python -ra, dec = 197.450341598 * u.deg, -23.3814675445 * u.deg - -level, ipix = ah.uniq_to_level_ipix(skymap['UNIQ']) -nside = ah.level_to_nside(level) - -match_ipix = ad.lonlat_to_healpix(ra, dec, nside, order='nested') - -match_index = np.flatnonzero(ipix == match_ipix)[0] - -prob_density = skymap[match_index]['PROBDENSITY'].to_value(u.deg**-2) -``` - -### Find the 90% Probability Region - -The estimation of a 90% probability region, involves sorting the pixel, calculating the area of each pixel, and then proceeding by the probability of each pixel. - -```python -#Sort the pixels by decending probability density -skymap.sort('PROBDENSITY', reverse=True) - -#Area of each pixel -level, ipix = ah.uniq_to_level_ipix(skymap['UNIQ']) -pixel_area = ah.nside_to_pixel_area(ah.level_to_nside(level)) - -#Pixel area times the probability -prob = pixel_area * skymap['PROBDENSITY'] - -#Cummulative sum of probability -cumprob = np.cumsum(prob) - -#Pixels for which cummulative is 0.9 -i = cumprob.searchsorted(0.9) - -#Sum of the areas of the pixels up to that one -area_90 = pixel_area[:i].sum() -area_90.to_value(u.deg**2) - -``` - -### Flat Resolution HEALPix Sky maps - -Let's say you have a sky map fits file, read in Python with Healpy: - -```python -import healpy as hp -import numpy as np - -# Read both the HEALPix image data and the FITS header -hpx, header = hp.read_map('*.fits.gz,0', h=True) - -# Plotting a Mollweide-projection all-sky map -np.mollview(hpx) -``` - -Most Probable Sky Location - -```python -# Find the highest probability pixel -ipix_max = np.argmax(hpx) - -# Probability density per square degree at that position -hpx[ipix_max] / hp.nside2pixarea(nside, degrees=True) - -# Highest probability pixel on the sky -theta, phi = hp.pix2ang(nside, ipix_max) -ra = np.rad2deg(phi) -dec = np.rad2deg(0.5 * np.pi - theta) -ra, dec -``` - -### Integrated probability in a Circle - -We call hp.query_disc to obtain an array of indices for the pixels inside the circle. - -```python -# First define the Cartesian coordinates of the center of the Circle -ra = 180.0 -dec = -45.0 -radius = 2.5 - -# We convert to spherical polar coordinates -theta = 0.5 * np.pi - np.deg2rad(dec) -phi = np.deg2rad(ra) -radius = np.deg2rad(radius) - -# Calculate Cartesian coordinates of the center of the Circle -xyz = hp.ang2vec(theta, phi) - -# Obtain an array of indices for the pixels inside the circle -ipix_disc = hp.query_disc(nside, xyz, radius) - -# Sum the probability in all of the matching pixels: -hpx[ipix_disc].sum() - -``` - -### Integrated probability in a Polygon - -We can use the `hp.query_polygon` function to find the pixels inside a polygon and compute the probability that the source is inside the polygon by adding up the pixel values. - -```python -# Indices of the pixels within a polygon (defined by the Cartesian coordinates of its vertices) - -xyz = [[-0.5, -0.4, -0.5], - [-0.4, -0.4, -0.6], - [-0.6, -0.3, -0.6], - [-0.7 , -0.4, -0.5]] -ipix_poly = hp.query_polygon(nside, xyz) -hpx[ipix_poly].sum() -``` - -## Further documentation - -Additional information can be found the [LIGO website](https://emfollow.docs.ligo.org/userguide/tutorial/multiorder_sky maps.html) - -## Libraries for reference - -[healpy](https://healpy.readthedocs.io/en/latest/): Official python library for handling the pixlated data on sphere - -[astropy-healpix](https://pypi.org/project/astropy-healpix/) - -[mhealpy](https://mhealpy.readthedocs.io/en/latest/): Object-oriented wrapper of healpy for handling the multi-resolution maps - -[MOCpy](https://cds-astro.github.io/mocpy/): Python library allowing easy creation, parsing and manipulation of Multi-Order Coverage maps. - -## Papers - -(1) Calabretta, M. R., & Roukema, B. F. 2007, Mon. Notices Royal Astron. Soc., 381, 865. [doi:10.1111/j.1365-2966.2007.12297.x](https://academic.oup.com/mnras/article/381/2/865/1021805?login=true) - -(2) Górski, K.M., Hivon, E., Banday, A.J., et al. 2005, Astrophys. J., 622, 759. [doi:10.1086/427976](https://iopscience.iop.org/article/10.1086/427976) - -(3) Górski, K. M., Wandelt, B. D., et al. 1999. [arXiv:astro-ph/9905275](https://arxiv.org/abs/astro-ph/9905275) - -(4) Fernique, P., Allen, et al. 2015, Astron. Astrophys., 578, A114. [doi:10.1051/0004-6361/201526075](https://www.aanda.org/articles/aa/full_html/2015/06/aa26075-15/aa26075-15.html) - -(5) Fernique, P., Boch, T., et al. 2014, IVOA Recommendation. [arXiv:1505.02937](https://arxiv.org/abs/1505.02937) - -(6) Martinez-Castellanos, I., Singer, L. P., et al. 2022, Astrophys. J., 163, 259. [doi:10.3847/1538-3881/ac6260](https://iopscience.iop.org/article/10.3847/1538-3881/ac6260) - -(7) Singer, L. P., & Price, L. R. 2016, Phys. Rev. D, 93, 024013. [doi:10.1103/PhysRevD.93.024013](https://journals.aps.org/prd/abstract/10.1103/PhysRevD.93.024013) From f624380611347f11e486bf00acf2662ec453f1df Mon Sep 17 00:00:00 2001 From: Tyler Barna Date: Fri, 2 Aug 2024 12:49:01 -0500 Subject: [PATCH 11/13] remove link to deleted healpix page --- app/routes/docs.tsx | 3 --- 1 file changed, 3 deletions(-) diff --git a/app/routes/docs.tsx b/app/routes/docs.tsx index 51f8edfd0..e9f0beff5 100644 --- a/app/routes/docs.tsx +++ b/app/routes/docs.tsx @@ -177,9 +177,6 @@ export default function () { Unified Schema , - - HEALPix - , Archive , From 1fda4d869563fd200774a7067f35ca521ca1df2f Mon Sep 17 00:00:00 2001 From: Tyler Barna Date: Fri, 2 Aug 2024 15:22:06 -0500 Subject: [PATCH 12/13] corrections to breadcrumbs and imports remove extra breadcrumb that was not appropriate to include and change imports to be at the top of the page --- app/routes/docs.client.samples.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/app/routes/docs.client.samples.md b/app/routes/docs.client.samples.md index adae7a16a..cd022c88f 100644 --- a/app/routes/docs.client.samples.md +++ b/app/routes/docs.client.samples.md @@ -3,6 +3,9 @@ handle: breadcrumb: Sample Code --- +import { Highlight } from '~/components/Highlight' +import { Tab, Tabs } from '~/components/tabs' + # Sample Code Here is a collection of functions and example code that may be useful @@ -165,16 +168,6 @@ for message in consumer.consume(end[0].offset - start[0].offset, timeout=1): print(message.value()) ``` ---- - -handle: -breadcrumb: HEALPix Maps - ---- - -import { Highlight } from '~/components/Highlight' -import { Tab, Tabs } from '~/components/tabs' - ## HEALPix Sky Maps HEALPix stands for Hierarchical, Equal Area, and iso-Latitude Pixelisation is a scheme for indexing positions on the unit sphere. From 569e18cef4568a4efb29dd3de16f04ba773505bf Mon Sep 17 00:00:00 2001 From: Tyler Barna Date: Mon, 7 Oct 2024 12:28:29 -0500 Subject: [PATCH 13/13] resolve doi issue all references use doi now, and they are also updated such that they use the standardized doi link as well --- app/routes/docs.client.samples.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/app/routes/docs.client.samples.md b/app/routes/docs.client.samples.md index cd022c88f..e0233d323 100644 --- a/app/routes/docs.client.samples.md +++ b/app/routes/docs.client.samples.md @@ -343,16 +343,16 @@ Additional information can be found on the [LIGO website](https://emfollow.docs. ## Papers -(1) Calabretta, M. R., & Roukema, B. F. 2007, Mon. Notices Royal Astron. Soc., 381, 865. [doi:10.1111/j.1365-2966.2007.12297.x](https://academic.oup.com/mnras/article/381/2/865/1021805?login=true) +(1) Calabretta, M. R., & Roukema, B. F. 2007, Mon. Notices Royal Astron. Soc., 381, 865. [doi: 10.1111/j.1365-2966.2007.12297.x](https://doi.org/10.1111/j.1365-2966.2007.12297.x) -(2) Górski, K.M., Hivon, E., Banday, A.J., et al. 2005, Astrophys. J., 622, 759. [doi:10.1086/427976](https://iopscience.iop.org/article/10.1086/427976) +(2) Górski, K.M., Hivon, E., Banday, A.J., et al. 2005, Astrophys. J., 622, 759. [doi: 10.1086/427976](https://doi.org/10.1086/427976) -(3) Górski, K. M., Wandelt, B. D., et al. 1999. [arXiv:astro-ph/9905275](https://arxiv.org/abs/astro-ph/9905275) +(3) Górski, K. M., Wandelt, B. D., et al. 1999. [doi: 10.48550/arXiv.astro-ph/9905275](https://doi.org/10.48550/arXiv.astro-ph/9905275) -(4) Fernique, P., Allen, et al. 2015, Astron. Astrophys., 578, A114. [doi:10.1051/0004-6361/201526075](https://www.aanda.org/articles/aa/full_html/2015/06/aa26075-15/aa26075-15.html) +(4) Fernique, P., Allen, et al. 2015, Astron. Astrophys., 578, A114. [doi: 10.1051/0004-6361/201526075](https://doi.org/10.1051/0004-6361/201526075) -(5) Fernique, P., Boch, T., et al. 2014, IVOA Recommendation. [arXiv:1505.02937](https://arxiv.org/abs/1505.02937) +(5) Fernique, P., Boch, T., et al. 2014, IVOA Recommendation. [doi: 10.48550/arXiv.1505.02937](https://doi.org/10.48550/arXiv.1505.02937) -(6) Martinez-Castellanos, I., Singer, L. P., et al. 2022, Astrophys. J., 163, 259. [doi:10.3847/1538-3881/ac6260](https://iopscience.iop.org/article/10.3847/1538-3881/ac6260) +(6) Martinez-Castellanos, I., Singer, L. P., et al. 2022, Astrophys. J., 163, 259. [doi: 10.3847/1538-3881/ac6260](https://doi.org/10.3847/1538-3881/ac6260) -(7) Singer, L. P., & Price, L. R. 2016, Phys. Rev. D, 93, 024013. [doi:10.1103/PhysRevD.93.024013](https://journals.aps.org/prd/abstract/10.1103/PhysRevD.93.024013) +(7) Singer, L. P., & Price, L. R. 2016, Phys. Rev. D, 93, 024013. [doi: 10.1103/PhysRevD.93.024013](https://doi.org/10.1103/PhysRevD.93.024013)