\n",
+ "The schemas for the PS1 DR2 tables are available at: https://mastdev.stsci.edu/schema_browser/#/\n",
+ " \n",
+ "
\n",
+ "\n",
+ "\n",
+ "**IF POSSIBLE:**\n",
+ "Integrete the schema browser.\n",
+ "\n",
+ "Or else provide a simple URL link, so users can still use the schema browser even if it isn't fully integrated with the jupyter notebook?\n",
+ "
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "*********\n",
+ "\n",
+ "## Q12\n",
+ "\n",
+ "Following [Gray et al. (2002)](https://arxiv.org/abs/cs/0202014), but modifying by shifting one filter to the red (as PS1 has no `u` filter) and pushing one magnitude fainter (as PS1 is deeper than SDSS), Query 12 poses: \n",
+ "\n",
+ "> **Create a gridded count of galaxies with g-r>1 and i<22.5 over -5\n",
+ "Add correct link to the migration guide in the above paragraph.\n",
+ "
\n",
+ "\n",
+ "Similar to the above example, this query will combine filtering and binning --- but in this case, the binning is greatly simplified as we can directly use the HTM ids which are available for all entries in the `stack_object` table.\n",
+ "\n",
+ "\n",
+ "We apply selection criteria to:\n",
+ "- Apply the color and magnitude constraints (`(0.7*gkronmag-0.5*rkronmag-0.2*ikronmag) < 1.25` and `ikronmag < 22.5`).\n",
+ "- Apply quality cuts and remove contamination:\n",
+ " - Require entries to both be marked as a `primarydetection`and the `bestdetection` in the `ps1_dr2.stack_object` table (`primarydetection > 0`, `bestdetection > 0`)\n",
+ " - Require the sum of the `g`, `r`, `i` magnitudes to be greater than 0 (filtering out objects with missing photometry in any of these bands, denoted with values of -999)\n",
+ " - Select only extended sources (using `ipsfmag > 0` and `(ipsfmag-ikronmag > 0.05)`\n",
+ "\n",
+ "We then bin over the set of the 8-deep HTM buckets (with each covering about 1 square degree) using a \"group by\" statement, retrieving the 8-deep HTM buckets by right-shifting the HTM ids by 12 (as specified by Gray et al.).\n",
+ "\n",
+ "For this example, we also restrict the RA range to be within [245, 330] degrees, to ensure the query does not exceed the row limits for the MAST TAP service.\n",
+ "\n",
+ "> (**Note:** If executing this query in chunks to cover the full sky, chunks over 8-deep HTM buckets should be chosen and *not* RA ranges, as RA ranges do not cleanly overlap our desired 8-deep HTM bucket tiling.)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "RightShift12 = np.power(4, 12) # Divisor to go from HTM IDs to the 8-deep HTM buckets\n",
+ "\n",
+ "adql_query = f\"\"\"\n",
+ "select (htmid/{RightShift12}) as htm_8, \n",
+ "avg(ramean) as ra, \n",
+ "avg(decmean) as dec,\n",
+ "count(*) as pop\n",
+ "from ps1_dr2.stack_object as s\n",
+ "where primarydetection>0 and bestdetection>0\n",
+ " and (gkronmag+rkronmag+ikronmag) > 0 -- remove -999 values\n",
+ " and (ipsfmag>0) and (ipsfmag-ikronmag > 0.05) -- extended sources (galaxies)\n",
+ " and (0.7*gkronmag-0.5*rkronmag-0.2*ikronmag) < 1.25 -- meeting this color cut\n",
+ " and (ikronmag < 22.5)\n",
+ "and ramean between 245 and 330\n",
+ "group by (htmid/{RightShift12})\n",
+ "\"\"\""
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We then submit this query to the TAP service (and capture the elapsed time)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "start = time.time()\n",
+ "job = TAP_service.run_async(adql_query)\n",
+ "end = time.time()\n",
+ "print(f\"Elapsed time: {str(datetime.timedelta(seconds=end-start))}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Q13: Inspecting & visualizing the results\n",
+ "\n",
+ "This query takes about 2.5 minutes to run and returned 94,834 rows. \n",
+ "\n",
+ "To query the full sky PanSTARRS coverage (without RA range restrictions), it would take ~10.5 minutes to run the queries, and would result in ~400,000 total rows."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "TAP_results_q13 = job.to_table()\n",
+ "TAP_results_q13"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "In total, 45,530,164 galaxies are included in the binned counts (for this RA range)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "TAP_results_q13[\"pop\"].sum()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We now visualize the binned counts. As these bins span a wide swath of the sky, we will display the bin counts as a scatter plot over an Aitoff projection, with each bin's point colored by the number of galaxies in that bin."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Aitoff-projection scatter plot of HTM-8 bins\n",
+ "\n",
+ "f = plt.figure(figsize=(10, 5))\n",
+ "ax = f.add_axes([0.05, 0.05, 0.925, 0.9], projection=\"aitoff\")\n",
+ "cax = f.add_axes([0.985, 0.05, 0.025, 0.9])\n",
+ "\n",
+ "counts = ax.scatter(\n",
+ " Angle(TAP_results_q13['ra']*u.deg).wrap_at(180 * u.deg).radian,\n",
+ " Angle(TAP_results_q13['dec']*u.deg).radian,\n",
+ " c=TAP_results_q13['pop'],\n",
+ " lw=0,\n",
+ " s=2,\n",
+ " norm=PowerNorm(0.5),\n",
+ " cmap=\"plasma\",\n",
+ ")\n",
+ "\n",
+ "ax.grid(True)\n",
+ "f.colorbar(counts, cax=cax)\n",
+ "cax.yaxis.set_major_locator(MultipleLocator(1000))\n",
+ "cax.yaxis.set_major_formatter(ScalarFormatter())\n",
+ "\n",
+ "ax.set_xlabel('RA')\n",
+ "ax.set_ylabel('Dec')\n",
+ "ax.set_title(\"Q13: HTMid Gridding\", pad=15)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The distribution is fairly uniform, as expected for galaxies. Near the plane of the Milky Way (the arc that runs from middle left, up to the north (in the RA slice we have selected --- the Galactic plane also runs back down to the lower right if repeated over the full sky) there are some variations seen. The darker regions have a lower density of objects per sky area, which is a real effect due to absorption by dust near the plane of the galaxy (which reduces galaxy brightnesses and so reduces the counts). \n",
+ "\n",
+ "The brighter regions are areas with very high stellar densities. Those stars are often blended together with neighbors, which produces a catalog object that appears to be spatially extended. Those objects are interpreted as galaxies and so get erroneously included in the counts. These effects near the Milky Way would need to be corrected before using this sky density for scientific analysis (or they could simply be excluded from the sample).\n",
+ "\n",
+ "We do note that one complication with this example directly using HTM binning is that **HTM bins do not have equal area on the sky**. This leads to the (spherical) triangular color pattern imprinted on the astrophysical signal on the sky (as described above). It *is* be possible to correct for the bin-area discrepancies by calculating the sky area in each bin. However, functions to perform such calculations are not available with MAST's PS1 TAP service, so determining this factor has been omitted from this tutorial example."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "----------\n",
+ "\n",
+ "## Additional Resources\n",
+ "\n",
+ "### Table Access Protocol\n",
+ "\n",
+ "- IVOA standard for RESTful web service access to tabular data\n",
+ "- http://www.ivoa.net/documents/TAP/\n",
+ "\n",
+ "### PanSTARRS 1 DR 2\n",
+ "\n",
+ "- https://outerspace.stsci.edu/display/PANSTARRS/\n",
+ "\n",
+ "### Astronomical Query Data Language (2.0)\n",
+ "\n",
+ "- IVOA standard for querying astronomical data in tabular format, with geometric search support\n",
+ "- http://www.ivoa.net/documents/latest/ADQL.html\n",
+ "\n",
+ "### PyVO\n",
+ "\n",
+ "- an affiliated package for [astropy](https://www.astropy.org/)\n",
+ "- find and retrieve astronomical data available from archives that support standard IVOA virtual observatory service protocols.\n",
+ "- https://pyvo.readthedocs.io/en/latest/index.html\n",
+ "\n",
+ "\n",
+ "### Full list of MAST/TAP services\n",
+ "- A full list of available MAST TAP services can be found at:\n",
+ "- https://mast.stsci.edu/vo-tap\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Citations\n",
+ "If you use `astropy` for published research, please cite the\n",
+ "authors. Follow these links for more information about citing `astropy`:\n",
+ "\n",
+ "* [Citing `astropy`](https://www.astropy.org/acknowledging.html)\n",
+ "\n",
+ "If you use PanSTARRS data accessed through MAST for published research, \n",
+ "please include the following acknowledgements, found at the following links:\n",
+ "\n",
+ "* [Acknowledging PanSTARRS](https://archive.stsci.edu/publishing/mission-acknowledgements#section-895d38a0-86b3-4143-b521-6cc3312701f9)\n",
+ "* [Acknowledging MAST](https://archive.stsci.edu/gsc/mast_data_use.html)\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "slideshow": {
+ "slide_type": "slide"
+ }
+ },
+ "source": [
+ "## About this Notebook\n",
+ "\n",
+ "\n",
+ "**Author(s):** Rick White, Sedona Price\n", + "**Keyword(s):** Tutorial, TAP, pyvo, ADQL, Pan-STARRS
\n", + "**First Published:** 2026-06-05
\n", + "**Last Updated:** 2026-06-05\n", + "***\n", + "[Top of Page](#top)\n", + "
![\"Space](\"https://raw.githubusercontent.com/spacetelescope/style-guides/master/guides/images/stsci-logo.png\"){kind=logo}
"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3 (ipykernel)",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.13.3"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
diff --git a/notebooks/PanSTARRS/PS1_20_query_tutorials/PS1_20q_spatial_binning/requirements.txt b/notebooks/PanSTARRS/PS1_20_query_tutorials/PS1_20q_spatial_binning/requirements.txt
new file mode 100644
index 00000000..fa3fd842
--- /dev/null
+++ b/notebooks/PanSTARRS/PS1_20_query_tutorials/PS1_20q_spatial_binning/requirements.txt
@@ -0,0 +1,4 @@
+astropy >= 5.3.3
+matplotlib >= 3.7.1
+numpy >= 1.25.0
+pyvo >= 1.4.1
diff --git a/notebooks/PanSTARRS/PS1_20_query_tutorials/panstarrs_20_query_tutorials.md b/notebooks/PanSTARRS/PS1_20_query_tutorials/panstarrs_20_query_tutorials.md
new file mode 100644
index 00000000..ef950d3a
--- /dev/null
+++ b/notebooks/PanSTARRS/PS1_20_query_tutorials/panstarrs_20_query_tutorials.md
@@ -0,0 +1,16 @@
+# Example "20 queries" with PanSTARRS
+
+## For Further Reading
+
+For information about Pan-STARRS and links to Pan-STARRS resources, please see [the Pan-STARRS landing page](https://spacetelescope.github.io/mast_notebooks/notebooks/PanSTARRS/panstarrs.html).
+
+## Notebooks in this Section
+
+The notebooks in this section demonstrate how to execute example science queries, grouped by technique & technical similarities. These queries are drawn from the 20 queries for SDSS as presented by [Gray, Szalay, et al. (2002)](https://arxiv.org/abs/cs/0202014), adapted for the Pan-STARRS PS1 database. In all, this series of notebooks will present the 11 queries which are applicable for PS1.
+
+
+| Notebook | Description |
+|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [Pan-STARRS "20 queries": Spatial Binning](https://spacetelescope.github.io/mast_notebooks/notebooks/PanSTARRS/PS1_20_query_tutorials/PS1_20q_spatial_binning/PS1_20q_spatial_binning.html) | Tutorial demonstrating how to spatially bin (with selection criteria filtering) objects from the Pan-STARRS DR2 catalogs, using the Table Access Protocol (TAP) service at MAST. |
+
+More Pan-STARRS example query notebooks will be coming soon!
diff --git a/notebooks/PanSTARRS/panstarrs.md b/notebooks/PanSTARRS/panstarrs.md
new file mode 100644
index 00000000..6a5f25a4
--- /dev/null
+++ b/notebooks/PanSTARRS/panstarrs.md
@@ -0,0 +1,30 @@
+# Panoramic Survey Telescope and Rapid Response System (Pan-STARRS)
+
+## What is Pan-STARRS?
+[Panoramic Survey Telescope and Rapid Response System (Pan-STARRS)](http://pan-starrs.ifa.hawaii.edu/) is a system for wide-field astronomical imaging developed
+and operated by the Institute for Astronomy at the University of Hawaii.
+Pan-STARRS1 (PS1) is the first part of Pan-STARRS to be completed and is the basis
+for both Data Releases 1 and 2 (DR1 and DR2).
+The PS1 survey used a 1.8 meter telescope and its 1.4 Gigapixel camera (GPC1; see
+[PS1 GPC1 camera](https://outerspace.stsci.edu/spaces/PANSTARRS/pages/298812301/PS1+GPC1+camera))
+to image the sky in five broadband [filters](https://outerspace.stsci.edu/display/PANSTARRS/PS1+Filter+properties) (g, r, i, z, y). The PS1 Science Consortium funded the operation of the Pan-STARRS1 telescope, situated at Haleakala Observatories near the summit of
+Haleakala in Hawaii, for the purposes of astronomical research.
+The PS1 consortium is made up of astronomers and engineers from
+[14 institutions from six countries](https://outerspace.stsci.edu/spaces/PANSTARRS/pages/298812469/PS1+Science+Consortium+-+PS1SC).
+
+The data from PS1 are archived at the [Space Telescope Science Institute](http://www.stsci.edu/) (STScI) in Baltimore Maryland, and can be accessed through MAST, the Mikulski Archive for Space Telescopes (see the [Pan-STARRS1 Data Archive](https://outerspace.stsci.edu/display/PANSTARRS/Pan-STARRS1+data+archive+home+page)). Additional support for the PS1 public science archive is provided by the [Gordon and Betty Moore Foundation](https://www.moore.org/).
+
+## For Further Reading
+
+The [Pan-STARRS1 Data Archive at MAST](https://outerspace.stsci.edu/display/PANSTARRS/Pan-STARRS1+data+archive+home+page) website contains summary information, data product overviews, descriptions of MAST tools, and tutorials on how to interact with PS1 data at MAST.
+
+For more general information regarding Pan-STARRS1, see the [MAST Pan-STARRS1 homepage](https://archive.stsci.edu/missions-and-data/pan-starrs), and the [Pan-STARRS system homepage](http://pan-starrs.ifa.hawaii.edu/).
+
+## Notebooks in this Chapter
+
+
+| Notebook | Description |
+|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [MAST Table Access Protocol Pan-STARRS1 DR2 Tutorial](https://spacetelescope.github.io/mast_notebooks/notebooks/PanSTARRS/PS1_DR2_TAP/PS1_DR2_TAP.html) | Tutorial demonstrating how to access Pan-STARRS 1 Data Release 2 catalogs via a Virtual Observatory standard Table Access Protocol (TAP) service at MAST. |
+| [Retreiving Pan-STARRS images Tutorial](https://spacetelescope.github.io/mast_notebooks/notebooks/PanSTARRS/PS1_image/PS1_image.html) | Tutorial of how to programmatically retrieve Pan-STARRS1 image cutouts using the PS1 Image Server at MAST. |
+| [Pan-STARRS "20 queries" Tutorials](https://spacetelescope.github.io/mast_notebooks/notebooks/PanSTARRS/PS1_20_query_tutorials/panstarrs_20_query_tutorials.html) | Tutorials with examples of how to answer select scientify questions through queries to the PS1 DR2 catalogs using the Table Access Protocol (TAP) service at MAST. |
\ No newline at end of file