Added the contrast_to_mass method to ReadIsochrone for converting con…

…trast values in a given filter into masses

docs/overview.rst

@@ -28,7 +28,7 @@ The following data and models are currently supported:
 - `DRIFT-PHOENIX <http://svo2.cab.inta-csic.es/theory/newov2/index.php?models=drift>`_
 - `Exo-REM <https://ui.adsabs.harvard.edu/abs/2018ApJ...854..172C/abstract>`_
 - `Morley et al. (2012) T/Y dwarf spectra <https://ui.adsabs.harvard.edu/abs/2012ApJ...756..172M/abstract>`_
-- `petitCODE <http://www.mpia.de/~molliere/#petitcode>`_
+- `petitCODE <https://www2.mpia-hd.mpg.de/~molliere/grids/>`_
 - `petitRADTRANS <https://petitradtrans.readthedocs.io>`_
 - `Saumon & Marley (2008) <https://ui.adsabs.harvard.edu/abs/2008ApJ...689.1327S/abstract>`_
 - `Sonora Bobcat <https://zenodo.org/record/5063476>`_

docs/tutorials/read_isochrone.ipynb

@@ -63,7 +63,7 @@
      "output_type": "stream",
      "text": [
       "==============\n",
-      "species v0.7.2\n",
+      "species v0.7.3\n",
       "==============\n",
       "Working folder: /Users/tomasstolker/applications/species/docs/tutorials\n",
       "Creating species_config.ini... [DONE]\n",
@@ -79,7 +79,7 @@
     {
      "data": {
       "text/plain": [
-       "<species.core.init.SpeciesInit at 0x149e28310>"
+       "<species.core.init.SpeciesInit at 0x110b15a10>"
       ]
      },
      "execution_count": 2,
@@ -455,7 +455,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 10,
    "id": "2e93e5de",
    "metadata": {},
    "outputs": [],
@@ -476,7 +476,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 11,
    "id": "606c4fde",
    "metadata": {},
    "outputs": [
@@ -590,7 +590,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": 12,
    "id": "c944ed49",
    "metadata": {},
    "outputs": [
@@ -605,7 +605,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "/Users/tomasstolker/applications/species/species/read/read_model.py:145: UserWarning: The 'atmo-ceq' model spectra are not present in the database. Will try to add the model grid. If this does not work (e.g. currently without an internet connection) then please use the 'add_model' method of 'Database' to add the grid of spectra yourself.\n",
+      "/Users/tomasstolker/applications/species/species/read/read_model.py:145: UserWarning: The 'atmo-ceq' model spectra are not present in the database. Will try to add the model grid. If this does not work (e.g. currently without an internet connection) then please use the 'add_model' method of 'Database' to add the grid of spectra at a later moment.\n",
       "  warnings.warn(\n",
       "Downloading data from 'https://home.strw.leidenuniv.nl/~stolker/species/atmo-ceq.tgz' to file '/Users/tomasstolker/applications/species/docs/tutorials/data/atmo-ceq.tgz'.\n"
      ]
@@ -621,7 +621,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "100%|████████████████████████████████████████| 476M/476M [00:00<00:00, 147GB/s]\n",
+      "100%|████████████████████████████████████████| 476M/476M [00:00<00:00, 229GB/s]\n",
       "SHA256 hash of downloaded file: bab2dc6920d9358bd0a554b9d5554b09e5885fec2daf91ee11ccf340c310fcbf\n",
       "Use this value as the 'known_hash' argument of 'pooch.retrieve' to ensure that the file hasn't changed if it is downloaded again in the future.\n"
      ]
@@ -656,7 +656,7 @@
      "output_type": "stream",
      "text": [
       "Downloading data from 'https://archive.stsci.edu/hlsps/reference-atlases/cdbs/current_calspec/alpha_lyr_stis_011.fits' to file '/Users/tomasstolker/applications/species/docs/tutorials/data/alpha_lyr_stis_011.fits'.\n",
-      "100%|████████████████████████████████████████| 288k/288k [00:00<00:00, 161MB/s]"
+      "100%|████████████████████████████████████████| 288k/288k [00:00<00:00, 105MB/s]"
      ]
     },
     {
@@ -690,7 +690,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 13,
    "id": "0c32a006",
    "metadata": {},
    "outputs": [
@@ -731,7 +731,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 18,
+   "execution_count": 14,
    "id": "83a86b99",
    "metadata": {},
    "outputs": [],
@@ -752,7 +752,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": 15,
    "id": "be9a4029",
    "metadata": {},
    "outputs": [
@@ -846,7 +846,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 21,
+   "execution_count": 16,
    "id": "0ca8aa3b",
    "metadata": {},
    "outputs": [
@@ -876,7 +876,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 22,
+   "execution_count": 17,
    "id": "b7959461",
    "metadata": {},
    "outputs": [
@@ -1080,6 +1080,125 @@
    "source": [
     "fig"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c43b9f35-3b87-4971-b62e-0d4689d2785e",
+   "metadata": {},
+   "source": [
+    "## Converting contrast into mass"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5c999f15-785d-43cc-b31c-d24f937d9b2a",
+   "metadata": {},
+   "source": [
+    "The [contrast_to_mass](https://species.readthedocs.io/en/latest/species.read.html#species.read.read_isochrone.ReadIsochrone.contrast_to_mass) method of [ReadIsochrone](https://species.readthedocs.io/en/latest/species.read.html#species.read.read_isochrone.ReadIsochrone) can be used to convert a list or array with companion-to-star contrast values into masses of the companion. This feature can be useful for converting a *contrast curve* (i.e. detection limits for point sources) into mass limits as function of separation from the star. Or, to estimate the mass of a companion from a measured brightness contrast with its star."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a0bc0df6-8795-4c9c-ac92-05f3b9379cb2",
+   "metadata": {},
+   "source": [
+    "We can either select one of the filters with pre-calculated magnitudes that come with the isochrone grid (i.e., those returned by [get_filters](https://species.readthedocs.io/en/latest/species.read.html#species.read.read_isochrone.ReadIsochrone.get_filters)) or any of the filters from the [SVO Filter Profile Service](http://svo2.cab.inta-csic.es/svo/theory/fps/)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ccf4f4f1-37d8-4e45-b799-1143f94fcb46",
+   "metadata": {},
+   "source": [
+    "For example, let's select the ``MKO_H`` filter that is include with the ATMO grid and interpolate the masses for a list of contrast values that are provided as magnitudes."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 18,
+   "id": "cf2e2a56-b81b-44bd-803a-d0c0badefe1c",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The 'MKO_H' filter is found in the list of available filters from the isochrone data of 'atmo-ceq'.\n",
+      "The requested contrast values will be directly interpolated from the grid with pre-calculated magnitudes.\n",
+      "[12.18523169  6.5719161   3.0361701 ]\n"
+     ]
+    }
+   ],
+   "source": [
+    "masses = read_iso.contrast_to_mass(age=20.,\n",
+    "                                   distance=50.,\n",
+    "                                   filter_name='MKO_H',\n",
+    "                                   star_mag=10.,\n",
+    "                                   contrast=[5.0, 7.5, 10.],\n",
+    "                                   use_mag=True)\n",
+    "print(masses)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3c0b501f-c4c1-4e55-a35f-d8ecd7451400",
+   "metadata": {},
+   "source": [
+    "Alternatively, we can select a filter from the SVO Filter Profile Service. In this case, the function will use the associated model spectra for calculating and interpolating the synthetic photometry. In this example we will provide the contrast values as ratios instead of magnitudes, so we set ``use_mag=False``."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 19,
+   "id": "83877efb-0a3d-4cdc-a29f-6b18c29f0872",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The 'JWST/NIRCam.F162M' filter is not found in the list of available filters from the isochrone data of 'atmo-ceq'.\n",
+      "It will be tried to download the filter profile (if needed) and to use the associated atmospheric model spectra for calculating synthetic photometry.\n",
+      "Adding filter: JWST/NIRCam.F162M... [DONE]\n",
+      "[11.68030143  6.2010683   2.81440063]\n"
+     ]
+    },
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/Users/tomasstolker/applications/species/species/read/read_model.py:1606: UserWarning: The set of model parameters {'teff': 3001.357148379523, 'logg': 4.455553724453863, 'radius': 2.526381394429854, 'distance': 50.0} is outside the grid range {'teff': (200.0, 3000.0), 'logg': (2.5, 5.5)} so returning a NaN.\n",
+      "  warnings.warn(\n",
+      "/Users/tomasstolker/applications/species/species/read/read_model.py:1606: UserWarning: The set of model parameters {'teff': 3006.482388036101, 'logg': 4.4562069114763485, 'radius': 2.5424416720662784, 'distance': 50.0} is outside the grid range {'teff': (200.0, 3000.0), 'logg': (2.5, 5.5)} so returning a NaN.\n",
+      "  warnings.warn(\n",
+      "/Users/tomasstolker/applications/species/species/read/read_model.py:1606: UserWarning: The set of model parameters {'teff': 3011.408951792053, 'logg': 4.456811598156431, 'radius': 2.558493215446333, 'distance': 50.0} is outside the grid range {'teff': (200.0, 3000.0), 'logg': (2.5, 5.5)} so returning a NaN.\n",
+      "  warnings.warn(\n",
+      "/Users/tomasstolker/applications/species/species/read/read_model.py:1606: UserWarning: The set of model parameters {'teff': 3016.267586113234, 'logg': 4.457442944709719, 'radius': 2.5743185127516264, 'distance': 50.0} is outside the grid range {'teff': (200.0, 3000.0), 'logg': (2.5, 5.5)} so returning a NaN.\n",
+      "  warnings.warn(\n",
+      "/Users/tomasstolker/applications/species/species/read/read_model.py:1606: UserWarning: The set of model parameters {'teff': 3021.073033921284, 'logg': 4.458036630627344, 'radius': 2.5901106044291575, 'distance': 50.0} is outside the grid range {'teff': (200.0, 3000.0), 'logg': (2.5, 5.5)} so returning a NaN.\n",
+      "  warnings.warn(\n",
+      "/Users/tomasstolker/applications/species/species/read/read_model.py:1606: UserWarning: The set of model parameters {'teff': 3025.8044035429903, 'logg': 4.45866077561258, 'radius': 2.6056736019935696, 'distance': 50.0} is outside the grid range {'teff': (200.0, 3000.0), 'logg': (2.5, 5.5)} so returning a NaN.\n",
+      "  warnings.warn(\n"
+     ]
+    }
+   ],
+   "source": [
+    "masses = read_iso.contrast_to_mass(age=20.,\n",
+    "                                   distance=50.,\n",
+    "                                   filter_name='JWST/NIRCam.F162M',\n",
+    "                                   star_mag=10.,\n",
+    "                                   contrast=[1e-2, 1e-3, 1e-4],\n",
+    "                                   use_mag=False)\n",
+    "print(masses)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8729edb9-9e60-4457-9a83-b1716917490f",
+   "metadata": {},
+   "source": [
+    "Several warnings appeared because some of the effective temperatures from the ischrone data are outside the available range of the associated atmospheric model. Those magnitudes are set to NaN such that converting any contrast values into masses for objects in the $\\sim$3000 K regime will not be possible. Any contrast values in that regime will be returned as NaN as well, which is not the case in this example."
+   ]
   }
  ],
  "metadata": {

species/data/model_data.json

@@ -214,7 +214,7 @@
     },
     "petitcode-linder2019-clear": {
         "parameters": ["teff", "logg", "feh"],
-        "name": "petitCODE (Linder et al. 2019)",
+        "name": "petitCODE clear (Linder et al. 2019)",
         "file size": "225 MB",
         "wavelength range": [0.1, 250],
         "resolution": 1000,
@@ -224,7 +224,7 @@
     },
     "petitcode-linder2019-cloudy": {
         "parameters": ["teff", "logg", "feh", "fsed"],
-        "name": "petitCODE hot cloudy",
+        "name": "petitCODE cloudy (Linder et al. 2019)",
         "file size": "1.4 GB",
         "wavelength range": [0.1, 250],
         "resolution": 1000,

species/plot/plot_comparison.py

@@ -530,6 +530,7 @@ def plot_grid_statistic(
     h5_file = h5py.File(db_path, "r")
 
     dset = h5_file[f"results/comparison/{tag}/goodness_of_fit"]
+    goodness_fit = np.array(dset)
 
     n_param = dset.attrs["n_param"]
     parallax = dset.attrs["parallax"]
@@ -552,8 +553,6 @@ def plot_grid_statistic(
     for item in read_obj.get_spectrum().values():
         n_wavel += item[0].shape[0]
 
-    goodness_fit = np.array(dset)
-
     model_param = []
     coord_points = []
 
@@ -702,13 +701,18 @@ def plot_grid_statistic(
                 goodness_fit = np.nanmin(goodness_fit, axis=tuple(ax_list))
 
                 extra_map = np.zeros(goodness_fit.shape[:2])
+
                 for i in range(goodness_fit.shape[0]):
                     for j in range(goodness_fit.shape[1]):
                         # Get the indices in the goodness_full array
                         # for the values from the collapsed (2D)
                         # goodness_fit array
                         min_idx = np.argwhere(goodness_fit[i, j] == goodness_full)
 
+                        if len(min_idx) == 0:
+                            extra_map[i, j] = np.nan
+                            continue
+
                         if len(min_idx) > 1:
                             warnings.warn(
                                 f"Found {len(min_idx)} positions in the "