Merge pull request #103 from nikhil-sarin/update_docs_and_bugfixes

Update docs and bugfixes

README.md

@@ -24,8 +24,11 @@ Redback is a software package for end-to-end interpretation and parameter estima
 
 ### Contributing 
 Redback is currently in alpha with a paper in preparation. 
-If you are interested in contributing please join the redback [slack](https://join.slack.com/t/slack-23u4492/shared_invite/zt-14y9q1qmo-VRmc8ZxHzB3u~dB3Wi6pjw). All contributors at the alpha stage will be invited to be co-authors of the first paper.
+If you are interested in contributing please join the redback 
+[slack](https://join.slack.com/t/slack-23u4492/shared_invite/zt-14y9q1qmo-VRmc8ZxHzB3u~dB3Wi6pjw)
+and email [Nikhil Sarin](mailto:nikhil.sarin@su.se?subject=Contributing%20to%20redback). 
+All contributors at the alpha stage will be invited to be co-authors of the first paper.
 
-To make changes to redback, we require users to use a pull request system. 
+To make changes to redback, we require users to use a merge request system. 
 
 

docs/acknowledgements.txt

@@ -9,7 +9,9 @@ please acknowledge the :code:`redback` software, and cite the github page.
 Using :code:`redback` to fit transients
 -------------------------
 
-If you use :code:`redback` to fit an electromagnetic transient, please cite the `Bilby paper <https://ui.adsabs.harvard.edu/#abs/2018arXiv181102042A/abstract>`_
+If you use :code:`redback` to fit an electromagnetic transient,
+please cite the `Bilby paper <https://ui.adsabs.harvard.edu/#abs/2018arXiv181102042A/abstract>`_,
+and the :code:`redback` paper (when it is out).
 
 Alongside this we request that you also cite the paper associated with the sampler you use.
 Furthermore, several models implemented in :code:`redback` are introduced in previous scientific publications.
@@ -24,11 +26,12 @@ For example,
 
     citation = kilonova_models.one_component_kilonova_model.citation
 
-Here citation will be a url to the ads page for the model.
+Here citation will be a url to the NASA ads page for the paper describing the model.
 If you use a specific model or build upon it, we request that you also cite the paper for the model.
 
 In several cases, the citation will be `redback`, in which case,
 only a citation to :code:`redback`, :code:`bilby`, and the sampler is necessary.
+Although we recommend periodically checking the citation in the latest :code:`redback` release.
 
 Using :code:`redback` to simulate transients
 -------------------------

docs/code_motivation.txt

@@ -2,22 +2,34 @@
 Code motivation
 ============
 
-How redback can be useful to you
--------------------------
-
 The launch of new telescopes/surveys is leading to an explosion of transient observations.
-Redback is a software package for end-to-end interpretation and parameter estimation of these transients.
+Redback is a software package that enables end-to-end interpretation and parameter estimation of these transients.
+Redback is built with an object oriented modular approach.
+This ensures that users can use different parts of :code:`redback` for their own use without needing to interact with other parts.
+
+How :code:`redback` can be useful to you
+-------------------------
 
 - Download data for supernovae, tidal disruption events, gamma-ray burst afterglows, kilonovae, prompt emission from
-  different catalogs/telescopes; Swift, BATSE, Open access catalogs. Users can also provide their own data or use simulated data
-- Redback processes the data into a homogeneous transient object, plotting lightcurves and doing other processing.
-- The user can then fit one of the models implemented in redback. Or fit their own model. Models for several different types of electromagnetic transients are implemented and range from simple analytical models to numerical surrogates.
-- All models are implemented as functions and can be used to simulate populations, without needing to provide data. This way redback can be used simply as a tool to simulate realistic populations, no need to actually fit anything.
-- `Bilby <https://lscsoft.docs.ligo.org/bilby/index.html>`_ under the hood. Can easily switch samplers/likelihoods etc. By default the choice is made depending on the data.
-- Fitting returns a homogenous result object, with functionality to plot lightcurves and the posterior/evidence etc.
+  different catalogs/telescopes; Swift, BATSE, Open access catalogs, ZTF, etc. Users can also provide their own data or use simulated data.
+- Process transient data into a homogeneous transient object, providing an interface for plotting lightcurves and doing other processing.
+- Fit one of the models implemented in :code:`redback`, or fit your own model.
+  Models for several different types of electromagnetic transients are implemented and range from simple analytical models to numerical surrogates.
+- All models are implemented as functions and can be used to simulate populations, without needing to provide data.
+This way :code:`redback` can be used simply as a tool to simulate realistic populations, no need to actually fit anything.
+- Fitting returns a homogenous result object, with functionality to plot lightcurves/walkers/corner and the posterior/evidence/credible interval etc.
+This way :code:`redback` results can feed into hierarchical analysis of populations of transients or be used in reweighting.
 
-Advantages of the interface to Bilby
+Advantages of the interface to :code:`bilby`
 -------------------------
 
-As we are using :code:`bilby` under the hood for sampling, priors, likelihood, we have a natural interface to gravitational-wave parameter estimation. This enables easy multi-messenger analysis with redback doing the transient part, and bilby doing the GW part.
-We demonstrate this in the `examples <https://github.com/nikhil-sarin/redback/tree/master/examples>`_
+We use `bilby <https://lscsoft.docs.ligo.org/bilby/index.html>`_ under the hood for inference, which has many advantages.
+
+- Easily change samplers, likelihoods, place constraints on priors, etc.
+- Natural interface with gravitational-wave parameter estimation.
+  Enabling multi-messenger analysis with :code:`redback` used in fitting to the electromagnetic data,
+  and :code:`bilby` for gravitational-wave parameter estimation.
+- A large developer/user base for core functionality.
+`:code:`bilby` is adopted by the LIGO-Virgo-Kagra Collaboration
+and used in all parameter estimation results by the LVK collaboration and in over 300 publications,
+a testament to its ease of use and robustness.

docs/contributing.txt

@@ -6,13 +6,14 @@ Redback is currently in alpha with a paper in preparation.
 If you are interested in contributing please join the :code:`redback` `slack <https://join.slack.com/t/slack-23u4492/shared_invite/zt-14y9q1qmo-VRmc8ZxHzB3u~dB3Wi6pjw>`_.
 All contributors at the alpha stage will be invited to be co-authors of the first paper.
 
-To make contributions to :code:`redback` at this stage,
-we request that you first make an issue on :code:`redback` github `page <https://github.com/nikhil-sarin/redback/issues>`_.
+To make contributions to :code:`redback`,
+we request that you first make an issue on :code:`redback` github `page <https://github.com/nikhil-sarin/redback/issues>`_ describing what contribution you want to make.
 This minimises the risk of double effort from different people contributing the same functionality.
 
-We also request that you use a merge request and implement some form of a unit test/or example that can be used to test your feature.
-A lot of the documentation is automatically generated and this requires
-that any feature you implement is well documented following the numpy or restructured text convention.
+For all contributions to :code:`redback` we require a merge request system.
+We also request that you implement some form of a unit test/or example that can be used to test your feature.
+The API documentation is automatically generated and this requires
+that every function/class you implement is well documented following the numpy or restructured text convention.
 
 Before your request is merged, one of the core developers will look through your implementation and suggest any changes if necessary.
 This is to ensure that the software remains consistent and easily maintainable.

docs/dependency_injections.txt

@@ -3,7 +3,7 @@ Making changes to models and plotting using dependency injections
 ======
 
 Several models and classes in :code:`redback` use dependency injections.
-This allows users to easily swap some functionality with their own preferred method while keeping the rest of the infrastructure intact.
+This enables users to easily swap some functionality with their own preferred method while keeping the rest of the infrastructure intact.
 
 Modifying a model physics/Creating a new model
 -------------------------

docs/fitting.txt

@@ -7,19 +7,19 @@ and creating a prior we now come to the exciting part; Fitting the model to data
 
 To fit our model to data we have to specify a sampler and sampler settings.
 The likelihood is set by default depending on the transient/data but one can use a different one
-or write their own as explained in the likelihood `documentation <https://redback.readthedocs.io/en/latest/likelihood.html>`_
+or write their own as explained in the likelihood `documentation <https://redback.readthedocs.io/en/latest/likelihood.html>`_.
 
 Installing :code:`redback` with minimal requirements will install the default sampler `dynesty
 <https://dynesty.readthedocs.io/en/latest/>`_. Installing optional requirements will also install `nestle
-<http://kylebarbary.com/nestle/`_. We generally find `dynesty` to be more reliable/robust but nestle is much faster.
-We note that `dynesty` has checkpointing!
+<http://kylebarbary.com/nestle/>`_. We generally find `dynesty` to be more reliable/robust but nestle is much faster.
+We note that `dynesty` has checkpointing, as do many other samplers.
 
 Samplers
 ---------------
 
 As we use :code:`bilby` under the hood, we have access to several different samplers.
 Cross-checking results with different samplers is often a great way to ensure results are robust
-so we encourage users to install multiple samplers and fit models with different samplers.
+so we encourage users to install multiple samplers and fit with different samplers.
 
 Nested samplers
 
@@ -62,3 +62,7 @@ Here
 - prior: the prior object
 - data_mode: type of data to fit.
 - kwargs: Additional keyword arguments to pass to fit_grb, such as the likelihood, or things required by the sampler, label of the result file, directory where results are saved to etc.
+
+We note that some samplers have multiprocessing,
+which you can see how to use `here https://lscsoft.docs.ligo.org/bilby/api/bilby.core.sampler.run_sampler.html>`_.
+We will soon implement some `GPU` models and :code:`parallel bilby` functionality for more rapid inference workflows.

docs/getting_data.txt

@@ -2,7 +2,7 @@
 Get data
 ============
 
-Redback provides a simple interface to getting data from the open access, Swift, and BATSE catalogs.
+Redback provides a simple interface to getting data from the open access, Swift, and BATSE catalogs, in different formats.
 We will soon add an interface to get data from the Zwicky Transient Facility, and LASAIR.
 
 - Swift: Prompt, X-ray afterglow [counts, flux, flux density]
@@ -25,8 +25,8 @@ Or downloading the flux_density/magnitude data of the kilonova at2017gfo
 
     data = redback.get_data.get_kilonova_data_from_open_transient_catalog_data(transient=kne)
 
-Both these commands return the data, in a pandas dataframe. They also save the raw data and the processed data in a sensible way.
-In particular, the kilonova data will be saved to :code:`kilonova/at2017gfo/` and the afterglow will be saved to :code:`afterglow/GRB070809/flux/`
+Both these commands return the data, in a pandas dataframe. They also save the raw and processed data in a sensible way.
+In particular, the kilonova data will be saved to :code:`kilonova/at2017gfo/` and the afterglow will be saved to :code:`afterglow/GRB070809/flux/`.
 
 Please look at the API or the examples to see how we can get other data.
 
@@ -35,18 +35,20 @@ Basic processing and metadata
 
 We do some basic processing to the raw data to make the files homogenous and save them in a homogenous format.
 We also get metadata about the transient, such as redshift, start time, photon index etc from publically available sources.
-Users can also provide this data themselves.
+Users can also provide this metadata themselves.
 
 Private data or simulated data
 -------------------------
 
 We do not have to use data from the above catalogs for fitting.
 Redback can be used on private data or on simulated data.
-We have written an example demonstrating this `here <https://github.com/nikhil-sarin/redback/blob/master/examples/broadband_afterglow_private_data_example.py>`_
+You can see this in the documentation `here <https://redback.readthedocs.io/en/latest/transients.html>`_.
+We have also written an example demonstrating this `here <https://github.com/nikhil-sarin/redback/blob/master/examples/broadband_afterglow_private_data_example.py>`_ as well.
+
 
 Simulating your own data
 -------------------------
 
 We will soon add an automated interace to simulating data in specific bands/frequencies/flux/luminosity using the in built :code:`redback` models.
 For now, users can use any :code:`redback` model as functions, pass in parameters or a dictionary of parameters, and create their own simulated data.
-See `API <https://redback.readthedocs.io/en/latest/>`_.
+See `Models documentation <https://redback.readthedocs.io/en/latest/models.html>`_.

docs/installation.txt

@@ -23,9 +23,11 @@ Installation
 
 This will install all requirements for running :code:`redback` for general transient fitting, including bilby and our default sampler `dynesty
 <https://dynesty.readthedocs.io/en/latest/>`_. Other samplers will need to be
-installed via pip or the appropriate means. Please look through :code:`redback` `documentation <http://redback.readthedocs.io/>`_ for what samplers are available.
+installed via pip or the appropriate means. Please look through :code:`redback` `fitting documentation <https://redback.readthedocs.io/en/latest/fitting.html>`_ for what samplers are available.
+Currently :code:`redback` is going significant development, and we can not guarantee that any `pip` or `conda` releases will be completely up to date.
+Therefore, for the near future, we recommend installing :code:`redback` from source.
 
-Install redback from source
+Install :code:`redback` from source
 -------------------------
 
 :code:`redback` is developed and tested with Python 3.7+. In the

docs/likelihood.txt

@@ -3,7 +3,11 @@ Likelihood
 ============
 
 By default the likelihood is determined by the type of transient/data being used.
-However, users can choose a different likelihood (assuming they have an edge case which requires a different likelihood).
+However, users can choose a different likelihood. We note that there is typically only one `correct` choice of likelihood but
+there may be edge cases such as errors in time, or non-detections, or uncertain y errors which requires users to use a different likelihood.
+Many different simple to more complicated likelihoods are included in :code:`redback`,
+these should cover most of the cases seen in transient data but if not, users can write their own likelihoods.
+We encourage users to add such likelihoods to :code:`redback`.
 
 Regular likelihoods
 -------------------------

docs/models.txt

@@ -38,6 +38,7 @@ Specifically, the models already included are
     - magnetar + nickel
     - SLSN
     - exponential powerlaw
+    - SNcosmo
 
 - Magnetar boosted ejecta models:
 
@@ -65,7 +66,8 @@ Specifically, the models already included are
     - 1-6 component piecewise power law
     - exponential_powerlaw
 
-We note that these models can output in a range of format set by the keyword argument `output_format` or using the appropriate bolometric/flux function.
+We note that these models can output in `flux_density` or `magnitude` set by the keyword argument
+`output_format` or using the appropriate bolometric/flux function.
 
 Alongside these models we also include some general models which can many of the above models as a `base_model`
 
@@ -101,8 +103,9 @@ For example:
     bolometric_luminosity = function(time, f_nickel=0.6,
                         mej=30, vej=1000, kappa=2, kappa_gamma=1e2)
 
+Here we use `all_models_dict` to provide a simple way to access the relevant function. A user could of course just import the function themselves.
+
 Users can also use the prior objects to get a simulation of the light curves predicted by the function for randomly drawn samples from the prior.
-Here we have also demonstrated the all_models_dict for easy access to all different models.
 
 .. code:: python
 
@@ -121,12 +124,14 @@ Here we have also demonstrated the all_models_dict for easy access to all differ
     bolometric_luminosity = function(time, **samples.iloc[0])
 
 Remember that the priors are simply a dictionary so users could also just pass a dictionary/dataframe they created themselves as well.
+
 Users could also sample a lot of different draws from the prior at once (in the above we randomly drew a 100 samples) and then loop through them to simulate a population.
 Remember that we can only place arbitrary constraints on the priors to make a really specific population/simulation.
 
 Modifying :code:`redback` models
 -------------------------
-A lot of the physics in different redback models is set by default.
+
+A lot of the physics in different :code:`redback` models is set by default.
 However, several different pieces of physics in various models can be changed by either passing your own function/class (see next section),
 by switching the default argument with something else already implemented in redback, or changing a keyword argument.
 
@@ -142,7 +147,7 @@ The specific physics that can be changed:
 - Different photosphere: See photospheres already implemented `here <https://github.com/nikhil-sarin/redback/blob/master/redback/photosphere.py>`_.
 - Different SED: See SED's already implemented `here <https://github.com/nikhil-sarin/redback/blob/master/redback/sed.py>`_.
 
-We encourage users to add more of these, which is another easy way to contribute to :code:`redback`.
+We encourage users to add more of these physics switches, which is another easy way to contribute to :code:`redback`.