Merge pull request #57 from JulienPeloton/readme_update

Update the README with better Statement of Needs

README.rst

@@ -10,6 +10,9 @@ s4cmb
 
 .. image:: https://coveralls.io/repos/github/JulienPeloton/s4cmb/badge.svg?branch=master
     :target: https://coveralls.io/github/JulienPeloton/s4cmb?branch=master
+
+.. image:: https://joss.theoj.org/papers/8ff011dd5336a30d175b69c7b63908ab/status.svg
+    :target: https://joss.theoj.org/papers/8ff011dd5336a30d175b69c7b63908ab
 
 .. raw:: html
 
@@ -19,34 +22,38 @@ s4cmb
 
 The package
 ===============
-Systematics For Cosmic Microwave Background (s4cmb), is a package to
-study instrumental systematic effects in the context of current and future
-Cosmic Microwave Background experiments. Currently accessible:
+Systematics For Cosmic Microwave Background (`s4cmb`) is a Python package developed to study the impact of instrumental systematic effects on measurements of CMB experiments based on bolometric detector technology.
+`s4cmb` provides a unified framework to simulate raw data streams in the time domain (TODs) acquired by CMB experiments scanning the sky, and to inject in these realistic instrumental systematics effect.
+The development of `s4cmb` is built on experience and needs of the analysis of
+data of the Polarbear ground-based experiment (see e.g. `1403.2369 <https://arxiv.org/abs/1403.2369>`_ and `1705.02907 <https://arxiv.org/abs/1705.02907>`_).
+It is designed to analyze real data, to guide the design of future instruments that require the estimation of specific systematic effects as well as to increase the realism of simulated data sets required in the development of data analysis methods. Users can currently model and study: 
 
 * Electrical crosstalk in the multiplexed readout.
 * Relative gain-calibration uncertainty between the two detectors in a focal plane pixel.
 * Time drift of the gains between two consecutive calibration measurements.
 * Differential pointing between the two detectors in a pixel.
 * ... more to come!
 
+The simplicity of the `s4cmb` framework allows to easily add new instrumental systematics to be simulated according to the users' needs.
+As far as we know, s4cmb is the only dedicated package that enables the study of a wide range of instrumental simulations, from the instrument to the sky map, while being publicly available. For more general purposes, including some instrumental systematic effect simulations, users might also consider the use of `TOAST <https://github.com/hpc4cmb/toast>`_, a software framework to simulate and process timestream data collected by telescopes focusing on efficient TOD manipulation on massively parallel architectures.
+
+
 Requirements
 ===============
-The pipeline is mainly written in python (>= 3.6) and it has the following dependencies (see requirements.txt):
+The package is mainly written in python (>= 3.6), and it adopts several commonly used libraries in astronomy (`astropy`, `healpy`, `ephem`, `pyslalib`) and uses functions based on low-level languages wrapped in Python (e.g. Fortran with `f2py`) for speeding up the most critical part of the code without losing the flexibility provided by a simple python user-friendly interface. It has the following dependencies (see requirements.txt):
 
 * numpy, matplotlib
 * astropy, ephem, pyslalib, healpy (astro libs)
 * f2py (interfacing with python)
 
-Some parts of the pipeline are written in Fortran which is interfaced with
-python using f2py. The compilation is done usually when you install the
+The compilation of Fortran parts is done usually when you install the
 package (see setup.py), but we also provide a Makefile for more
 customized compilations (see the Makefile in s4cmb).
 
 Installation
 ===============
 
-The type of installation depends on what you want to do with the code:
-just using it or also developing it?
+`s4cmb` is designed to be employed on systems of varying scale, from laptops to parallel supercomputing platforms thanks to its internal Message Passing Interface (MPI) support. We also support packaging the entire application into a Docker container for portability. 
 
 **I just want to use the code:**
 
@@ -159,7 +166,7 @@ Thanks to
 In the literature
 ===============
 
-s4cmb has been used in several research projects:
+The package has already been used in a number of scientific and technical publications:
 
 * Instrumental systematics biases in CMB lensing reconstruction: a simulation-based assessment (`2011.13910 <https://arxiv.org/abs/2011.13910>`_)
 * Development of Calibration Strategies for the Simons Observatory (`1810.04633 <https://arxiv.org/abs/1810.04633>`_)