docs + readme

Author: ppp-one

.gitignore

@@ -1,6 +1,7 @@
 .DS_Store
 temp/
 .vscode/
+*.psd
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

README.md

@@ -1,2 +1,48 @@
 # mphot
- A versatile Python package to model photometry for ground-based astronomy
+*mphot* is a fast Python package to model photometry data from the ground or space.
+
+![example plots](examples/example-plots.png)
+
+
+## How it works
+
+Simply put, 
+- it combines user submitted [telescope * filter * camera qe] efficiencies with generic stellar models and sky transmission/radiance models (for Paranal, 2400m) to generate integrable grids of stellar fluxes and sky radiances.
+
+- Then, *mphot* uses the grids to interpolate between different
+    - atmospheric parameters (PWV, airmass)
+    - target star parameters (effective temperature + distance)
+
+- using user submitted
+    - telescope/site parameters (primary and secondary diameters, site seeing)
+    - camera parameters (plate scale, dark current, read noise, well depth, target well fill, read time)
+    
+- to calculate ideal exposure time and expected precision for a given observation.
+
+Please see the [examples](https://github.com/ppp-one/mphot/tree/main/examples) for more details on how to use *mphot*. For further details on the models used, please see [https://doi.org/10.1117/12.3018320](https://doi.org/10.1117/12.3018320).
+
+Note, it uses stellar parameters from "[A Modern Mean Dwarf Stellar Color and Effective Temperature Sequence](https://www.pas.rochester.edu/~emamajek/EEM_dwarf_UBVIJHK_colors_Teff.txt)". Temperatures between 1278 K to 3042 K are calibrated for the [SPECULOOS target list](https://doi.org/10.1051/0004-6361/202038827) and [2MASS](https://irsa.ipac.caltech.edu/Missions/2mass.html) (see Figure 4.7 in "[Optimised ground-based near-infrared instrumentation for robotic exoplanet transit surveys](https://doi.org/10.17863/CAM.96904)").
+
+<!-- For further details, please see the [documentation](https://ppp-one.github.io/mphot/). -->
+
+
+## Installation
+
+You can install *mphot* in a Python (`>=3.11`) environment with
+
+```bash
+pip install mphot
+```
+
+or from a local clone
+
+```bash
+git clone https://github.com/ppp-one/mphot
+pip install -e mphot
+```
+
+You can test the package has been properly installed with
+
+```bash
+python -c "import mphot"
+```

docs/source/conf.py

@@ -28,6 +28,12 @@
     "myst_parser",
 ]
 
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".txt": "markdown",
+    ".md": "markdown",
+}
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 

docs/source/index.md

@@ -0,0 +1,8 @@
+```{include} ../../README.md
+:relative-docs: ../../
+:relative-images:
+```
+
+## Contents
+```{toctree} mphot
+```

docs/source/index.rst

@@ -33,7 +33,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 41,
+   "execution_count": 3,
    "id": "ba5f2fbd",
    "metadata": {},
    "outputs": [
@@ -43,7 +43,7 @@
        "<Axes: title={'center': 'speculoos_Andor_iKon-L-936_-60_I+z'}, xlabel='Wavelength (microns)', ylabel='System Response'>"
       ]
      },
-     "execution_count": 41,
+     "execution_count": 3,
      "metadata": {},
      "output_type": "execute_result"
     },
@@ -64,7 +64,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 42,
+   "execution_count": 4,
    "id": "0feee513-9586-40b8-81e3-d0a05723a2d0",
    "metadata": {},
    "outputs": [],
@@ -99,17 +99,10 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 43,
+   "execution_count": 13,
    "id": "43ff22f5-b58d-44c4-ae15-2bcf5703ff07",
    "metadata": {},
    "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Progress: [####################] 100.0%\n"
-     ]
-    },
     {
      "data": {
       "text/html": [
@@ -244,7 +237,7 @@
        "      <td>394</td>\n",
        "    </tr>\n",
        "    <tr>\n",
-       "      <th>npix</th>\n",
+       "      <th>pixels in aperture [pix]</th>\n",
        "      <td>421</td>\n",
        "    </tr>\n",
        "    <tr>\n",
@@ -304,7 +297,7 @@
        "      <td>6.40e+4</td>\n",
        "    </tr>\n",
        "    <tr>\n",
-       "      <th>well_fill</th>\n",
+       "      <th>peak well_fill</th>\n",
        "      <td>0.700</td>\n",
        "    </tr>\n",
        "    <tr>\n",
@@ -316,7 +309,7 @@
        "      <td>10.5</td>\n",
        "    </tr>\n",
        "    <tr>\n",
-       "      <th>nImages</th>\n",
+       "      <th>binned images</th>\n",
        "      <td>7.84</td>\n",
        "    </tr>\n",
        "  </tbody>\n",
@@ -330,7 +323,7 @@
        "N_star [e/s]                                             1.16e+4\n",
        "star_flux [e/m2/s]                                       1.77e+4\n",
        "scn [e_rms]                                                  394\n",
-       "npix                                                         421\n",
+       "pixels in aperture [pix]                                     421\n",
        "ap_radius [pix]                                             11.6\n",
        "N_sky [e/pix/s]                                             13.5\n",
        "sky_radiance [e/m2/arcsec2/s]                                152\n",
@@ -345,10 +338,10 @@
        "r1 [m]                                                     0.140\n",
        "t [s]                                                       66.1\n",
        "well_depth [e/pix]                                       6.40e+4\n",
-       "well_fill                                                  0.700\n",
+       "peak well_fill                                             0.700\n",
        "binning [mins]                                              10.0\n",
        "read_time [s]                                               10.5\n",
-       "nImages                                                     7.84"
+       "binned images                                               7.84"
       ]
      },
      "metadata": {},

examples/Basic use.ipynb

@@ -662,6 +662,7 @@ def get_precision(
     SPCcorrection: bool = True,
     N_sky: float | None = None,
     N_star: float | None = None,
+    scn: float | None = None,
     exp_time: float | None = None,
     extended: bool = False,
 ) -> dict:
@@ -711,6 +712,9 @@ def get_precision(
         N_star (float, optional):
             Number of star counts, calculated if None. Default is None.
 
+        scn (float, optional):
+            Scintillation noise, calculated if None. Default is None.
+
         exp_time (float, optional):
             Exposure time in seconds, calculated if None. Default is None.
 
@@ -896,7 +900,8 @@ def get_precision(
 
     npix = np.pi * ap**2
 
-    scn = scintillation_noise(r0, t, N_star, airmass)
+    if scn is None:
+        scn = scintillation_noise(r0, t, N_star, airmass)
 
     precision = np.sqrt(
         N_star * t + scn**2 + npix * (N_sky * t + N_dc * t + N_rn**2)
@@ -1112,7 +1117,7 @@ def update_progress(progress: float | int) -> None:
     print(text)
 
 
-def to_precision(x: float, p: int = 3) -> str:
+def display_number(x: float, p: int = 3) -> str:
     """
     Convert a number to a string with the given precision.
 
@@ -1124,11 +1129,11 @@ def to_precision(x: float, p: int = 3) -> str:
         str: The number represented as a string with the specified precision.
 
     Examples:
-    >>> to_precision(123.456, 4)
+    >>> display_number(123.456, 4)
     '123.5'
-    >>> to_precision(0.00123456, 2)
+    >>> display_number(0.00123456, 2)
     '0.0012'
-    >>> to_precision(123456, 2)
+    >>> display_number(123456, 2)
     '1.2e+05'
     """
 
@@ -1214,7 +1219,7 @@ def display_results(r1: tuple, r2: tuple = None) -> None:
             This function displays the results using pandas DataFrames and does not return any value.
     """
 
-    pd.set_option("display.float_format", to_precision)
+    pd.set_option("display.float_format", display_number)
 
     image_precision1, binned_precision1, components1 = r1
 
@@ -1301,11 +1306,11 @@ def display_results(r1: tuple, r2: tuple = None) -> None:
 
         for k, v in components1.items():
             if not isinstance(v, (str, bool)):
-                components1[k] = to_precision(v)
+                components1[k] = display_number(v)
 
         for k, v in components2.items():
             if not isinstance(v, (str, bool)):
-                components2[k] = to_precision(v)
+                components2[k] = display_number(v)
 
         values = np.c_[list(components1.values()), list(components2.values())]
         display(pd.DataFrame(values, index=components1.keys(), columns=columns))
@@ -1335,7 +1340,7 @@ def display_results(r1: tuple, r2: tuple = None) -> None:
 
         for k, v in components1.items():
             if (type(v) != str) and (type(v) != bool):
-                components1[k] = to_precision(v)
+                components1[k] = display_number(v)
 
         values = np.c_[list(components1.values())]
         display(pd.DataFrame(values, index=components1.keys(), columns=columns))