Improving documentation & adapting to latest submodule versions

src/_build_utils.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python
 """
-Contains the ananke module building utility tools.
+Contains the ananke module building utility tools. Credit to
+https://github.com/GalacticDynamics-Oxford/Agama/blob/master/setup.py.
 """
 import pathlib
 import sys

src/ananke/Ananke.py

@@ -61,7 +61,9 @@ def __init__(self, particles, name, ngb=64, d_params={}, e_params={}, err_params
                 Number of neighbours to use in kernel density estimation
 
             d_params : dict
-                Parameters to configure the kernel density estimation
+                Parameters to configure the kernel density estimation. Use
+                class method display_density_docs to find what parameters can
+                be defined
 
             e_params : dict
                 Parameters to configure the extinction pipeline. Use class
@@ -177,12 +179,12 @@ def _prepare_extinctiondriver_proxy(self, e_params):
     def _prepare_errormodeldriver_proxy(self, err_params):
         return ErrorModelDriver(self, **err_params)
 
-    def _prep_galaxia_input(self, rho, knorm = 0.596831):
+    def _prepare_galaxia_input(self, rho, knorm = 0.596831):
         if self.__galaxia_input is None:
             self.__galaxia_input = Galaxia.Input(self._galaxia_particles, rho[POS_TAG], rho[VEL_TAG], name=self.name, knorm=knorm, ngb=self.ngb)
         return self.__galaxia_input
 
-    def _prep_galaxia_survey(self, input: Galaxia.Input, surveyname = 'survey'):
+    def _prepare_galaxia_survey(self, input: Galaxia.Input, surveyname = 'survey'):
         if self.__galaxia_survey is None:
             self.__galaxia_survey = Galaxia.Survey(input, photo_sys=self.photo_sys, surveyname=surveyname)
         return self.__galaxia_survey
@@ -214,8 +216,8 @@ def _run_galaxia(self, rho, **kwargs):
             output : :obj:`Galaxia.Output`
                 Handler with utilities to utilize the output survey and its data.
             """
-        input = self._prep_galaxia_input(rho, **{k:kwargs.pop(k) for k in ['knorm'] if k in kwargs})
-        survey = self._prep_galaxia_survey(input, **{k:kwargs.pop(k) for k in ['surveyname'] if k in kwargs})
+        input = self._prepare_galaxia_input(rho, **{k:kwargs.pop(k) for k in ['knorm'] if k in kwargs})
+        survey = self._prepare_galaxia_survey(input, **{k:kwargs.pop(k) for k in ['surveyname'] if k in kwargs})
         self.__galaxia_output = survey.make_survey(**self._galaxia_kwargs, **kwargs)
         return self._galaxia_output
 
@@ -343,11 +345,11 @@ def galaxia_catalogue_mag_names(self):
 
     @property
     def intrinsic_catalogue_mag_names(self):
-        return list(map(self._intrinsic_mag_template, self.galaxia_catalogue_mag_names))
+        return tuple(map(self._intrinsic_mag_template, self.galaxia_catalogue_mag_names))
 
     @property
     def galaxia_catalogue_mag_and_astrometrics(self):
-        return self.galaxia_catalogue_mag_names + [Galaxia.Output._pi] + Galaxia.Output._cel + Galaxia.Output._mu + [Galaxia.Output._vr]
+        return self.galaxia_catalogue_mag_names + (Galaxia.Output._pi,) + Galaxia.Output._cel + Galaxia.Output._mu + (Galaxia.Output._vr,)
 
     @property
     def galaxia_catalogue_keys(self):
@@ -416,6 +418,20 @@ def display_available_photometric_systems(cls):
         """
         return Galaxia.photometry.available_photo_systems
 
+    @classmethod
+    def display_density_docs(cls):
+        """
+            Print the DensitiesDriver constructor docstring
+        """
+        print(DensitiesDriver.__init__.__doc__)
+
+    @classmethod
+    def display_EnBiD_docs(cls):
+        """
+            Print the EnBiD.run_enbid docstring
+        """
+        DensitiesDriver.display_EnBiD_docs()
+
     @classmethod
     def display_extinction_docs(cls):
         """

src/ananke/DensitiesDriver.py

@@ -28,8 +28,12 @@ def __init__(self, ananke: Ananke, **kwargs) -> None:
             ----------
             ananke : Ananke object
                 The Ananke object that utilizes this DensitiesDriver object
+            
             **kwargs
-                Additional parameters to be used by the density estimator
+                Additional parameters to be used by the density estimator. In
+                the current implementation, these include all the configurable
+                parameters of EnBiD accessible through the class method
+                display_EnBiD_docs
         """
         self.__ananke = ananke
         self.__parameters = kwargs
@@ -84,4 +88,10 @@ def densities(self):
             return self._run_enbid()
         else:
             return self.__densities
-
+
+    @classmethod
+    def display_EnBiD_docs(cls):
+        """
+            Print the EnBiD.run_enbid docstring
+        """
+        print(EnBiD.run_enbid.__doc__)

src/ananke/ErrorModelDriver.py

@@ -10,10 +10,8 @@
 from warnings import warn
 from collections.abc import Iterable
 import numpy as np
-import pandas as pd
-
-from Galaxia_ananke import utils as Gutils
 
+from . import utils
 from ._default_error_model import *
 from .constants import *
 
@@ -31,7 +29,7 @@ class ErrorModelDriver:
     _sigma_template = _sigma_formatter.format
     _error_formatter = '{}_Err'
     _error_template = _error_formatter.format
-    _extra_output_keys = []
+    _extra_output_keys = ()
 
     def __init__(self, ananke: Ananke, **kwargs) -> None:
         """
@@ -76,13 +74,13 @@ def _expand_and_apply_error_model(self, df):
         return {key: error for error_dict in [(err_model(df) if callable(err_model) else err_model) for err_model in error_model] for key,error in error_dict.items()}  # TODO adapt to dataframe type of output?
 
     def _test_error_model(self):
-        dummy_df = pd.DataFrame([], columns = self.ananke.galaxia_catalogue_keys + self._extra_output_keys)  # TODO create a DataFrame subclass that intercepts __getitem__ and record every 'key' being used
+        dummy_df = utils.RecordingDataFrame([], columns = self.ananke.galaxia_catalogue_keys + self._extra_output_keys)  # TODO make use of dummy_df.record_of_all_used_keys
         dummy_df.loc[0] = np.nan
         try:
             dummy_err = self._expand_and_apply_error_model(dummy_df)
         except KeyError as KE:
             raise KE  # TODO make it more informative
-        Gutils.compare_given_and_required(dummy_err.keys(), self.ananke.galaxia_catalogue_mag_and_astrometrics, set(self.ananke.galaxia_catalogue_keys)-set(self.ananke.galaxia_catalogue_mag_and_astrometrics), error_message="Given error model function returns wrong set of keys")
+        utils.compare_given_and_required(dummy_err.keys(), self.ananke.galaxia_catalogue_mag_and_astrometrics, set(self.ananke.galaxia_catalogue_keys)-set(self.ananke.galaxia_catalogue_mag_and_astrometrics), error_message="Given error model function returns wrong set of keys")
 
     @property
     def _sigma_keys(self):
@@ -98,12 +96,16 @@ def errors(self):
             magnitudes = self.ananke.galaxia_catalogue_mag_names
             with_columns = []
             for prop_name, error in self._expand_and_apply_error_model(self.galaxia_output).items():
+                # pre-generate the keys to use for the standard error and its actual gaussian drawn error of property prop_name
                 prop_sig_name, prop_err_name = self._sigma_template(prop_name), self._error_template(prop_name)
+                # assign the column of the standard error values for property prop_name in the final catalogue output 
                 self.galaxia_output[prop_sig_name] = error
+                # assign the column of the actual gaussian drawn error values for property prop_name in the final catalogue output 
                 self.galaxia_output[prop_err_name] = error*np.random.randn(self.galaxia_output.shape[0])
+                # add the drawn error value to the existing quantity for property prop_name
                 self.galaxia_output[prop_name] += self.galaxia_output[prop_err_name]
                 with_columns.append(prop_name)
-        self.galaxia_output.flush_extra_columns_to_hdf5(with_columns=with_columns)
+        self.galaxia_output.flush_extra_columns_to_hdf5(with_columns=tuple(with_columns))
         self.galaxia_output._pp_convert_icrs_to_galactic()
         return self.galaxia_output[list(self._error_keys)]
 

src/ananke/ExtinctionDriver.py

@@ -12,10 +12,8 @@
 import numpy as np
 import scipy as sp
 import scipy.interpolate  # needed for python==3.7
-import pandas as pd
-
-from Galaxia_ananke import utils as Gutils
 
+from . import utils
 from ._default_extinction_coeff import *
 from .constants import *
 
@@ -36,7 +34,7 @@ class ExtinctionDriver:
     _extinction_formatter = 'A_{}'
     _extinction_template = _extinction_formatter.format
     _extinction_0 = _extinction_template(0)
-    _extra_output_keys = [_reddening, _extinction_0]
+    _extra_output_keys = (_reddening, _extinction_0)
 
     def __init__(self, ananke: Ananke, **kwargs) -> None:
         """
@@ -72,24 +70,19 @@ def __init__(self, ananke: Ananke, **kwargs) -> None:
 
     __init__.__doc__ = __init__.__doc__.format(Q_DUST=Q_DUST, TOTAL_TO_SELECTIVE=TOTAL_TO_SELECTIVE)
 
-    def _make_interpolator(self):  # TODO to review
-        xvsun = self.ananke.observer_position
-        pos_pa = self.ananke.particle_positions
-        xhel = pos_pa - xvsun[:3]
-        # TODO coordinates.SkyCoord(**dict(zip([*'uvw'], xhel.T)), unit='kpc', representation_type='cartesian', frame='galactic') ?
-        # phi = np.pi + np.arctan2(xvsun[1], xvsun[0])
-        # rot = np.array([
-        #     [np.cos(phi), np.sin(phi), 0.0],
-        #     [-np.sin(phi), np.cos(phi), 0.0],
-        #     [0.0, 0.0, 1.0]
-        #     ])
-        xhel_p = xhel  # np.dot(xhel,rot.T)
+    def _make_interpolator(self):
+        # center particle coordinates on the observer
+        xhel_p = self.ananke.particle_positions - self.ananke.observer_position[:3]
+        # TODO coordinates.SkyCoord(**dict(zip([*'uvw'], xhel_p.T)), unit='kpc', representation_type='cartesian', frame='galactic') ?
+        # return distances from observer to particles
         dhel_p = np.linalg.norm(xhel_p, axis=1)
-        rmin, rmax = self.ananke.universe_rshell
-        rmin *= 0.9
-        rmax *= 1.1
+        # return the min,max extent of the shell of particles used by Galaxia (with a +-0.1 margin factor)
+        rmin, rmax = self.ananke.universe_rshell * [0.9, 1.1]
+        # create a mask for the particles that are within the shell
         sel_interp = (rmin<dhel_p) & (dhel_p<rmax)
+        # get the array of column densities input by the user to each particle
         lognh = self.column_densities
+        # generate the interpolator to use to get the column densities at positions in and around the particles
         self.__interpolator = sp.interpolate.LinearNDInterpolator(xhel_p[sel_interp],lognh[sel_interp],rescale=False)  # TODO investigate NaN outputs from interpolator
         return self.__interpolator
 
@@ -147,13 +140,13 @@ def _expand_and_apply_extinction_coeff(self, df, A0):
         return {key: A0 * coeff for coeff_dict in [(ext_coeff(df) if callable(ext_coeff) else ext_coeff) for ext_coeff in extinction_coeff] for key,coeff in coeff_dict.items()}  # TODO adapt to dataframe type of output?
 
     def _test_extinction_coeff(self):
-        dummy_df = pd.DataFrame([], columns = self.ananke.galaxia_catalogue_keys + self._extra_output_keys)  # TODO create a DataFrame subclass that intercepts __getitem__ and record every 'key' being used
+        dummy_df = utils.RecordingDataFrame([], columns = self.ananke.galaxia_catalogue_keys + self._extra_output_keys)  # TODO make use of dummy_df.record_of_all_used_keys
         dummy_df.loc[0] = np.nan
         try:
             dummy_ext = self._expand_and_apply_extinction_coeff(dummy_df, dummy_df[self._extinction_0])
         except KeyError as KE:
             raise KE  # TODO make it more informative
-        Gutils.compare_given_and_required(dummy_ext.keys(), self.ananke.galaxia_catalogue_mag_names, error_message="Given extinction coeff function returns wrong set of keys")
+        utils.compare_given_and_required(dummy_ext.keys(), self.ananke.galaxia_catalogue_mag_names, error_message="Given extinction coeff function returns wrong set of keys")
 
     @property
     def _extinction_keys(self):
@@ -163,7 +156,9 @@ def _extinction_keys(self):
     def extinctions(self):
         if self._extinction_keys.difference(self.galaxia_output.columns):
             for mag_name, extinction in self._expand_and_apply_extinction_coeff(self.galaxia_output, self.extinction_0).items():
+                # assign the column of the extinction values for filter mag_name in the final catalogue output 
                 self.galaxia_output[self._extinction_template(mag_name)] = extinction
+                # add the extinction value to the existing photometric magnitude for filter mag_name
                 self.galaxia_output[mag_name] += extinction
         self.galaxia_output.flush_extra_columns_to_hdf5(with_columns=self.ananke.galaxia_catalogue_mag_names)
         return self.galaxia_output[list(self._extinction_keys)]

src/ananke/Observer.py

@@ -8,7 +8,7 @@
 from __future__ import annotations
 from typing import TYPE_CHECKING
 import numpy as np
-import numpy.typing
+import numpy.typing  # needed for python==3.7
 from Galaxia_ananke.constants import DEFAULTS_FOR_PARFILE
 
 from .constants import *

src/ananke/Universe.py

@@ -8,7 +8,7 @@
 from __future__ import annotations
 from typing import TYPE_CHECKING
 import numpy as np
-import numpy.typing
+import numpy.typing  # needed for python==3.7
 from Galaxia_ananke.constants import DEFAULTS_FOR_PARFILE
 
 from .constants import *

src/ananke/_default_error_model.py

@@ -11,9 +11,14 @@
 
 def _temp(df):
     """
-    Approximate error model for DR2
-    based on Table 3 of release paper
-    returns uncertainty estimate in magnitudes, mas, mas/yr, km/s
+    Default error model function for the Gaia DR2 photometric system.
+
+    Notes
+    -----
+    Approximate error model is based on the Gaia DR2 release paper
+    (https://ui.adsabs.harvard.edu/abs/2018A%26A...616A...1G/abstract) and its
+    Table 3 which returns uncertainty estimates in magnitudes, mas, mas/yr,
+    km/s.
     """
     GMAG  = 'gaiadr2_gmag'
     RPMAG = 'gaiadr2_g_rpmag'
@@ -27,7 +32,7 @@ def _temp(df):
     TEFF  = 'teff'
     MAS_TO_DEG = (units.mas/units.deg).si.scale
     def grvs_from_g_rp(gmag, rpmag):
-        #from equations 2 and 3 of DR2 release paper
+        # from equations 2 and 3 of DR2 release paper
         ggrp = gmag - rpmag
         grvs = rpmag + 132.32 - 377.28*ggrp + 402.32*ggrp**2 - 190.97*ggrp**3 + 34.026*ggrp**4
         mask = ggrp < 1.4

src/ananke/_default_extinction_coeff.py

@@ -8,15 +8,25 @@
 from Galaxia_ananke import photometry as ph
 
 def _temp(df):
-    #Constants for empirical extinction model - Table 1 of Babusiaux et al 2018
-    #to easily match to Equation 1 of the paper, c[0]=0 
+    """
+    Default extinction coefficient function for the Gaia DR2 photometric
+    system.
+
+    Notes
+    -----
+    Constants for the empirical extinction model are taken from Table 1 of
+    Babusiaux et al. 2018 (ui.adsabs.harvard.edu/abs/2018A%26A...616A..10G)
+    with the coefficients determined their Equation 1
+    """
+    # Constants for the empirical extinction model from Table of Babusiaux et al. 2018
     consts = {
         'gaiadr2_gmag': [0.0, 0.9761,-0.1704,0.0086,0.0011,-0.0438,0.0013,0.0099],
         'gaiadr2_g_bpmag':[0.0, 1.1517,-0.0871,-0.0333,0.0173,-0.0230,0.0006,0.0043],
         'gaiadr2_g_rpmag':[0.0, 0.6104,-0.0170,-0.0026,-0.0017,-0.0078,0.00005,0.0006]
     }
     bp_rp_int = df['gaiadr2_g_bpmag'] - df['gaiadr2_g_rpmag']
     A_0 = df['A_0']
+    # Coeffients from Equation 1 of Babusiaux et al. 2018
     return {b: c[1] + c[2]*bp_rp_int + c[3]*bp_rp_int**2 + c[4]*bp_rp_int**3 +c[5]*A_0 +c[6]*A_0**2 +c[7]*bp_rp_int*A_0 for b,c in consts.items()}
 
 ph.available_photo_systems['padova/GAIADR2'].default_extinction_coeff = _temp

src/ananke/utils.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 """
-Docstring
+Module miscellaneous utilities
 """
 import pandas as pd