Doc strings reformatting

README.md

@@ -21,6 +21,7 @@ Other software utilities can be found in this github repository: [https://github
 * All required input files for the main software or unit tests should have extensions that clearly describe the file format (e.g. .csv, .txt, .db, .fits)
 * If you are working on addressing a specific issue ticket, assign yourself the ticket.
 * When making a pull request that closes an issue, cite the issue ticket in the pull request summary
+* Docstrings should follow the [NumPy style](https://numpydoc.readthedocs.io/en/latest/format.html) 
 
 ## Collaboration
 This effort is a collaboration between Queen's University Belfast, the University of Washington's DiRAC Institute, 

src/sorcha/ephemeris/simulation_constants.py

@@ -14,13 +14,16 @@ def create_ecl_to_eq_rotation_matrix(ecl):
     system's ecliptic obliquity is already provided as
     `ECL_TO_EQ_ROTATION_MATRIX`.
 
-    Parameters:
+    Parameters
     -----------
-    ecl (float): The ecliptical obliquity.
+    ecl : float
+        The ecliptical obliquity.
 
-    Returns:
+    Returns
     -----------
-    `numpy` array with shape (3,3).
+    rotmat: numpy array/matrix of floats
+        rotation matrix for transofmring ecliptical coordinates to equatorial coordinates.
+        Array has shape (3,3).
 
     """
     ce = np.cos(-ecl)

src/sorcha/ephemeris/simulation_data_files.py

@@ -74,16 +74,16 @@ def make_retriever(directory_path: str = None, registry: dict = REGISTRY) -> poo
 
     Parameters
     ----------
-    directory_path : str, optional
-        The base directory to place all downloaded files, by default None
-    registry : dict, optional
+    directory_path : string, optional
+        The base directory to place all downloaded files. Default = None
+    registry : dictionary, optional
         A dictionary of file names to SHA hashes. Generally we'll not use SHA=None
-        because the files we're tracking change frequently, by default REGISTRY
+        because the files we're tracking change frequently. Default = REGISTRY
 
     Returns
     -------
-    pooch.Pooch
-        The Pooch object used to track and retrieve files.
+    : pooch
+        The instance of a Pooch object used to track and retrieve files.
     """
     dir_path = pooch.os_cache("sorcha")
     if directory_path:

src/sorcha/ephemeris/simulation_driver.py

@@ -35,29 +35,15 @@ def create_ephemeris(orbits_df, pointings_df, args, configs):
     """Generate a set of observations given a collection of orbits
     and set of pointings.
 
-    This works by calculating and regularly updating the sky-plane
-    locations (unit vectors) of all the objects in the collection
-    of orbits.  The HEALPix index for each of the locations is calculated.
-    A dictionary with pixel indices as keys and lists of ObjIDs for
-    those objects in each HEALPix tile as values.  One of these
-    calculations is called a 'picket', as one element of a long picket
-    fence.  At present,
-
-    Given a specific pointing, the set of HEALPix tiles that are overlapped
-    by the pointing (and a buffer region) is computed.  These the precise
-    locations of just those objects within that set of HEALPix tiles are
-    computed.  Details for those that actually do land within the field
-    of view are passed along.
-
     Parameters
     ----------
-    orbits_df : pd.DataFrame
+    orbits_df : pandas dataframe
         The dataframe containing the collection of orbits.
-    pointings_df : pd.DataFrame
+    pointings_df : pandas dataframe
         The dataframe containing the collection of telescope/camera pointings.
     args :
         Various arguments necessary for the calculation
-    configs : dict
+    configs : dictionary
         Various configuration parameters necessary for the calculation
         ang_fov : float
             The angular size (deg) of the field of view
@@ -74,14 +60,30 @@ def create_ephemeris(orbits_df, pointings_df, args, configs):
             The MPC code for the observatory.  (This is current a configuration
             parameter, but these should be included in the visit information,
             to allow for multiple observatories.
-        nside : int
+        nside : integer
             The nside value used for the HEALPIx calculations.  Must be a
             power of 2 (1, 2, 4, ...)  nside=64 is current default.
 
     Returns
     -------
-    pd.DataFrame
+    observations: pandas dataframe
         The dataframe of observations needed for Sorcha to continue
+
+    Notes
+    -------
+    This works by calculating and regularly updating the sky-plane
+    locations (unit vectors) of all the objects in the collection
+    of orbits.  The HEALPix index for each of the locations is calculated.
+    A dictionary with pixel indices as keys and lists of ObjIDs for
+    those objects in each HEALPix tile as values.  One of these
+    calculations is called a 'picket', as one element of a long picket
+    fence.  At present,
+
+    Given a specific pointing, the set of HEALPix tiles that are overlapped
+    by the pointing (and a buffer region) is computed.  These the precise
+    locations of just those objects within that set of HEALPix tiles are
+    computed.  Details for those that actually do land within the field
+    of view are passed along.
     """
     verboselog = args.pplogger.info if args.verbose else lambda *a, **k: None
 
@@ -254,14 +256,14 @@ def calculate_rates_and_geometry(pointing: pd.DataFrame, ephem_geom_params: Ephe
 
     Parameters
     ----------
-    pointing : pd.DataFrame
+    pointing : pandas dataframe
         The dataframe containing the pointing database.
     ephem_geom_params : EphemerisGeometryParameters
         Various parameters necessary to calculate the ephemeris
 
     Returns
     -------
-    tuple
+    : tuple
         Tuple containing the ephemeris parameters needed for Sorcha post processing.
     """
     ra0, dec0 = vec2ra_dec(ephem_geom_params.rho_hat)

src/sorcha/ephemeris/simulation_setup.py

@@ -36,8 +36,12 @@ def create_assist_ephemeris(args) -> tuple:
 
     Returns
     -------
-    Ephem, gm_sun
+    Ephem : ASSIST ephemeris obejct
         The ASSIST ephemeris object
+    gm_sun : float
+        value for the GM_SUN value
+    gm_total : float
+        value for gm_total
     """
     pplogger = logging.getLogger(__name__)
 
@@ -133,16 +137,16 @@ def precompute_pointing_information(pointings_df, args, configs):
 
     Parameters
     ----------
-    pointings_df : pd.dataframe
+    pointings_df : pandas dataframe
         Contains the telescope pointing database.
-    args : dict
+    args : dictionary
         Command line arguments needed for initialization.
-    configs : dict
+    configs : dictionary
         Configuration settings.
 
     Returns
     -------
-    pointings_df : pd.dataframe
+    pointings_df : pandas dataframe
         The original dataframe with several additional columns of precomputed values.
     """
     ephem, _, _ = create_assist_ephemeris(args)

src/sorcha/lightcurves/base_lightcurve.py

@@ -64,7 +64,7 @@ def _log_error_message(self, error_msg: str) -> None:
 
         Parameters
         ----------
-        error_msg : str
+        error_msg : string
             The string to be appended to the error log
         """
         logger.error(error_msg)

src/sorcha/lightcurves/identity_lightcurve.py

@@ -50,7 +50,7 @@ def name_id() -> str:
 
         Returns
         -------
-        str
+        string
             Unique identifier for this light curve calculator
         """
         return "identity"