Merge branch 'feature/99_sphinx' into develop #100

.github/workflows/sphinx-build.yml

@@ -0,0 +1,38 @@
+name: "Sphinx Docs Check"
+on:
+  push:
+    paths:
+    - 'docs/**'
+    - 'Metallicity_Stack_Commons/**'
+  pull_request:
+    paths:
+    - 'docs/**'
+    - 'Metallicity_Stack_Commons/**'
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.8']
+
+    steps:
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Checkout MSC
+      uses: actions/checkout@v2
+    - name: Checkout chun_codes
+      uses: actions/checkout@v2
+      with:
+        repository: astrochun/chun_codes
+        path: chun_codes
+    - name: Install chun_codes
+      run: |
+        python setup.py install
+      working-directory: chun_codes
+    - name: Sphinx build
+      uses: ammaraskar/sphinx-action@master
+      with:
+        docs-folder: "docs/"

Metallicity_Stack_Commons/__init__.py

@@ -1,3 +1,6 @@
+from logging import Logger
+from typing import Union
+
 from chun_codes.cardelli import cardelli
 import astropy.units as u
 from datetime import date
@@ -51,22 +54,20 @@
 k_dict   = dict(zip(line_name, k_values))
 
 
-def exclude_outliers(objno, verbose=False, log=None):
+def exclude_outliers(objno: Union[list, np.ndarray], verbose: bool = False,
+                     log: Logger = log_stdout()) -> np.ndarray:
     """
     Exclude spectra that are identified as outliers.
 
     Generally this is because the spectra have very high S/N on the continuum.
 
-    :param objno: list or numpy array of eight-digit identifier
-    :param verbose: bool to write verbose message to stdout. Default: file only
-    :param log: LogClass or logging object
+    :param objno: Array of eight-digit identifier
+    :param verbose: Write verbose message to stdout. Default: file only
+    :param log: logging.Logger object
 
-    :return flag: numpy array of zeros and ones
+    :return: Array of zeros (not flagged) and ones (flagged
     """
 
-    if log is None:
-        log = log_stdout()
-
     log_verbose(log, "starting ...", verbose=verbose)
 
     flag = np.zeros(len(objno), dtype=int)
@@ -81,31 +82,29 @@ def exclude_outliers(objno, verbose=False, log=None):
     return flag
 
 
-def dir_date(folder_name, path_init='', year=False, verbose=False, log=None):
+def dir_date(folder_name: str, path_init: str = '', year: bool = False,
+             verbose: bool = False, log: Logger = log_stdout()) \
+        -> str:
     """
-    Purpose:
-      This function finds and returns the path to a directory named after the
-      current date (MMDDYYYY). If the directory doesn't exist yet, it creates
-      a new directory named after the current date in the provided folder_name
-      directory.
+    This function finds and returns the path to a directory named after the
+    current date (MMDDYYYY). If the directory doesn't exist yet, it creates
+    a new directory named after the current date in the provided
+    ``folder_name`` directory.
 
-      From https://github.com/rafia37/Evolution-of-Galaxies/blob/master/general.py
+    Originally from https://github.com/rafia37/Evolution-of-Galaxies/blob/master/general.py
 
     Usage:
-        fitspath = dir_date(folder_name, path_init='', year=True)
+        fitspath = dir_date(folder_name, year=True)
 
-    :param folder_name: str containing directory for date subdirectory will be in
+    :param folder_name: Directory for date subdirectory will be in
     :param path_init: root path. Default: empty string
     :param year: Indicate whether to include year in date folder. Default: False
-    :param verbose: bool to write verbose message to stdout. Default: file only
-    :param log: LogClass or logging object
+    :param verbose: Write verbose message to stdout. Default: file only
+    :param log: logging.Logger object
 
-    :return fitspath: Full path to the date directory
+    :return: Full path to the date directory
     """
 
-    if log is None:
-        log = log_stdout()
-
     log_verbose(log, "starting ...", verbose=verbose)
 
     today = date.today()
@@ -125,10 +124,17 @@ def dir_date(folder_name, path_init='', year=False, verbose=False, log=None):
     return fitspath
 
 
-def get_user(username=None, verbose=False, log=None):
+def get_user(username: Union[None, str] = None,
+             verbose: bool = False, log: Logger = log_stdout()) -> str:
+    """
+    Get the corresponding path for a given ``username``
+
+    :param username: Optional input for username
+    :param verbose: Write verbose message to stdout. Default: file only
+    :param log: logging.Logger object
 
-    if log is None:
-        log = log_stdout()
+    :return: Full path to the date directory
+    """
 
     log_verbose(log, "starting ...", verbose=verbose)
 

Metallicity_Stack_Commons/analysis/attenuation.py

@@ -1,3 +1,6 @@
+from logging import Logger
+from typing import Union, Tuple
+
 import numpy as np
 
 from .. import k_dict, line_name_short
@@ -19,24 +22,27 @@
 k_HDELTA = k_dict[HD]
 
 
-def compute_EBV(ratio, source='HgHb', zero_neg=True, verbose=False, log=None):
-    """
-    Purpose:
-      Determines E(B-V) from Hg/Hb or Hd/Hb flux ratios using Case B assumptions
-
-    :param ratio: float or numpy array containing Hg/Hb or Hd/Hb
-    :param source: str indicate ratio type.  Either 'HgHb' or 'HdHb'. Default: 'HgHb'
-    :param zero_neg: boolean to indicate whether to zero out negative reddening. Default: True
-    :param verbose: bool to write verbose message to stdout. Default: file only
-    :param log: LogClass or logging object
-
-    :return EBV: float or numpy array containing E(B-V).
-                 Note: Not correcting for negative reddening
-    :return EBV_peak: float or numpy array return when it is a 2-D distribution
+def compute_EBV(ratio: Union[float, np.ndarray], source: str = 'HgHb',
+                zero_neg: bool = True, verbose: bool = False,
+                log: Logger = log_stdout()) -> \
+        Union[float, np.ndarray, Tuple[np.ndarray, np.ndarray]]:
     """
+    Determines E(B-V) from Hg/Hb or Hd/Hb flux ratios using Case B assumptions
+
+    :param ratio: Float or array containing Hg/Hb or Hd/Hb values
+    :param source: Indicate ratio type. Either 'HgHb' or 'HdHb'.
+                   Default: 'HgHb'
+    :param zero_neg: Indicate whether to zero out negative reddening.
+                     Default: True
+    :param verbose: Write verbose message to stdout. Default: file only
+    :param log: logging.Logger object
 
-    if log is None:
-        log = log_stdout()
+    :return: E(B-V) values, E(B-V) peak values
+
+    Note:
+      When only E(B-V) values is returned, correction does not account
+      for negative reddening
+    """
 
     log_verbose(log, "starting ...", verbose=verbose)
 
@@ -87,42 +93,56 @@ def compute_EBV(ratio, source='HgHb', zero_neg=True, verbose=False, log=None):
         return EBV
 
 
-def compute_A(EBV, verbose=False, log=None):
+def compute_A(EBV: float, verbose: bool = False,
+              log: Logger = log_stdout()) -> dict:
     """
-    Purpose:
-      Compute A(Lambda) for all possible emission lines
+    Compute A(Lambda) for all possible emission lines
 
-    :param EBV: float value of E(B-V)
-      Has not been configured to handle a large array.  Some array handling would be needed
-    :param verbose: bool to write verbose message to stdout. Default: file only
-    :param log: LogClass or logging object
+    :param EBV: E(B-V) value
+      Has not been configured to handle a large array.
+      Some array handling would be needed
 
-    :return A_dict: dict containing A(lambda) with keys identical to k_dict
-    """
+    :param verbose: Write verbose message to stdout.
+           Default: file only
+    :param log: logging.Logger object
 
-    if log is None:
-        log = log_stdout()
+    :return: A(lambda) with keys identical to ``k_dict``
+    """
 
     log_verbose(log, "starting ...", verbose=verbose)
 
-    k_arr  = np.array(list(k_dict.values()))
+    k_arr = np.array(list(k_dict.values()))
 
-    A_arr  = k_arr * EBV
+    A_arr = k_arr * EBV
     A_dict = dict(zip(list(k_dict.keys()), A_arr))
 
     log_verbose(log, "finished.", verbose=verbose)
     return A_dict
 
 
-def line_ratio_atten(ratio, EBV, wave_top, wave_bottom, verbose=False,
-                     log=None):
+def line_ratio_atten(ratio: Union[float, np.ndarray],
+                     EBV: Union[float, np.ndarray],
+                     wave_top: str, wave_bottom: str,
+                     verbose: bool = False,
+                     log: Logger = log_stdout()) -> \
+        Union[float, np.ndarray]:
+    """
+    Determine dust-corrected emission-line ratios
 
-    if log is None:
-        log = log_stdout()
+    :param ratio: Float or array of observed flux ratios
+    :param EBV: E(B-V) value(s)
+    :param wave_top: Emission-line name for flux ratio numerator
+    :param wave_bottom: Emission-line name for flux ratio denominator
+    :param verbose: Write verbose message to stdout.
+           Default: file only
+    :param log: logging.Logger object
+
+    :return: Float or array of dust-corrected flux ratios
+    """
 
     log_verbose(log, "starting ...", verbose=verbose)
 
-    k_top    = k_dict[wave_top]
+    k_top = k_dict[wave_top]
     k_bottom = k_dict[wave_bottom]
 
     ratio_atten = ratio * 10**(0.4*EBV*(k_top - k_bottom))
@@ -131,28 +151,26 @@ def line_ratio_atten(ratio, EBV, wave_top, wave_bottom, verbose=False,
     return ratio_atten
 
 
-def Hb_SFR(log_LHb, EBV, verbose=False, log=None):
+def Hb_SFR(log_LHb: Union[float, np.ndarray],
+           EBV: Union[float, np.ndarray],
+           verbose: bool = False,
+           log: Logger = log_stdout()) -> \
+        Union[float, np.ndarray]:
     """
-    Purpose:
-      Determine dust-corrected SFR using the H-beta luminosity and a
-      measurement for nebular attenuation
+    Determine dust-corrected SFR using the H-beta luminosity and a
+    measurement for nebular attenuation
 
     Equation below is based on Eq. 2 in Ly et al. (2015), ApJ, 805, 45
       DOI: https://doi.org/10.1088/0004-637X/805/1/45
 
-    :param log_LHb: numpy array or float containing logarithm of H-beta
-           luminosity in units of erg/s
-    :param EBV: numpy array or float providing E(B-V)
-    :param verbose: bool to write verbose message to stdout. Default: file only
-    :param log: LogClass or logging object
+    :param log_LHb: Logarithm of H-beta luminosity in units of erg/s
+    :param EBV: E(B-V) value(s)
+    :param verbose: Write verbose message to stdout. Default: file only
+    :param log: logging.Logger object
 
-    :return logSFR: numpy array or float containing the SFR in
-            logarithmic units of M_sun/yr
+    :return: SFRs in logarithmic units of M_sun/yr
     """
 
-    if log is None:
-        log = log_stdout()
-
     log_verbose(log, "starting ...", verbose=verbose)
 
     logSFR = np.log10(4.4e-42 * HaHb_CaseB) + 0.4*EBV*k_HBETA + log_LHb

Metallicity_Stack_Commons/analysis/composite_indv_detect.py

@@ -1,3 +1,5 @@
+from logging import Logger
+
 from os.path import join
 from os.path import exists
 
@@ -21,40 +23,41 @@
 three_beta_name = indv_names0[6]
 
 
-def main(fitspath, dataset, revised=False, det3=True, verbose=False, log=None):
+def main(fitspath: str, dataset: str, revised: bool = False,
+         det3: bool = True, verbose: bool = False,
+         log: Logger = log_stdout()):
     """
-    Purpose:
-      Reads in composite table(s) containing bin information to
-      determine temperature-based metallicity from composite average
-      T_e and individual line ratios ([OII]/H-beta, [OIII]/H-beta)
-
-    :param fitspath: str containing folder path
-    :param dataset: str containing sub-folder (specific to stacking approach)
-    :param revised: Bool indicates whether to use revised bin properties
-                    (e.g., *.revised.tbl files)
-    :param det3: Bool indicates whether individual galaxy files is limited to
+    Reads in composite table(s) containing bin information to
+    determine temperature-based metallicity from composite average
+    T_e and individual line ratios ([OII]/H-beta, [OIII]/H-beta)
+
+    :param fitspath: Folder full path
+    :param dataset: Sub-folder path (specific to stacking approach)
+    :param revised: Indicates whether to use revised bin properties
+                    (e.g., revised.tbl files). Default: False
+    :param det3: Indicates whether individual galaxy files is limited to
                  those satisfying emission-line det3 requirement
                  Default: True
-    :param verbose: bool to write verbose message to stdout. Default: file only
-    :param log: LogClass or logging object
-
-    Files identified by default
-    composite_file: str containing filename of composite data
-      e.g., '[dataset]/bin_derived_properties.tbl' or
-            '[dataset]/bin_derived_properties.revised.tbl'
-    indv_em_line_file: str containing filename that contains
-                     emission-line information for each galaxy
+    :param verbose: Write verbose message to stdout. Default: file only
+    :param log: logging.Logger object
+
+    Files identified by default:
+
+    composite_file: Filename of composite data
+      e.g., '[dataset]/bin_derived_properties.tbl',
+      '[dataset]/bin_derived_properties.revised.tbl'
+
+    indv_em_line_file: Filename that contains emission-line information
+      for each galaxy
       e.g., 'individual_properties.tbl'
-    indv_bin_file: str containing filename tha contains bin information
-                   for each galaxy
+
+    indv_bin_file: Filename that contains bin information for each galaxy
       e.g., '[dataset]/individual_bin_info.tbl'
-    outfile: str containing filename of output file
+
+    outfile: Filename of output file
       e.g., '[dataset]/individual_derived_properties.tbl'
     """
 
-    if log is None:
-        log = log_stdout()
-
     log_verbose(log, "starting ...", verbose=verbose)
 
     # Define [composite_file]