diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..35d7ecc8 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,31 @@ +name: docs + +on: [push, pull_request, workflow_dispatch] + +permissions: + contents: write + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + - name: Install dependencies + run: | + sudo apt install pandoc + pip install sphinx sphinx_rtd_theme nbsphinx mock + - name: Sphinx build + run: | + make -C docs html + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/docs' }} + with: + publish_branch: gh-pages + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/_build/html + force_orphan: true + diff --git a/README.md b/README.md index 7b53f064..ad62580b 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,10 @@ # cosipy -The COSI high-level data analysis tools -## Installation from source +The cosipy library is [COSI](https://cosi.ssl.berkeley.edu)'s high-level analysis software. -Meant for developers. Currently the only option. +The main repository is hosted in https://github.com/cositools/cosipy -1. Clone the repository into your local machine +For the cosipy installation and usage instructions please refer to the main [cosipy documentation](https://cositools.github.io/cosipy/). -``` -git clone git@github.com:cositools/cosipy.git -``` -2. Move to the cosipy folder -``` -cd cosipy -``` - -3. Create a new conda environment. Optional but highly encouranged. - -4. Install it: - -``` -pip install -e . -``` diff --git a/cosipy/response/FullDetectorResponse.py b/cosipy/response/FullDetectorResponse.py index 3a6e21d0..06c7ce9a 100644 --- a/cosipy/response/FullDetectorResponse.py +++ b/cosipy/response/FullDetectorResponse.py @@ -835,7 +835,7 @@ def get_point_source_response(self, Effective time spent by the source at each pixel location in spacecraft coordinates coord : :py:class:`astropy.coordinates.SkyCoord` Source coordinate - scatt_map : :py:cass:`SpacecraftAttitudeMap` + scatt_map : :py:class:`SpacecraftAttitudeMap` Spacecraft attitude map Returns diff --git a/cosipy/threeml/COSILike.py b/cosipy/threeml/COSILike.py index dc7f8b17..3fa27e6a 100644 --- a/cosipy/threeml/COSILike.py +++ b/cosipy/threeml/COSILike.py @@ -34,34 +34,33 @@ logger = logging.getLogger(__name__) class COSILike(PluginPrototype): - + """ + COSI 3ML plugin. + + Parameters + ---------- + name : str + Plugin name e.g. "cosi". Needs to have a distinct name with respect to other plugins in the same analysis + dr : str + Path to full detector response + data : histpy.Histogram + Binned data. Note: Eventually this should be a cosipy data class + bkg : histpy.Histogram + Binned background model. Note: Eventually this should be a cosipy data class + sc_orientation : cosipy.spacecraftfile.SpacecraftFile + Contains the information of the orientation: timestamps (astropy.Time) and attitudes (scoord.Attitude) that describe + the spacecraft for the duration of the data included in the analysis + nuisance_param : astromodels.core.parameter.Parameter, optional + Background parameter + coordsys : str, optional + Coordinate system ('galactic' or 'spacecraftframe') to perform fit in, which should match coordinate system of data + and background. This only needs to be specified if the binned data and background do not have a coordinate system + attached to them + precomputed_psr_file : str, optional + Full path to precomputed point source response in Galactic coordinates + """ def __init__(self, name, dr, data, bkg, sc_orientation, nuisance_param=None, coordsys=None, precomputed_psr_file=None, **kwargs): - """ - COSI 3ML plugin. - - Parameters - ---------- - name : str - Plugin name e.g. "cosi". Needs to have a distinct name with respect to other plugins in the same analysis - dr : str - Path to full detector response - data : histpy.Histogram - Binned data. Note: Eventually this should be a cosipy data class - bkg : histpy.Histogram - Binned background model. Note: Eventually this should be a cosipy data class - sc_orientation : cosipy.spacecraftfile.SpacecraftFile - Contains the information of the orientation: timestamps (astropy.Time) and attitudes (scoord.Attitude) that describe - the spacecraft for the duration of the data included in the analysis - nuisance_param : astromodels.core.parameter.Parameter, optional - Background parameter - coordsys : str, optional - Coordinate system ('galactic' or 'spacecraftframe') to perform fit in, which should match coordinate system of data - and background. This only needs to be specified if the binned data and background do not have a coordinate system - attached to them - precomputed_psr_file : str, optional - Full path to precomputed point source response in Galactic coordinates - """ # create the hash for the nuisance parameters. We have none for now. self._nuisance_parameters = collections.OrderedDict() diff --git a/docs/api/coordinates.rst b/docs/api/coordinates.rst deleted file mode 100644 index a18a4a6b..00000000 --- a/docs/api/coordinates.rst +++ /dev/null @@ -1,4 +0,0 @@ -Coordinates -=========== - -The cosipy library uses :py:mod:`astropy.coordinates`. diff --git a/docs/api/data_io.rst b/docs/api/data_io.rst new file mode 100644 index 00000000..070dc7d7 --- /dev/null +++ b/docs/api/data_io.rst @@ -0,0 +1,8 @@ +Data IO +======= + +.. automodule:: cosipy.data_io + :imported-members: + :members: + :undoc-members: + diff --git a/docs/api/image_deconvolution.rst b/docs/api/image_deconvolution.rst new file mode 100644 index 00000000..b2c43491 --- /dev/null +++ b/docs/api/image_deconvolution.rst @@ -0,0 +1,7 @@ +Image deconvolution +=================== + +.. automodule:: cosipy.image_deconvolution + :imported-members: + :members: + :undoc-members: diff --git a/docs/api/index.rst b/docs/api/index.rst index bde41e45..bccae241 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -1,9 +1,23 @@ API === +This is cosipy's Application Programming Interface (API). It is an exhaustive list of all available classes and their properties, as well as the inputs and outputs of each method. + +If you are instead interested in an overview on how to use cosipy, see out `tutorial series instead <../tutorials/index.html>`_. + +.. warning:: + Under construction. The description of some methods is still missing. If you need the description of a particular class, please open an `issue `_ so we can prioritize it. + .. toctree:: :maxdepth: 2 :caption: Contents: response - coordinates + data_io + spacecraftfile + threeml + ts_map + image_deconvolution + + + diff --git a/docs/api/spacecraftfile.rst b/docs/api/spacecraftfile.rst new file mode 100644 index 00000000..e4026261 --- /dev/null +++ b/docs/api/spacecraftfile.rst @@ -0,0 +1,9 @@ +Spacecraft File +=============== + +.. automodule:: cosipy.spacecraftfile + :imported-members: + :members: + :undoc-members: + + diff --git a/docs/api/threeml.rst b/docs/api/threeml.rst new file mode 100644 index 00000000..17b56f72 --- /dev/null +++ b/docs/api/threeml.rst @@ -0,0 +1,10 @@ +COSILike (3ML plugin) +===================== + +ThreeML plugin + +.. automodule:: cosipy.threeml + :imported-members: + :members: + :undoc-members: + diff --git a/docs/api/ts_map.rst b/docs/api/ts_map.rst new file mode 100644 index 00000000..0b344778 --- /dev/null +++ b/docs/api/ts_map.rst @@ -0,0 +1,7 @@ +TS Map +====== + +.. automodule:: cosipy.ts_map + :imported-members: + :members: + :undoc-members: diff --git a/docs/conf.py b/docs/conf.py index 49dc103f..57a82fdb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,11 +10,9 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - -import cosipy +import os +import sys +sys.path.insert(0, os.path.abspath('..')) # -- Project information ----------------------------------------------------- @@ -23,7 +21,8 @@ author = 'COSI Team' # The full version, including alpha/beta/rc tags -release = cosipy.__version__ +with open('../cosipy/_version.py') as f: + release = f.readline() # -- General configuration --------------------------------------------------- @@ -50,16 +49,46 @@ # The master toctree document. master_doc = 'index' -# intersphinx +# mock dependencies so we don't have to install them +autodoc_mock_imports = ["histpy", + 'threeML', + 'astromodels', + 'past', + 'numpy', + 'h5py', + 'astropy', + 'healpy', + 'mhealpy', + 'sparse', + 'matplotlib', + 'yaml', + 'scoords', + 'pandas', + 'tqdm', + 'scipy'] + +# There seems to be a conflict between unittest.mock (used by sphinx) and metaclasses +# The cosipy.threeml.custom_functions.Band_Eflux includes a metaclass from +# astromodels.functions.function, so we mock that one manually with the mock package +import mock + +MOCK_MODULES = ['astromodels.functions.function'] +for mod_name in MOCK_MODULES: + sys.modules[mod_name] = mock.Mock() + +# intersphinx for mocked dependencies intersphinx_mapping = { 'histpy': ('https://histpy.readthedocs.io/en/latest', None), + 'threeML': ('https://threeml.readthedocs.io/en/latest/', None), + 'astromodels': ('https://astromodels.readthedocs.io/en/latest/', None), + 'numpy': ('https://numpy.org/doc/stable/', None), 'h5py' : ('https://docs.h5py.org/en/stable/', None), 'astropy' : ('https://docs.astropy.org/en/stable', None), 'python' : ('https://docs.python.org/3', None), 'mhealpy' : ('https://mhealpy.readthedocs.io/en/latest/', None), 'sparse' : ('https://sparse.pydata.org/en/stable/', None), - 'gammapy' : ('https://docs.gammapy.org/dev', None), + 'matplotlib' : ('https://matplotlib.org/stable/', None), 'scipy' : ('https://scipy.github.io/devdocs', None), } @@ -87,29 +116,3 @@ # Extensions to theme docs -# Fix issue with Napoleon RTD that displays "Variables" instead of "Attributes" -# credit - https://michaelgoerz.net/notes/extending-sphinx-napoleon-docstring-sections.html - -from sphinx.ext.napoleon.docstring import GoogleDocstring - -# first, we define new methods for any new sections and add them to the class -def parse_keys_section(self, section): - return self._format_fields('Keys', self._consume_fields()) -GoogleDocstring._parse_keys_section = parse_keys_section - -def parse_attributes_section(self, section): - return self._format_fields('Attributes', self._consume_fields()) -GoogleDocstring._parse_attributes_section = parse_attributes_section - -def parse_class_attributes_section(self, section): - return self._format_fields('Class Attributes', self._consume_fields()) -GoogleDocstring._parse_class_attributes_section = parse_class_attributes_section - -# we now patch the parse method to guarantee that the the above methods are -# assigned to the _section dict -def patched_parse(self): - self._sections['keys'] = self._parse_keys_section - self._sections['class attributes'] = self._parse_class_attributes_section - self._unpatched_parse() -GoogleDocstring._unpatched_parse = GoogleDocstring._parse -GoogleDocstring._parse = patched_parse diff --git a/docs/index.rst b/docs/index.rst index 7b30e5ea..bcd86f08 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,11 +1,34 @@ Welcome to cosipy's documentation! ================================== +The cosipy library is `COSI `_'s high-level analysis software. It allows you to extract imaging and spectral information from the data, as well as to perform statistical model comparisons. The cosipy products are meant to be ready for interpretation. + +The main repository is hosted at https://github.com/cositools/cosipy + +In the following sections you will find: + +- Installation instructions +- A tutorial series explaining the basics of various components of cosipy +- Further usage examples +- The Application Programming Interface (API), describes the various available classes, their properties, and usage. + +.. warning:: + While many features are already available, cosipy is still actively under development. COSI is scheduled to launch in 2027. In preparation, the cosipy team will be releasing alpha versions with approximately an annual cadence. Your feedback will be greatly appreciated! Note, however, that these are not stable releases and various components can be modified or deprecated shortly. + + +Contributing +------------ + +Cosipy is open-source and anyone can contribute. It doesn't matter if you are part of the COSI team or an external contributor. + +The preferred communication channel is the GitHub repository:: if you find a problem, please report it by opening an issue; if you have a question or an idea on how to collaborate, please open a discussion; if you have code to contribute, please fork the repository and open a pull request. + + .. toctree:: :maxdepth: 2 :caption: Contents: install - tutorials/Intro.ipynb tutorials/index + tutorials/other_examples api/index diff --git a/docs/install.rst b/docs/install.rst index 9cc67d5b..9225aae5 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,9 +1,40 @@ Installation ============ -For developers --------------- +Using pip +--------- +Optional but recommended step: install a conda environment:: + + conda create -n python=3.10 pip + conda activate + +Note: currently cosipy is not compatible with Python 3.11 and 3.12, mainly due to +installation issues with a dependency (astromodels, see issues `#201 `_ and `#204 `_) + +Install with pip:: + + pip install cosipy==0.0.2a1 + +Note: you need to specify the alpha release 0.0.2a1, otherwise pip will fall back to +the latest regular release (which is currently unusable). This will be updated when +we have our next regular release. + + +From source (for developers) +---------------------------- + +Optional but recommended step: install a conda environment:: + + conda create -n python=3.10 pip + conda activate + +Also optional but recommended: before installing cosipy, install the main +dependencies from the source (similar +procedure as for cosipy below). These are histpy, mhealpy, scoords, threeml and +astromodels. The reason is that these libraries might be changing rapidly to +accommodate new features in cosipy. + Do the following (preferably inside a conda environment):: git clone git@github.com:cositools/cosipy.git @@ -16,6 +47,9 @@ having to run ``pip`` again. Testing ....... +.. warning:: + Under construction. Unit tests are not ready. + When you make a change, check that it didn't break something by running:: pytest --cov=cosipy --cov-report term --cov-report html:tests/coverage_report @@ -31,14 +65,15 @@ You can install ``pytest`` and ``pytest-cov`` with:: Compiling the docs ------------------ -You need sphinx, nbsphinx and sphinx_rtd_theme. Using conda:: +You need pandoc, sphinx, nbsphinx, sphinx_rtd_theme and mock. Using conda:: - conda install -c conda-forge nbsphinx sphinx_rtd_theme + conda install -c conda-forge pandoc nbsphinx sphinx_rtd_theme mock -Onece you have this requirements, run:: +Once you have these requirements, run:: cd docs make html To read the documentation, open ``docs/_build/html/index.html`` in a browser. + diff --git a/docs/tutorials/image_deconvolution/511keV/ScAttBinning/511keV-DC2-ScAtt-ImageDeconvolution.ipynb b/docs/tutorials/image_deconvolution/511keV/ScAttBinning/511keV-DC2-ScAtt-ImageDeconvolution.ipynb index 320100e8..bfaf923b 100644 --- a/docs/tutorials/image_deconvolution/511keV/ScAttBinning/511keV-DC2-ScAtt-ImageDeconvolution.ipynb +++ b/docs/tutorials/image_deconvolution/511keV/ScAttBinning/511keV-DC2-ScAtt-ImageDeconvolution.ipynb @@ -385,7 +385,7 @@ "tags": [] }, "source": [ - "# 0. Files needed for this notebook\n", + "## 0. Files needed for this notebook\n", "\n", "From wasabi\n", "- cosi-pipeline-public/COSI-SMEX/DC2/Responses/SMEXv12.511keV.HEALPixO4.binnedimaging.imagingresponse.nonsparse_nside16.area.h5\n", @@ -405,7 +405,7 @@ "id": "6c259412", "metadata": {}, "source": [ - "# 1. Read the response matrix" + "## 1. Read the response matrix" ] }, { @@ -495,7 +495,7 @@ "id": "26d6eb3a", "metadata": {}, "source": [ - "# 2. Read binned 511keV binned files (source and background)" + "## 2. Read binned 511keV binned files (source and background)" ] }, { @@ -520,7 +520,7 @@ "data_bkg = BinnedData(\"inputs_511keV_DC2.yaml\")\n", "data_bkg.load_binned_data_from_hdf5(\"511keV_scatt_binning_DC2_bkg.hdf5\")\n", "\n", - "# signal + background\n", + "## signal + background\n", "data_511keV = BinnedData(\"inputs_511keV_DC2.yaml\")\n", "data_511keV.load_binned_data_from_hdf5(\"511keV_scatt_binning_DC2_event.hdf5\")" ] @@ -532,7 +532,7 @@ "tags": [] }, "source": [ - "# 3. Load the coordsys conversion matrix" + "## 3. Load the coordsys conversion matrix" ] }, { @@ -561,7 +561,7 @@ "id": "31ec05ad-90b7-4fad-9ad0-98cfd6483d41", "metadata": {}, "source": [ - "# 4. Imaging deconvolution" + "## 4. Imaging deconvolution" ] }, { @@ -569,7 +569,7 @@ "id": "6e88ca7f", "metadata": {}, "source": [ - "## Brief overview of the image deconvolution\n", + "### Brief overview of the image deconvolution\n", "\n", "Basically, we have to maximize the following likelihood function\n", "\n", @@ -626,7 +626,7 @@ "id": "e0a2582e", "metadata": {}, "source": [ - "## 4-1. Prepare DataLoader containing all neccesary datasets" + "### 4-1. Prepare DataLoader containing all neccesary datasets" ] }, { @@ -694,7 +694,7 @@ "id": "2a662f5e", "metadata": {}, "source": [ - "## 4-2. Load the response file\n", + "### 4-2. Load the response file\n", "\n", "The response file will be loaded on the CPU memory. It requires a few GB. In the actuall analysis, the response will be much larger, ~TB. \n", "\n", @@ -753,7 +753,7 @@ "id": "b1a0269e", "metadata": {}, "source": [ - "## 4-3. Initialize the instance of the image deconvolution class\n", + "### 4-3. Initialize the instance of the image deconvolution class\n", "\n", "First we prepare an instance of ImageDeconvolution class, and then, resister the dataset, parameters for the deconvolution. After that, you can start the calculation." ] @@ -1021,7 +1021,7 @@ "id": "f764066e", "metadata": {}, "source": [ - "## 4-5. Start the image deconvolution" + "### 4-5. Start the image deconvolution" ] }, { @@ -1753,7 +1753,7 @@ "id": "9d32d0a8", "metadata": {}, "source": [ - "# 5. Analyze the results\n", + "## 5. Analyze the results\n", "Below examples to see/analyze the results are shown." ] }, @@ -1762,7 +1762,7 @@ "id": "f577c7ac", "metadata": {}, "source": [ - "## Log-likelihood\n", + "### Log-likelihood\n", "\n", "Plotting the log-likelihood vs the number of iterations" ] @@ -1803,7 +1803,7 @@ "id": "3f085706", "metadata": {}, "source": [ - "## Alpha (the factor used for the acceleration)\n", + "### Alpha (the factor used for the acceleration)\n", "\n", "Plotting $\\alpha$ vs the number of iterations. $\\alpha$ is a parameter to accelerate the EM algorithm (see the beginning of Section 4). If it is too large, reconstructed images may have artifacts." ] @@ -1844,7 +1844,7 @@ "id": "b3298aa5", "metadata": {}, "source": [ - "## Background normalization\n", + "### Background normalization\n", "\n", "Plotting the background nomalization factor vs the number of iterations. If the backgroud model is accurate and the image is reconstructed perfectly, this factor should be close to 1." ] @@ -1885,7 +1885,7 @@ "id": "58e0d3a6", "metadata": {}, "source": [ - "## The reconstructed images" + "### The reconstructed images" ] }, { diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index e95e6314..50a9f8ab 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -1,11 +1,76 @@ Tutorials ========= -Tutorial for various components of the `cosipy` library. These are Python -notebooks that you can execute interactively. +This is a series of tutorials explaining step by step the various components of the `cosipy` library and how to use it. Although they are rendered as a webpage here, these are interactive Python notebooks (ipynb) that you can execute and modify, distributed as part of the cosipy repository. +If you are interested instead of the description of each class and method, please see our `API <../api/index.html>`_ section. + +List of tutorials and contents, as a link to the corresponding Python notebook in the repository: + +1. Data format and handling `(ipynb) `_ + + - Data format, binned and unbinned + - Binning the data in both local and galactic coordinates + - Combining files. + - Inspecting and plotting the data + +2. Spacecraft orientation and location `(ipynb) `_ + + - SC file format and manipulation it —e.g. get a time range, rebin it. + - The dwell time map and how to obtain it + - The scatt map and how to obtain it + +3. Detector response and signal expectation `(ipynb) `_ + + - Explanation of the detector response format and meaning + - Visualizing the response + - Convolving the detector response with a point source model (location + spectrum) + spacecraft file to obtain the expected signal counts. Both in SC and galactic coordinates. + +4. TS Map: localizing a GRB `(ipynb) `_ + - TS calculation + - Meaning of the TS map and how to compute confidence contours + - Computing a TS map, getting the best location and estimating the error + +5. Fitting the spectrum of a GRB `(ipynb) `_ + + - Introduction to 3ML and astromodels + - Likelihood analysis. + - Mechanics of background estimation. + - Fitting a simple power law, assuming you know the time of the GRB + - Plotting the result + - Comparing the result with the data + +6. Fitting the spectrum of the Crab `(ipynb) `_ + + - Analysing a continuous source transiting in the sky. + +7. Extended source model fitting `(ipynb) `_ + + - Obtaining the extended source response as a convolution of multiple point sources + - Pre-computing a response in galactic coordinates for all-sky + - Fitting an extended source + +8. Image deconvolution `(ipynb) `_ + - Explain the RL algorithm. Reference the previous example. Explain the difference with a TS map. + - Scatt binning and its advantages/disadvantages + - Fitting the 511 diffuse emission. + +9. TODO: Source injector + - Nice to have: allow theorist to test the sensitivity of their models + +.. warning:: + Under construction. Some of the explanations described above might be missing. However, the notebooks are fully functional. If you have a question not yet covered by the tutorials, please discuss `issue `_ so we can prioritize it. + .. toctree:: :maxdepth: 1 - DetectorResponse.ipynb - + Data format and handling + Spacecraft orientation and location + Detector response and signal expectation + TS Map: localizing a GRB + Fitting the spectrum of a GRB + Fitting the spectrum of the Crab + Extended source model fitting + Image deconvolution + + diff --git a/docs/tutorials/other_examples.rst b/docs/tutorials/other_examples.rst new file mode 100644 index 00000000..c460132e --- /dev/null +++ b/docs/tutorials/other_examples.rst @@ -0,0 +1,11 @@ +Other examples +============== + +.. warning:: + Under construction. + +.. toctree:: + :maxdepth: 1 + + spectral_fits/line_fit/SpectralFit_Line.ipynb +