Merge remote-tracking branch 'origin/conv/utilsTelescopeSupport' into…

… conv/utilsTelescopeSupport

docs/requirements.txt

@@ -15,7 +15,6 @@ Sphinx~=5.0
 nbsphinx
 sphinx_rtd_theme>=0.3.1
 ipython
-ipykernel
 tabulate>=0.8.9
 getdist>=1.1.3
 pytest~=6.2.1

docs/source/conf.py

@@ -108,9 +108,6 @@
 # This should make nbsphinx highlight notebooks better
 highlight_language = 'ipython3'
 
-# This alllows notebooks to run and error - need this for the time being
-nbsphinx_allow_errors = True
-
 
 # -- Options for HTML output -------------------------------------------------
 

docs/source/future.rst

@@ -1,9 +1,7 @@
 Planned XGA Features
 ========================
 
-* **Support for other X-ray telescopes** - XGA's purpose is to facilitate the exploitation of the complete public X-ray archive, hence the aim is to support all X-ray telescopes eventually.
-Currently XMM and eROSITA are supported, and the software is setup so that integrating new telescope-specific softwares should not be an arduous task. If you are interested in integrating 
-a telescope into XGA please reach out to the development team (:doc:`support`). 
+* **Support for other X-ray telescopes** - XGA's purpose is to facilitate the exploitation of the complete public X-ray archive, hence the aim is to support all X-ray telescopes eventually. Currently XMM and eROSITA are supported, and the software is setup so that integrating new telescope-specific softwares should not be an arduous task. If you are interested in integrating a telescope into XGA please reach out to the development team (:doc:`support`). 
 
 * **Creating a Docker image for users to download** - Creating a Docker environment with all relevant software already installed.
 

docs/source/intro.rst

@@ -1,55 +1,84 @@
 Introduction to XGA
 ===================
 
-X-ray: Generate and Analyse (XGA) is a Python module designed to make it easy to analyse X-ray sources.
-It is based around declaring different types of source and sample objects which correspond to real X-ray sources, 
-finding all available data, and then insulating the user from the tedious generation and basic analysis of X-ray data products 
-(though with the option to get stuck into the data directly if required). XGA provides an easy to use Python interface with
-telescope specific software (XMM's Science Analysis System (SAS), eROSITA's eROSITA Science Analysis Software System (eSASS), and XSPEC),
-where all generation and fitting procedures have been parallelised as much as is possible. A major goal of this module is that you 
-shouldn't need to leave a Python environment at any point during your analysis, as all XGA products and fit results are read into 
-an XGA source storage structure. It is not a pipeline in itself, as it can be used for interactive analyses in Jupyter Notebooks, however it is
-quite possible to build pipeline's using XGA's features and methods. 
+X-ray: Generate and Analyse (XGA) is an open source Python module designed for astronomers with the aim to make X-ray astronomy accessible, transparent, and reproducible.
+The main ethos of XGA is to facilitate serendipitous science so that the public X-ray Archive may be fully exploited. It does this by shielding the user from tedious telescope software 
+interaction, and provides a consistent Python interface to generate and analyse X-ray sources from an X-ray dataset. Astronomers across all levels of expertise may use XGA, as it's API is flexible 
+to the users' knowledge base. 
+
+
+How to Use XGA
+---------------
+XGA is an object-orientated module, where the user may declare different types of source and sample objects which correspond to real X-ray sources.  
+Upon instantiation, XGA will find all available data containing these sources, and then insulate the user from interaction with telescope-specific software
+when generating data products such as images and spectra (to name a few). Analysis of these products can also be done through XGA's API - for example fitting models to spectra performed by XSPEC behind the scenes.
+A major goal of this module is that the user shouldn't need to leave a Python environment at any point during X-ray analysis, as all XGA products and fit results are read into 
+an XGA source storage structure. 
+
+.. image:: images/flowchart.png
+
+All generation and fitting procedures have been parallelised as much as is possible, making it a useful tool for pipeline analyses of large samples of sources.
+XGA is also perfect for investigations of indiviual objects, as all generated products are accessed easily, viewed, and fitted through XGA's inbuilt functions. 
 
 
 Generating
 ----------
 
-XGA will generate photometric products (images, exposure maps, and rate maps), spectra, and lightcurves for individual sources,
-or whole samples, with just a few lines of code. XGA generated products are then saved into the source storage structure, so that
+For both individual sources or whole samples, all through a consistent Python interface, XGA can generate:
+
+* Images
+* Exposure maps
+* Rate maps
+* Spectra
+* Lightcurves
+
+XGA generated products are then saved into the source storage structure, so that
 they may be viewed and plotted within Python, and used in subsequent analysis.
 
 Analysing
 ---------
 
-This module also supports more complex analyses for specific object types; the easy generation of scaling relations,
-the measurement of gas masses for galaxy clusters, and the PSF correction of images for instance. It is also
-possible, for extended sources (such as galaxy clusters), to generate and fit sets of annular spectra. This allows you
-to investigate how properties change radially with distance from the centre, and enables the measurement of hydrostatic
-masses of clusters.
+Once the neccessary products have been generated, further analysis may be performed. Through XGA the user can:
 
-Multi-Mission XGA
------------------
+* Fit models to spectra via XSPEC
+* Yield temperature, luminosity, and photon index values from these fits
+* Apply PSF corrections to images
+* Calculate count rates and fluxes
+* Find X-ray peaks of sources
+* Fit radial profiles of temperature, density, and metallicity 
+
+For specific source types, more complex analysis options are available. For galaxy clusters the user may:
+
+* Generate scaling relations
+* Measure a gas mass
+* Fit sets of annular spectra (this can be done for any extended source)
+* Measure a hydrostatic mass
+
+
+Multi-Mission Data
+------------------
 
 The user may provide XGA with a dataset containing observations from multiple X-ray missions, so that any 
-product generatation and analysis will utilise all the X-ray missions the user has data for. 
-Currently XGA supports XMM and eROSITA. Combining products from different telescopes is not yet possible 
-through XGA. To see full details of XGA treatment of different missions see the :doc:`multi` section.
+product generatation and analysis will utilise all the X-ray telescopes that the user has data for. 
+
+.. image:: images/mulitmission.png
+
+Currently XGA supports interaction with:
 
-.. image:: images/intro.png
+* **XMM** via Science Analysis System (SAS)
+* **eROSITA** via eROSITA Science Analysis Software System (eSASS) 
 
-For example in the diagram below, at step 1, the user is declaring a source. XGA searches the dataset
-and find that the source lies in one eROSITA observation (Obs1), and two XMM observations (Obs3, and Obs4). Then in step 2
-when the user uses XGA to make a product for that source, three products are made for each associated observation.
+The long term aim is to support all X-ray telescope's data, if you are interested in helping integrate your favourite X-ray telescope please do get in contact. 
+To see full details of XGA treatment of different missions see the :doc:`multi` section.
 
 Crediting
 ---------
 
-While XGA is a piece of open source software, I would appreciate it if any work that makes use of it would cite the
+While XGA is a piece of open source software, it would be appreciated if any work that makes use of it would cite the
 paper accompanying this package, which can be found in the :doc:`publications` section.
 
 Contributing
 ------------
 
-If wish to contribute to XGA, have feature suggestions, or any comments at all, then please go to the
-"Getting Support" section and submit an issue on GitHub/send me an email, I'll be happy to hear from you!
+If you wish to contribute to XGA, have feature suggestions, or any comments at all, then please go to the
+"Getting Support" section and submit an issue on GitHub/email the development team, we will be happy to hear from you!