Metadata-Version: 2.4
Name: ndspec
Version: 0.2.1
Summary: Multi-dimensional modeling for astrophysical X-ray data
Author-email: Matteo Lucchini <m.lucchini@uva.nl>
Maintainer-email: nDspec Developers <m.lucchini@uva.nl>
License: MIT License
        
        Copyright (c) 2023 Matteo Lucchini
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/nDspec/
Project-URL: Documentation, https://ndspec.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/nDspec/nDspec
Keywords: ndspec,astronomy,x-ray,polarimetry,spectral-timing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: astropy>=5.0.2
Requires-Dist: corner>=2.2.1
Requires-Dist: emcee>=3.1.4
Requires-Dist: lmfit>=1.3.1
Requires-Dist: matplotlib>=3.5.1
Requires-Dist: numpy>=1.17.3
Requires-Dist: scipy>=1.4.0
Requires-Dist: stingray
Requires-Dist: pyfftw
Requires-Dist: tqdm
Provides-Extra: docs
Requires-Dist: sphinx>=1.4; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: pandoc; extra == "docs"
Requires-Dist: nbconvert; extra == "docs"
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Dynamic: license-file

======
nDspec
======

|Docs|

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Multi-dimensional X-ray data modelling in Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

nDspec is a software package designed to model (primarly) X-ray astronomical data; in particular, it is meant to enable users to fit spectral, timing and (in the future) polarimetric data natively. 
Currently, nDspec provides the following features:

- a class to handle folding an energy-dependent model through a given X-ray instrument response matrix. We currently support existing and legacy missions (Swift/XRT, RXTE, NuSTAR, Nicer, XMM-Newton); next-generation missions like XRISM and Athena are not supported yet.
- Classes to handle the standard spectral-timing data products (power spectra, two-dimensional cross spectra, as well as their one-dimensional projections like lag-frequency spectra). Models need to be defined by the user either in the time domain (ie, an impulse response function) or in the Fourier domain (ie, a transfer functions). Additive models can be combined by the users before computing a given Fourier product.
- a small library of phenomenological spectral-timing models, currently including a one dimensional power-law, black body and gaussian, as well as example impulse response and/or transfer functions that parametrize the time dependence of these components.

The goal of the software is to provide users with an Xspec-like package, but to move beyond simple one-dimensional spectral fitting, which typically has relied on each group utilizing their own custom software. Being an open-source modular package, unlike legacy software nDspec allows users to interface with data science libraries for model handling or fitting. 

Documentation
-------------

The software documentation, including installation instructions, tutorials, and the full API, is `found on readthedocs <https://ndspec.readthedocs.io/en/latest/>`_. You can also find notebooks discussing the features of each class in the /notebooks/ folder.

Installation and testing
------------------------

The stable version of the software can be installed via pip; if you want to use (or contribute to!) features that are still in-developement, you should install the software directly from the repository. Unit tests make use of `py.test <https://pytest.org>`_. Running the unit tests simply requires opening the folder in which users downloaded the repository, and running the command `pytest` in the command line. 

Related Packages
----------------

- `STINGRAY <https://github.com/StingraySoftware/stingray>`_ is a library that allows users to produce typical spectral-timing products from observations. A typical use would consist of using Stingray to handle the data a user might be interested in (e.g. by converting event files into data products for modelling), and nDspec to handle modelling of that data.

- `Astropy <https://www.astropy.org/>`_ is the standard library for handling FITS files in a Python environment.

- `emcee <https://emcee.readthedocs.io/en/stable/>`_ implements one of the most commonly used Bayesian sampling algorithms in astronomy. 

- `lmfit <https://lmfit.github.io/lmfit-py/>`_ provides functions, classes and methods for curve optimization, such as least chi-squared fitting. 

Contributing
------------

nDspec is a fully open source software, so we welcome your contribution and feedback!
The best way to contact the developers is through the `issues`_ page - even a simple comment on what you find useful or intuitive (or vice versa) goes a long way in helping the project. 
If you would like to contribute a piece of code, you are welcome to do so either by opening an `issue`_ or submitting a `pull request`_. 

Citing
------

The initial release paper is not released yet; until then, please refer to this repository if you make use of the software in your work.

License
-------

All content © 2023 The Authors. The code is distributed under the MIT license; see `LICENSE <LICENSE>`_ for details.

.. |Docs| image:: https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat
   :target: https://ndspec.readthedocs.io/en/latest/
.. _issues: https://github.com/matteolucchini1/ndspec/issues
.. _issue: https://github.com/matteolucchini1/ndspec/issues
.. _pull request: https://github.com/matteolucchini1/ndspec/pulls
