From e48dbd304ab9051d0258b0c4b1a3eb5572d8b40f Mon Sep 17 00:00:00 2001 From: Massimiliano Lincetto Date: Wed, 28 Sep 2022 11:04:20 +0200 Subject: [PATCH] Define `catalogue_dtype` in `flarestack.core.data_types` (#187) Decoupling the catalogue type definition from the functional code. --- docs/source/api.rst | 14 ++++++++++---- docs/source/data_types.md | 16 ++++++++++++++++ docs/source/getting_started.rst | 4 ---- docs/source/index.rst | 1 + flarestack/core/data_types.py | 18 ++++++++++++++++++ flarestack/cosmo/simulate_catalogue.py | 4 ++-- flarestack/utils/prepare_catalogue.py | 15 ++++----------- 7 files changed, 51 insertions(+), 21 deletions(-) create mode 100644 docs/source/data_types.md delete mode 100644 docs/source/getting_started.rst create mode 100644 flarestack/core/data_types.py diff --git a/docs/source/api.rst b/docs/source/api.rst index 997b5f17..4cb1bdd6 100644 --- a/docs/source/api.rst +++ b/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 diff --git a/docs/source/data_types.md b/docs/source/data_types.md new file mode 100644 index 00000000..cc71d896 --- /dev/null +++ b/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. diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst deleted file mode 100644 index 0e18c25f..00000000 --- a/docs/source/getting_started.rst +++ /dev/null @@ -1,4 +0,0 @@ -Getting started -=============== - - diff --git a/docs/source/index.rst b/docs/source/index.rst index 708c4970..f7f414d4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -49,6 +49,7 @@ CONTENTS .. toctree:: setup + data_types flarestack_llh_workshop api :maxdepth: 2 diff --git a/flarestack/core/data_types.py b/flarestack/core/data_types.py new file mode 100644 index 00000000..c5b56e68 --- /dev/null +++ b/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"), +] diff --git a/flarestack/cosmo/simulate_catalogue.py b/flarestack/cosmo/simulate_catalogue.py index eef15d01..522b1e56 100644 --- a/flarestack/cosmo/simulate_catalogue.py +++ b/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) diff --git a/flarestack/utils/prepare_catalogue.py b/flarestack/utils/prepare_catalogue.py index b84a6204..772accf5 100644 --- a/flarestack/utils/prepare_catalogue.py +++ b/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):