Define catalogue_dtype in flarestack.core.data_types (#187)

Decoupling the catalogue type definition from the functional code.

docs/source/api.rst

@@ -1,7 +1,13 @@
-API
-===
-
-
+..
+    As long as data types are defined as names (instead of classes), it is not possible to provide a sphinx-friendly docstring.
+..
+    API
+    ===
+    ###############
+    Data types
+    ###############
+    .. automodule:: flarestack.core.data_types
+        :members:
 
 ###############
 Base PDFs

docs/source/data_types.md

@@ -0,0 +1,16 @@
+# Data types
+The module `core.data_types` is meant to collect different data types used by the different modules of *flarestack*, so they can be inspected and manipulated by the user in an independent fashion.
+
+Currently, it only includes `catalogue_dtype`.
+
+## Catalogue
+A *flarestack* catalogue takes the form of a `numpy` [structured array](https://numpy.org/doc/stable/user/basics.rec.html), consisting of the following fields:
+- `ra_rad` (`np.float`): right ascension (J2000.0) of the source in radians;
+- `dec_rad` (`np.float`): declination of the source in radians;
+- `base_weight` (`np.float`): base weight of the source for injection and fitting. Base weights should **not** include the distance scaling (this is handled implicitly by *flarestack*). *flarestack* takes care of normalising base weights to their sum, so the absolute scale of `base_weight` is not important.
+- `injection_weight_modifier` (`np.float`): multiplicative factor for `base _weight` only used in the signal injection. By default it should be set to one. Proper usage implies taking care of preserving the overall flux normalisation, so handle with care. 
+- `ref_time_mjd` (`np.float`): reference time, modified Julian day.
+- `start_time_mjd` (`np.float`): start time for the source time window, modifed Julian day. This is used for time-dependent injection and fitting.
+- `end_time_mjd` (`np.float`): end time for the source time window, modified Julian day. This is used for time-dependent injection and fitting.
+- `distance_mpc` (`np.float`): distance of the source, in Mpc (megaparsecs).
+- `source_name` (string): name of the source.

docs/source/index.rst

@@ -49,6 +49,7 @@ CONTENTS
 
 .. toctree::
    setup
+   data_types
    flarestack_llh_workshop
    api
    :maxdepth: 2

flarestack/core/data_types.py

@@ -0,0 +1,18 @@
+"""
+This module provides the basic data types used by the other modules of flarestack.
+"""
+
+import numpy as np
+
+""" Catalogue data type """
+catalogue_dtype = [
+    ("ra_rad", np.float),
+    ("dec_rad", np.float),
+    ("base_weight", np.float),
+    ("injection_weight_modifier", np.float),
+    ("ref_time_mjd", np.float),
+    ("start_time_mjd", np.float),
+    ("end_time_mjd", np.float),
+    ("distance_mpc", np.float),
+    ("source_name", "a30"),
+]

flarestack/cosmo/simulate_catalogue.py

@@ -4,7 +4,7 @@
 import os
 import logging
 from flarestack.shared import catalogue_dir
-from flarestack.utils.prepare_catalogue import cat_dtype
+from flarestack.core.data_types import catalogue_dtype
 from flarestack.cosmo.neutrino_cosmology import (
     define_cosmology_functions,
     integrate_over_z,
@@ -100,7 +100,7 @@ def simulate_transient_catalogue(
     if not np.logical_and(
         np.sum([os.path.isfile(x) for x in cat_names]) == len(cat_names), not resimulate
     ):
-        catalogue = np.empty(n_local, dtype=cat_dtype)
+        catalogue = np.empty(n_local, dtype=catalogue_dtype)
 
         catalogue["source_name"] = ["src" + str(i) for i in range(n_local)]
         catalogue["ra_rad"] = np.random.uniform(0.0, 2 * np.pi, n_local)

flarestack/utils/prepare_catalogue.py

@@ -12,17 +12,10 @@
 import zlib
 from flarestack.shared import catalogue_dir
 
-cat_dtype = [
-    ("ra_rad", np.float),
-    ("dec_rad", np.float),
-    ("base_weight", np.float),
-    ("injection_weight_modifier", np.float),
-    ("ref_time_mjd", np.float),
-    ("start_time_mjd", np.float),
-    ("end_time_mjd", np.float),
-    ("distance_mpc", np.float),
-    ("source_name", "a30"),
-]
+""" 
+Previously `cat_dtype` was defined here. Old analyses import the type definition from this module.
+"""
+from flarestack.core.data_types import catalogue_dtype as cat_dtype
 
 
 def single_source(sindec, ra_rad=np.pi):