DP02_01_Introduccion_a_DP02_ES.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "749b0ddf",
   "metadata": {
    "tags": []
   },
   "source": [
    "<img align=\"left\" src = https://project.lsst.org/sites/default/files/Rubin-O-Logo_0.png width=250 style=\"padding: 10px\"> \n",
    "<br><b>Introducción a Jupyter Notebooks para Data Preview 0.2</b> <br>\n",
    "Autoría: Melissa Graham <br>\n",
    "Última verificación de ejecución: 2024-12-17 <br>\n",
    "Versión de las Pipelines Científicas de LSST: Weekly 2024_50 <br>\n",
    "Tamaño del contenedor (Container size): medium <br>\n",
    "Nivel de aprendizaje: principiante <br>\n",
    "<br>\n",
    "<br>\n",
    "</img>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf7b00a0-a005-4a22-a4c7-a6ecb32c749a",
   "metadata": {},
   "source": [
    "**Descripción:** una introducción al uso de los Jupyter Notebooks y los paquetes de Python de Rubin para acceder a los productos de datos de LSST (imágenes y catálogos)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ed8dff8-bcf7-4508-a2f2-cd2260321261",
   "metadata": {},
   "source": [
    "**Habilidades:** ejecutar código Python en un Jupyter Notebook. Usar el servicio TAP para obtener datos del catálogo Object. Utilizar Butler para obtener y visualizar una imagen deepCoadd."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a748b3a3-00e8-4215-adfa-adcabff26f56",
   "metadata": {},
   "source": [
    "**Productos de Datos LSST:** TAP dp02_dc2_catalogs. Tabla Object. Imagen deepCoadd con Butler."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "387f46c8-d58f-400f-a6e6-f21c9ae7ce94",
   "metadata": {},
   "source": [
    "**Paquetes:** lsst.rsp.get_tap_service, lsst.rsp.retrieve_query, lsst.daf.butler, lsst.afw.display, lsst.geom, pandas, matplotlib"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7d622b84-83fa-4de9-94b6-d16af645a37e",
   "metadata": {},
   "source": [
    "**Créditos:** desarrollado originalmente por Melissa Graham y el equipo científico de la comunidad de Rubin (Rubin Community Science Team) en el contexto de la Vista Previa de Datos de Rubin DP0.1."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8f72b27f",
   "metadata": {},
   "source": [
    "**Soporte:**\n",
    "se pueden encontrar recursos y documentación relacionada a DP0 en <a href=\"https://dp0.lsst.io\">dp0.lsst.io</a>. Las preguntas son bienvenidas como nuevos temas en la categoría <a href=\"https://community.lsst.org/c/support/dp0\">Support - Data Preview 0</a> del foro de la comunidad de Rubin. El equipo de Rubin responderá a todas las preguntas publicadas allí."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cfc73be0",
   "metadata": {},
   "source": [
    "## 1.0. Introducción\n",
    "\n",
    "Este Jupyter Notebook da una introducción a cómo funcionan los notebooks. Muestra cómo ejecutar celdas de código y de texto *markdown*, cómo importar paquetes de Python y aprender acerca de sus módulos, y provee enlaces a documentacion adicional.\n",
    "\n",
    "Este Notebook también muestra la funcionalidad básica de la Plataforma Científica de Rubin (RSP - Rubin Science Platform) instalada en el Centro Interino de Datos (IDF - Interim Data Facility; Google Cloud) incluyendo cómo usar el servicio TAP para consultar y obtener datos de catálogos; matplotlib para graficar datos de catálogos; el paquete Butler de LSST para consultar y obtener datos de imágenes; y el paquete afwDisplay de LSST para visualizar imágenes.\n",
    "\n",
    "Este notebook utiliza el conjunto de datos Vista Previa de Datos 0.2 (DP0.2 - Data Preview 0.2). Este conjunto de datos utiliza un subconjunto de imágenes simuladas del Desafío de Datos 2 de DESC (DC2 - DESC's Data Challenge 2), que han sido *reprocesadas* por el Observatorio Rubin usando la versión 23 de las Pipelines Científicas de LSST (LSST Science Pipelines). Se puede encontrar más información sobre los datos simulados en el [artículo científico de DC2](https://ui.adsabs.harvard.edu/abs/2021ApJS..253...31L/abstract>) de DESC y en la [documentación de la divulgación de datos de DP0.2](https://dp0-2.lsst.io)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3507e32",
   "metadata": {},
   "source": [
    "### 1.1. Cómo usar un Jupyter Notebook\n",
    "\n",
    "Los Jupyter Notebooks contienen una combinación de código, salida, visualizaciones y texto narrativo. La fuente de documentación más completa acerca de los Jupyter Notebooks es [https://jupyter-notebook.readthedocs.io](https://jupyter-notebook.readthedocs.io), pero hay numerosos y muy buenos tutoriales y demostraciones para principiantes disponibles. Generalmente una búsqueda en la web de una pregunta, como por ejemplo \"cómo hacer una tabla markdown en jupyter notebook\", llevará a varios buenos ejemplos. A menudo las respuestas se hallarán en [StackOverflow](https://stackoverflow.com/).\n",
    "\n",
    "Un Jupyter Notebook es una serie de celdas (cells). Hay tres tipos de celdas: código, markdown y raw (en bruto). Este texto se generó a partir de una celda markdown. Arriba en la barra de menú vas a encontrar un menú desplegable para establecer el tipo de celda."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3db41666-4e0a-4a7e-93a5-90b99286fedf",
   "metadata": {},
   "source": [
    ">  **Advertencia:** todas las celdas de código en un notebook deben ser ejecutadas en el orden en que aparecen."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6fb67584-1bc1-4049-9f93-fa0f45d477c0",
   "metadata": {},
   "source": [
    "Hacer clic en la siguiente celda de código: con el cursor en la celda, presionar simultaneamente \"shift\" (tecla *Mayús*) y \"enter\" (tecla *Entrar*) para ejecutar el código de la celda."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ba94de19",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Esta es una celda de código. Presionar shift-enter para ejecutar.\n",
    "# El # convierte estas líneas en comentarios, no código. No se ejecutan.\n",
    "print('Hello, world!')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "06a6f7ed-284b-4a35-b0ba-d95a1300d463",
   "metadata": {},
   "source": [
    "<!---\n",
    "Esta es una celda markdown.\n",
    "Presiona shift-enter para ejecutar y ver reaparecer el texto formateado.\n",
    "-->\n",
    "Hacer doble clic sobre ESTAS PALABRAS EN ESTA CELDA MARKDOWN para ver el código fuente markdown."
   ]
  },
  {
   "cell_type": "raw",
   "id": "a3449766",
   "metadata": {},
   "source": [
    "# Esta es una celda raw (en bruto). Puedes presionar shift-enter, pero nada será ejecutado\n",
    "# El símbolo # no significa nada en una celda raw\n",
    "print('Hello, world!')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a34975f6",
   "metadata": {},
   "source": [
    "#### 1.1.1. Guías prácticas para Jupyter Notebooks\n",
    "\n",
    "**Cómo ejecutar rápidamente todas las celdas:**\n",
    "ir a la barra de menú de más arriba y seleccionar \"Kernel\", luego \"Restart Kernel and Run All Cells\" (Reiniciar Kernel y Ejecutar Todas las Celdas).\n",
    "\n",
    "**Cómo detener de emergencia un notebook:**\n",
    "si una celda de código está demorando mucho tiempo en ejecutarse (e.g., si se inició por accidente un proceso para obtener los datos de un catálogo entero)\n",
    "mátalo yendo a \"Kernel\" en el menú de más arriba y seleccionando \"Restart Kernel and Clear All Outputs\" (Reiniciar el Kernel y Limpiar Todas las Salidas).\n",
    "Puede igualmente tomar algunas decenas de segundos, pero detendrá el proceso y reiniciará el kernel.\n",
    "\n",
    "**El kernel** es el motor de cómputo para el notebook (la RSP usa un kernel de `python3`)\n",
    "y se puede pensar como un compilador en vivo.\n",
    "Reiniciar el kernel y limpiar todas las salidas significa que todas las variables o funciones definidas son eliminadas de la memoria,\n",
    "y todas las celdas de código vuelven al estado \"sin-ejecutar\".\n",
    "\n",
    "**Cómo ver una tabla de contenidos para este notebook:**\n",
    "hacer clic en el ícono de la lista con viñetas en la barra del menú vertical a la izquierda, y aparecerá a la izquierda una tabla de contenidos (ToC - Table of Contents) generada automáticamente.\n",
    "Hacer clic en el ícono de la carpeta de archivos que está en lo más alto de la barra de menú vertical a la izquierda, para volver a la vista de directorio.\n",
    "\n",
    "**Cómo saber qué versión de las Pipelines Científicas de LSST se está ejecutando:**\n",
    "mirar a lo largo de la barra inferior del navegador, y buscar la versión de las Pipelines Científicas de LSST que se seleccionó como \"imagen\".\n",
    "Es probablemente \"Recommended (Weekly aaaa_ss)\" -donde \"aaaa\" se refiere al año y \"ss\" a la semana- y debería corresponderse con la versión verificada que se lista en la cabecera del notebook.\n",
    "Alternativamente, descomentar de la siguiente celda de código las dos líneas y ejecutarla."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "48e9d2d7-ebec-42d9-8de0-73c1475fd539",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# ! echo $IMAGE_DESCRIPTION\n",
    "# ! eups list -s | grep lsst_distrib"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "245d2838",
   "metadata": {},
   "source": [
    "### 1.2. Importación de paquetes\n",
    "\n",
    "La mayoría de los Jupyter Notebooks comienzan cargando / importando todos los paquetes que necesitarán en la primera celda de código.\n",
    "\n",
    "No es necesario conocer en profundidad esos paquetes para completar este tutorial, pero aquí hay un poco de información básica y algunos links para seguir aprendiendo.  \n",
    "\n",
    "**numpy**: un paquete fundamental para cómputo científico con arreglos (arrays) en Python. Su documentación completa está disponible en <a href=\"https://numpy.org\">numpy.org</a>, e incluye guías rápidas para principiantes. (El paquete numpy no se utiliza en este notebook, pero se importa como ejemplo porque es un paquete de uso muy frecuente).\n",
    "\n",
    "**matplotlib**: este paquete es una biblioteca muy completa para crear visualizaciones estáticas, animadas e interactivas en Python. Toda su documentación se encuentra en <a href=\"https://matplotlib.org/\">matplotlib.org</a>. La <a href=\"https://matplotlib.org/stable/gallery/index.html\">galería de matplotlib</a> es un gran punto de partida y tiene enlaces a ejemplos.\n",
    "\n",
    " **pandas**: un paquete que permite trabajar de manera eficiente con datos tabulares en *dataframes* (marcos de datos). Se puede aprender más en la <a href=\"https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html\">documentación de Pandas</a>.\n",
    "\n",
    "**astropy**: un paquete de Python con herramientas de astronomía muy útiles. Se puede aprender más en la <a href=\"http://docs.astropy.org/en/stable/_modules/astropy/table/table.html\">documentación de astropy</a>.\n",
    "\n",
    " **lsst**: estos paquetes son todos de <a href=\"https://pipelines.lsst.io/\"> las Pipelines Científicas de LSST</a>.\n",
    " El paquete `lsst.rsp` habilita el acceso a imágenes y catálogos a través del servicio TAP (ver Sección 2);\n",
    " el paquete `lsst.daf.butler` habilita el acceso a imágenes y catálogos a través de Butler (ver Sección 3);\n",
    " el paquete `lsst.geom` posee funciones auxiliares para metadatos de imágenes y el paquete `lsst.afw.display` habilita la visualización de las imágenes (ver Sección 3)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8106313",
   "metadata": {},
   "source": [
    "Importar los paquetes utilizados en este notebook ejecutando la siguiente celda."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cddc1458",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import numpy\n",
    "import matplotlib\n",
    "import matplotlib.pyplot as plt\n",
    "import pandas\n",
    "from lsst.rsp import get_tap_service, retrieve_query\n",
    "import lsst.daf.butler as dafButler\n",
    "import lsst.geom\n",
    "import lsst.afw.display as afwDisplay"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f5ca54f6",
   "metadata": {},
   "source": [
    "#### 1.2.1. Obtener información sobre los paquetes de Python importados\n",
    "\n",
    "Mostrar las versiones de numpy y matplotlib."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0ef89712-485d-4016-93df-4b3627bc3415",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print('numpy version: ', numpy.__version__)\n",
    "print('matplotlib version: ', matplotlib.__version__)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2649d146-4903-4c47-95f3-640970b55618",
   "metadata": {},
   "source": [
    "Se puede ver una lista emergente de cualquier módulo de un paquete escribiendo el nombre del paquete, luego un punto y finalmente presionando la tecla Tab. Usar las flechas hacia arriba y abajo para desplazarse a través de la lista emergente. Esto funciona tanto si la línea de código está comentada como si no lo está. En la celda de abajo, `numpy.` está comentado porque no es una sentencia de código que se pueda ejecutar y, si no estuviera el #, esta celda fallaría en la ejecución (pruébalo -- elimina el #, presiona shift-enter y mira cómo falla)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9ff354c2",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# numpy."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a4a559b",
   "metadata": {},
   "source": [
    "Utilizar la funcion \"help\" para ver la documentación de ayuda para el paquete. Borrar el símbolo # para descomentar cualquiera de las líneas y ejecutar la siguiente celda. La documentación de ayuda puede ser demasiado larga. Re-comentar la línea reintroduciendo el #, luego re-ejecutar la celda y la salida desaparecerá."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c2d31bd7",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# help(numpy)\n",
    "# help(matplotlib)\n",
    "# help(numpy.abs)\n",
    "# help(matplotlib.pyplot)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec51ac0b",
   "metadata": {},
   "source": [
    "## 2.0. Datos de Catálogos\n",
    "\n",
    "### 2.1. Servicio de Protocolo de Acceso a Datos Tabulados (TAP)\n",
    "\n",
    "El protocolo de acceso a datos tabulados TAP (Table Access Protocol) provee un acceso estandarizado a los datos de catálogos para exploración, búsqueda y acceso. La <a href=\"http://www.ivoa.net/documents/TAP\">documentación completa de TAP</a> es provista por la Alianza Internacional de Observatorios Virtuales (IVOA --International Virtual Observatory Alliance).\n",
    "\n",
    "El servicio TAP utiliza un lenguaje de consultas similar a SQL (Structured Query Language --lenguaje de consulta estructurado) denominado ADQL (Astronomical Data Query Language --lenguaje de consulta de datos astronómicos).\n",
    "La <a href=\"http://www.ivoa.net/documents/latest/ADQL.html\">documentación para ADQL</a> incluye más información sobre sintaxis y palabras clave.\n",
    "\n",
    "> **Aviso:** no todas las funcionalidades de ADQL están soportadas por RSP para la Vista Previa de Datos 0 (DP0)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4936e520",
   "metadata": {},
   "source": [
    "Iniciar el servicio TAP."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f0a530b9",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "service = get_tap_service(\"tap\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10804bb0",
   "metadata": {},
   "source": [
    "### 2.2. Explorando tablas y columnas de catálogos con TAP\n",
    "\n",
    "Este ejemplo utiliza el catálogo *Object* de objetos de DP0.2, que contiene fuentes detectadas en imágenes coagregadas (coadded) (también llamadas imágenes apiladas --stacked--, combinadas --combined--, o *deepCoad*).\n",
    "\n",
    "Los contenidos del catálogo también se pueden explorar con el <a href=\"https://dm.lsst.org/sdm_schemas/browser/dp02.html\"> navegador de esquemas de DP0.2 </a>.\n",
    "\n",
    "Los resultados de una búsqueda usando el servicio TAP se visualizan de mejor manera usando una de estas dos funciones:<br>\n",
    "`.to_table()`: convierte los resultados en una tabla de astropy. <br>\n",
    "`.to_table().to_pandas()`: convierte a una tabla de astropy y luego a un dataframe de Pandas.\n",
    "\n",
    "> **Advertencia:** no usar el método .to_table().show_in_notebook(). Esto puede provocar problemas en el entorno de Jupyterlab de RSP que podría bloquear tu notebook indefinidamente.\n",
    "\n",
    "Los tres ejercicios opcionales de abajo enseñan diferentes maneras de explorar usando el servicio TAP. Muestran cómo usar el servicio TAP con sentencias ADQL para explorar qué catálogos existen y qué columnas contienen. Cada celda utiliza un método diferente para visualizar los resultados de la búsqueda con TAP. Eliminar todos los #, ejecutar cada celda y observar que se crean muchas salidas -- agregar el # nuevamente a cada línea, re-ejecutar la celda y la salida desaparecerá."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "beef6193",
   "metadata": {},
   "source": [
    "#### 2.2.1. Ejercicio 1\n",
    "Obtener y mostrar una lista de todos los nombres y descripciones de las tablas que están disponibles a través del servidor TAP."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "75ba75e6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# my_adql_query = \"SELECT description, table_name FROM TAP_SCHEMA.tables\"\n",
    "# results = service.search(my_adql_query)\n",
    "# results_table = results.to_table().to_pandas()\n",
    "# results_table"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "723cbe86",
   "metadata": {},
   "source": [
    "#### 2.2.2. Ejercicio 2\n",
    "Obtener y mostrar una lista de los nombres de los campos (nombres de columna) en el esquema TAP del catálogo de Objetos de DP0.2. Notar que los resultados se pueden nombrar de cualquier otra manera; aquí, se usa alternativamente 'res'."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "88711ca7",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# my_adql_query = \"SELECT * from TAP_SCHEMA.columns \"+\\\n",
    "#                 \"WHERE table_name = 'dp02_dc2_catalogs.Object'\"\n",
    "# res = service.search(my_adql_query)\n",
    "# print(res.fieldnames)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "de30cca5",
   "metadata": {},
   "source": [
    "#### 2.2.3. Ejercicio 3\n",
    "Obtener los nombres, tipos de datos, descripciones y unidades para todas las columnas en el catálogo Object. Mostrar el número de columnas."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5129c644",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# my_adql_query = \"SELECT column_name, datatype, description, unit \"+\\\n",
    "#                 \"FROM TAP_SCHEMA.columns \"+\\\n",
    "#                 \"WHERE table_name = 'dp02_dc2_catalogs.Object'\"\n",
    "# results = service.search(my_adql_query)\n",
    "# results_table = results.to_table().to_pandas()\n",
    "# print('Number of columns available in the Object catalog: ', len(results_table))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a8f5cb6e-1844-4f0f-9329-cb20f20617be",
   "metadata": {},
   "source": [
    "Mostrar todos los 991 nombres de columnas y su información. ¡Son tantas salidas! Comentar la línea en la celda y re-ejecutar la celda para hacer que todas las salidas desaparezcan."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a2142c9a-3be3-4e61-b69e-47fd25d23178",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# results_table"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2577a97a-4a96-41bb-8e29-4cae62672b3d",
   "metadata": {},
   "source": [
    "Mostrar sólo nombres y descripciones para columnas que contengan la cadena (texto) \"cModelFlux\".\n",
    "Probar otras cadenas como \"coord\", \"extendedness\", \"deblend\", o \"detect\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "40bde1ad-15cd-409c-9bcb-162052ee7890",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# my_string = 'cModelFlux'\n",
    "# for col,des in zip(results_table['column_name'],results_table['description']):\n",
    "#     if col.find(my_string) > -1:\n",
    "#         print('%-40s %-200s' % (col,des))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8ced15d7",
   "metadata": {},
   "source": [
    "### 2.3. Obteniendo Datos con TAP\n",
    "\n",
    "Algunos consejos sobre cómo hacer consultas eficientes en los catálogos de DP0.2.\n",
    "\n",
    "**Restricciones en RA, Dec producen consultas más rápidas:**\n",
    "los Servicios de Consulta de LSST (Qserv - Query Services) proveen acceso a la base de datos de catálogos del LSST.\n",
    "Los catálogos se pueden consultar utilizando el lenguaje estándar de consultas SQL con unas pocas limitaciones.\n",
    "Qserv almacena los datos de catálogos fragmentados por coordenadas (RA, Dec).\n",
    "Las sentencias de consultas ADQL que incluyen restricciones por coordenadas no requieren una búsqueda en todo el catálogo, y son generalmente más rápidas (y pueden ser mucho más rápidas) que las sentencias de consulta ADQL que sólo incluyen restricciones para otras columnas.\n",
    "\n",
    "**Obtener una pequeña muestra de filas:**\n",
    "como se mostró en la Sección 2.3.2, usar `maxrec=10` o `SELECT TOP 10` cuando se explora el conjunto de datos para obtener como resultado unas pocas filas con las que jugar (esto también puede acortar los tiempos de consulta para consultas exploratorias sin las sentencias WHERE).\n",
    "\n",
    "**Reestricción recomendada en `detect_isPrimary`:**\n",
    "cuando corresponda, se recomienda incluir `detect_isPrimary = True` en las consultas para los catálogos `Object`, `Source` y `ForcedSource`.\n",
    "Este parámetro toma el valor `True` si una fuente\n",
    "no tiene hijos,\n",
    "si está en la zona interior de una parcela coagregada (coadd patch),\n",
    "si está en la zona interior de una región coagregada (coadd tract),\n",
    "y si no se detecta en un pseudo-filtro.\n",
    "Al incluir esta restricción se eliminan duplicados (i.e., no se incluirán al mismo tiempo a padres e hijos obtenidos en la separación --deblend)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0370bb6e-6c3d-4cd2-978a-4b00fd485478",
   "metadata": {},
   "source": [
    "#### 2.3.1. Convirtiendo flujos a magnitudes\n",
    "\n",
    "Los catálogos de objetos y fuentes almacenan sólo flujos. Hay cientos de columnas relacionadas a flujos y almacenarlas también como magnitudes sería redundante y un desperdicio de espacio.\n",
    "\n",
    "Todas las unidades de flujo son nanojanskys ($nJy$). La <a href=\"https://es.wikipedia.org/wiki/Magnitud_AB\"> página de Wikipedia sobre Magnitudes AB</a>\n",
    " proporciona un recurso conciso para quienes no estén familiarizados con el uso de magnitudes AB y flujos jansky. Para convertir $nJy$ a magnitudes AB usar: $m_{AB} = -2.5log( f_{nJy}) + 31.4$.\n",
    " \n",
    "Como se muestra en la Sección 2.3.2, para agregar columnas de magnitudes después de obtener columnas de flujos, se puede hacer lo siguiente:<br>\n",
    "`results_table['r_calibMag'] = -2.50 * numpy.log10(results_table['r_calibFlux']) + 31.4`<br>\n",
    "`results_table['r_cModelMag'] = -2.50 * numpy.log10(results_table['r_cModelFlux']) + 31.4`\n",
    "\n",
    "Como se muestra en la Sección 2.3.3, para obtener columnas de flujos *como magnitudes* en una consulta ADQL, se puede hacer lo siguiente:<br>\n",
    "`scisql_nanojanskyToAbMag(g_calibFlux) as g_calibMag`,\n",
    "y las columnas de errores de magnitudes se pueden obtener con:<br>\n",
    "`scisql_nanojanskyToAbMagSigma(g_calibFlux, g_calibFluxErr) as g_calibMagErr`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5356f2e2-a369-42d2-8d46-ff155e221d7e",
   "metadata": {},
   "source": [
    "#### 2.3.2. Diez objetos de cualquier tipo\n",
    "\n",
    "Para mostrar rápidamente cómo obtener datos del catálogo Object, usar una búsqueda de cono y solicitar que se devuelvan sólo 10 registros. La Figura 2 del <a href=\"https://ui.adsabs.harvard.edu/abs/2021ApJS..253...31L/abstract\">artículo de DC2 de DESC</a>  muestra que la región del cielo cubierta por la simulación de DC2 contiene las coordenadas RA,Dec = 62,-37.\n",
    "\n",
    "Este ejemplo usa `maxrec=10` en la función `service.search()`, pero se pueden lograr los mismos resultados reemplazando `SELECT` por `SELECT TOP 10` en la consulta ADQL.\n",
    "\n",
    "> **Atención:** el catálogo Object contiene cientos de millones de filas. Las búsquedas que no especifican una región y/o un número máximo de registros pueden tomar mucho tiempo y devolver demasiadas filas para mostrar en un notebook.\n",
    "\n",
    "Obtener coordenadas y magnitudes g,r,i para diez objetos dentro de un radio de 0.5 grados de 62,-37."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8fa7d255-584b-4be5-94a3-2b901147c4c3",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "use_center_coords = \"62, -37\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c23a25b7-e861-4d74-a07d-cde752b10483",
   "metadata": {},
   "source": [
    "Abajo, `SELECT TOP 10` se utiliza en la sentencia de consulta para limitar a 10 objetos los datos que se devuelven.\n",
    "Una alternativa es usar la palabra clave `maxrec` en la sentencia de búsqueda: `service.search(my_adql_query, maxrec=10)`.\n",
    "Sin embargo, usar `maxrec` puede devolver un `DALOverflowWarning` que alerta que se han devuelto resultados parciales (aún cuando se deseaban resultados parciales)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "355a5cb2",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "my_adql_query = \"SELECT TOP 10 \"+ \\\n",
    "                \"coord_ra, coord_dec, detect_isPrimary, \" + \\\n",
    "                \"r_calibFlux, r_cModelFlux, r_extendedness \" + \\\n",
    "                \"FROM dp02_dc2_catalogs.Object \" + \\\n",
    "                \"WHERE CONTAINS(POINT('ICRS', coord_ra, coord_dec), \" + \\\n",
    "                \"CIRCLE('ICRS', \" + use_center_coords + \", 0.01)) = 1 \"\n",
    "\n",
    "results = service.search(my_adql_query)\n",
    "results_table = results.to_table()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "eb72874d-8c81-44a4-a1f8-c37b117f734e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "results_table['r_calibMag'] = -2.50 * numpy.log10(results_table['r_calibFlux']) + 31.4\n",
    "results_table['r_cModelMag'] = -2.50 * numpy.log10(results_table['r_cModelFlux']) + 31.4"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2a863831-690c-4cb9-b48b-2e49256863b6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "results_table"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1f5b222",
   "metadata": {},
   "source": [
    "#### 2.3.3 Diez mil objetos puntuales\n",
    "\n",
    "Además de la búsqueda de cono, fijar restricciones de consulta para que detect_isPrimary tenga valor True (esto no devolverá fuentes \"hijas\" producto de la separación --deblending), que el flujo calibrado sea mayor que 360 nJy (aproximadamente magnitud 25) y que los parámetros de extensión sean 0 (fuentes puntuales).\n",
    "\n",
    "Obtener las magnitudes en las bandas g, r e i para 10000 objetos que tienen alta probabilidad de ser estrellas."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e9989da7",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "results = service.search(\"SELECT TOP 10000 \"\n",
    "                         \"coord_ra, coord_dec, \"\n",
    "                         \"scisql_nanojanskyToAbMag(g_calibFlux) as g_calibMag, \"\n",
    "                         \"scisql_nanojanskyToAbMag(r_calibFlux) as r_calibMag, \"\n",
    "                         \"scisql_nanojanskyToAbMag(i_calibFlux) as i_calibMag, \"\n",
    "                         \"scisql_nanojanskyToAbMagSigma(g_calibFlux, g_calibFluxErr) as g_calibMagErr \"\n",
    "                         \"FROM dp02_dc2_catalogs.Object \"\n",
    "                         \"WHERE CONTAINS(POINT('ICRS', coord_ra, coord_dec), \"\n",
    "                         \"CIRCLE('ICRS', \"+use_center_coords+\", 1.0)) = 1 \"\n",
    "                         \"AND detect_isPrimary = 1 \"\n",
    "                         \"AND g_calibFlux > 360 \"\n",
    "                         \"AND r_calibFlux > 360 \"\n",
    "                         \"AND i_calibFlux > 360 \"\n",
    "                         \"AND g_extendedness = 0 \"\n",
    "                         \"AND r_extendedness = 0 \"\n",
    "                         \"AND i_extendedness = 0\")\n",
    "\n",
    "results_table = results.to_table()\n",
    "print(len(results_table))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d293260a-e7d3-4fdb-9a37-716f612c6220",
   "metadata": {},
   "source": [
    "La muestra de la tabla se truncará automáticamente."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "13eeaa07-ca19-4b1e-983f-3e29908adbc2",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "results_table"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "41b68c33",
   "metadata": {},
   "source": [
    "Guardar los resultados en un dataframe de pandas para tener acceso fácil al contenido. Estos datos son utilizados para crear un diagrama color-magnitud en la Sección 2.4."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "798b0809",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "data = results_table.to_pandas()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e1dc71c",
   "metadata": {},
   "source": [
    "Para quienes no estén familiarizados con Pandas, aquí hay algunas líneas de código opcionales que muestran cómo imprimir los nombres de las columnas, la información de la columna 'ra' o los valores de la columna 'ra'. Descomentar (eliminar #) y ejecutar la celda para ver la salida de la demostración."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fd0f247a",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# data.columns"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a3dd33a7",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# data['coord_ra']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a72e6ecd",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# data['coord_ra'].values"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd5b98bc",
   "metadata": {},
   "source": [
    "### 2.4 Hacer un diagrama color-magnitud\n",
    "\n",
    "Usar la función *plot* para graficar del paquete matplotlib.pyplot (que fue importado como plt). Los parámetros de la función *plot* se describen en su totalidad en <a href=\"https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.plot.html#matplotlib.pyplot.plot\"> este sitio web de matplotlib</a>, pero en resumen son: valores de x, valores de y, forma del símbolo ('o' es círculo), tamaño de marcador (marker size, ms) y transparencia del marcador (alpha)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "98b2c106",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "plt.plot(data['r_calibMag'].values - data['i_calibMag'].values,\n",
    "         data['g_calibMag'].values, 'o', ms=2, alpha=0.2)\n",
    "\n",
    "plt.xlabel('mag_r - mag_i', fontsize=16)\n",
    "plt.ylabel('mag_g', fontsize=16)\n",
    "plt.xticks(fontsize=16)\n",
    "plt.yticks(fontsize=16)\n",
    "\n",
    "plt.xlim([-0.5, 2.0])\n",
    "plt.ylim([25.5, 16.5])\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c2c40f7",
   "metadata": {},
   "source": [
    "Este gráfico genera muchos interrogantes, como por ejemplo \"¿Por qué los colores están concentrados discretamente?\" y \"¿Son todas esas realmente estrellas?\". Las respuestas exceden el ámbito de este notebook y son dejadas como temas potenciales de análisis científico que pueden abordarse con el conjunto de datos DC2."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d7c27a75-8928-4ead-a958-c7142b0a9a6e",
   "metadata": {},
   "source": [
    "### 2.5 Opcional: graficar magnitud versus error de magnitud\n",
    "\n",
    "Para ilustrar tanto las magnitudes como los errores de las magnitudes obtenidos mediante la consulta TAP de más arriba,\n",
    "aquí hay una opción para graficar el error de la magnitud como función de la magnitud."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d9503291-d974-471a-9d53-fd880f57e6fd",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# plt.plot(data['g_calibMag'].values, data['g_calibMagErr'].values, 'o', ms=2, alpha=0.2)\n",
    "# plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56baaa33",
   "metadata": {},
   "source": [
    "## 3.0. Datos de Imágenes\n",
    "\n",
    "Los dos tipos de imágenes más comunes con los que van a interactuar quienes tengan acceso a DP0 son calexps y deepCoadds.\n",
    "\n",
    "**calexp:** una única imagen en un único filtro.\n",
    "\n",
    "**deepCoadd:** una combinación de imágenes individuales apiladas en profundidad o coagregadas.\n",
    "\n",
    "Las Pipelines Científicas de LSST (Science Pipelines) procesan y almacenan imágenes en regiones (tracts) y parcelas (patches).\n",
    "\n",
    "**región (tract)**: una porción del cielo dentro de la teselación del cielo completo (mapa del cielo) de LSST (LSST all-sky tessellation); dividido en parcelas.\n",
    "\n",
    "**parcela (patch)**: una subregión cuadrilátera de una región, de un tamaño que puede almacenarse fácilmente en la memoria de una computadora de escritorio.\n",
    "\n",
    "Para obtener y visualizar una imagen en las cordenadas deseadas, se debe especificar el tipo de imagen, la región (tract) y la parcela (patch)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6758b295",
   "metadata": {},
   "source": [
    "### 3.1. Crear una instancia de Butler\n",
    "\n",
    "Butler --que en inglés significa mayordomo-- (<a href=\"https://pipelines.lsst.io/modules/lsst.daf.butler/index.html\">documentación</a>) es un paquete de software de las Pipelines Científicas de LSST que sirve para obtener datos de LSST sin necesidad de conocer su ubicación o formato. Además Butler también puede ser utilizado para explorar y descubrir qué datos existen. Otros tutoriales muestran la funcionalidad completa de Butler."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b640a69",
   "metadata": {},
   "source": [
    "Crear una instancia de Butler utilizando la siguiente configuración y colección de DP0.2.\n",
    "Devolverá información sobre las credenciales encontradas."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2122a1fb",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "butler = dafButler.Butler('dp02', collections='2.2i/runs/DP0.2')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7f25b7df-a901-4a69-81d0-c630cec28539",
   "metadata": {},
   "source": [
    "### 3.2. Identificar y obtener una imagen deepCoadd"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b0519417",
   "metadata": {},
   "source": [
    "Hay un cúmulo de galaxias DC2 que se ve genial en RA = 03h42m59.0s, Dec = -32d16m09s (en grados, 55.745834, -32.269167).\n",
    "\n",
    "Usar lsst.geom para definir un SpherePoint --punto en la esfera-- para las coordenadas del cúmulo (<a href=\"https://pipelines.lsst.io/modules/lsst.geom/index.html\">documentación de lsst.geom</a>)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "56ea8e01",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "my_ra_deg = 55.745834\n",
    "my_dec_deg = -32.269167\n",
    "\n",
    "my_spherePoint = lsst.geom.SpherePoint(my_ra_deg*lsst.geom.degrees,\n",
    "                                       my_dec_deg*lsst.geom.degrees)\n",
    "print(my_spherePoint)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "789fb4ff",
   "metadata": {},
   "source": [
    "Obtener el mapa del cielo de DC2 desde Butler y usarlo para identificar la región y parcela para las coordenadas del cúmulo (<a href=\"http://doxygen.lsst.codes/stack/doxygen/x_masterDoxyDoc/skymap.html\">documentación de skymap</a>)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1796f237",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "skymap = butler.get('skyMap')\n",
    "\n",
    "tract = skymap.findTract(my_spherePoint)\n",
    "patch = tract.findPatch(my_spherePoint)\n",
    "\n",
    "my_tract = tract.tract_id\n",
    "my_patch = patch.getSequentialIndex()\n",
    "\n",
    "print('my_tract: ', my_tract)\n",
    "print('my_patch: ', my_patch)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "63c0e237",
   "metadata": {},
   "source": [
    "Utilizar Butler para obtener la imagen deepCoadd en la banda i para la región y parcela."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "460e1df6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "dataId = {'band': 'i', 'tract': my_tract, 'patch': my_patch}\n",
    "my_deepCoadd = butler.get('deepCoadd', dataId=dataId)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d4e2c4d1",
   "metadata": {},
   "source": [
    "### 3.3. Visualizar la imagen con afwDisplay\n",
    "\n",
    "Los datos de imágenes obtenidos con Butler se pueden visualizar de diferentes maneras. Una opción sencilla es utilizar el paquete afwDisplay de las Pipelines Científicas de LSST. Hay cierta <a href=\"https://pipelines.lsst.io/modules/lsst.afw.display/index.html\">documentación de afwDisplay</a> disponible y otros tutoriales de DP0 entran en más detalle acerca de todas las opciones de visualización (e.g., superponer datos de máscaras para mostrar píxeles malos).\n",
    "\n",
    "Establecer el backend de afwDisplay para matplotlib."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d4ebe015",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "afwDisplay.setDefaultBackend('matplotlib')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f1ab1a8",
   "metadata": {},
   "source": [
    "Usar afwDisplay para mostrar los datos obtenidos de la imagen.\n",
    "\n",
    "La siguiente celda de código crea una figura matplotlib.pyplot; define una instancia de `lsst.afw.display.Display` como  `afw_display`; establece la escala para las intensidades o tonos de los píxeles (pixel shading); visualiza la imagen usando `mtv`; y activa las etiquetas para los ejes x, y (coordenadas del píxel)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dd46970e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "fig = plt.figure(figsize=(10, 8))\n",
    "afw_display = afwDisplay.Display(1)\n",
    "afw_display.scale('asinh', 'zscale')\n",
    "afw_display.mtv(my_deepCoadd.image)\n",
    "plt.gca().axis('on')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2a318232",
   "metadata": {},
   "source": [
    "Para conocer más sobre el paquete afwDisplay  y sus funcionalidades, usar la función de ayuda `help`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4e9a1ee0",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# help(afw_display.scale)\n",
    "# help(afw_display.mtv)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "LSST",
   "language": "python",
   "name": "lsst"
  },
  "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.11.9"
  },
  "toc-autonumbering": false
 },
 "nbformat": 4,
 "nbformat_minor": 5
}