1########################################################################################################################
 2# Copyright 2023 the authors (see AUTHORS file for full list).                                                         #
 3#                                                                                                                      #
 4# This file is part of shapelets.                                                                                      #
 5#                                                                                                                      #
 6# Shapelets is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General       #
 7# Public License as published by the Free Software Foundation, either version 2.1 of the License, or (at your option)  #
 8# any later version.                                                                                                   #
 9#                                                                                                                      #
10# Shapelets is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied      #
11# warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more  #
12# details.                                                                                                             #
13#                                                                                                                      #
14# You should have received a copy of the GNU Lesser General Public License along with shapelets. If not, see           #
15# <https://www.gnu.org/licenses/>.                                                                                     #
16########################################################################################################################
17
18r"""
19
20# shapelets
21
22[![DOI](https://joss.theoj.org/papers/10.21105/joss.06058/status.svg)](https://doi.org/10.21105/joss.06058)
23
24## What is shapelets? 
25
26Shapelets is a Python package that implements several shapelet functions and some of their significant applications in science and astronomy. Shapelet functions are a complete and orthogonal set of localized basis functions with mathematical properties convenient for manipulation and analysis of images from a broad range of applications.
27
28Due to these properties, they have seen extensive use in recent years, including:
29
30* Astronomy/astrophysics ([A. Refregier (2003)](https://doi.org/10.1046/j.1365-8711.2003.05901.x), [R. Massey (2005)](https://doi.org/10.48550/arXiv.astro-ph/0408445), [J. Berge (2019)](https://doi.org/10.48550/arXiv.1903.05837))
31* Self-assembled nanomaterials ([R. Suderman (2015)](http://dx.doi.org/10.1103/PhysRevE.91.033307), [T. Akdeniz (2018)](https://doi.org/10.1088/1361-6528/aaf353), [M. P. Tino (2024)](http://dx.doi.org/10.1088/1361-6528/ad1df4))
32* Computational neuroscience ([J. D. Victor (2006)](https://doi.org/10.1152/jn.00498.2005), [T. O. Sharpee (2009)](https://doi.org/10.1007%2Fs10827-008-0107-5))
33* Medical imaging ([J. Weissman (2004)](https://doi.org/10.1364/OPEX.12.005760))
34
35The shapelets package provides reference code and documentation for 4 shapelet function definitions: 
36
37* Cartesian shapelets ([A. Refregier (2003)](https://doi.org/10.1046/j.1365-8711.2003.05901.x)), 
38* Polar shapelets ([R. Massey (2005)](https://doi.org/10.48550/arXiv.astro-ph/0408445)),
39* Orthonormal polar shapelets with constant radial scale ([T. Akdeniz (2018)](https://doi.org/10.1088/1361-6528/aaf353)), and 
40* Exponential shapelets ([J. Berge (2019)](https://doi.org/10.48550/arXiv.1903.05837))
41
42## Getting Started
43
44New users should kindly follow these instructions to use the shapelets package:
45
461. If you have Python 3.10+ installed, you can install the shapelets package via pip from your terminal/command line: `pip install shapelets` 
472. If you do not have Python 3.10+ installed, consult the [installation guide](https://uw-comphys.github.io/shapelets/shapelets/docs/installation_guide.html) for helpful instructions on Linux, Mac OS, and Windows machines.
483. Consult the [examples](https://uw-comphys.github.io/shapelets/shapelets/docs.html) to see specific applications implemented in the package and a walkthrough of how to interact with the package correctly.
494. Checkout other documentation, such as
50    * [Custom Commands](https://uw-comphys.github.io/shapelets/shapelets/docs/custom_commands.html) - describes command-line arguments specifically designed for this package
51    * [Package Interface](https://uw-comphys.github.io/shapelets/shapelets/docs/package_interface.html) - describes two different ways of using the `shapelets` package (configuration files or traditional Python programming)
52
53If you plan to use the shapelets package for your own work, please cite appropriately using the [citation](#citation) below.
54
55## Issues
56
57If you encounter any **bugs** or **problems** with shapelets, please create a post using our package [issue tracker](https://github.com/uw-comphys/shapelets/issues). Please provide a clear and concise description of the problem, with images or code-snippets where appropriate. We will do our best to address these problems as fast and efficiently as possible.
58
59## Contribute
60
61The authors of the shapelets package welcome external contributions to the source code. This process will be easiest if users adhere to the contribution policy:
62
63* Open an issue on the package [issue tracker](https://github.com/uw-comphys/shapelets/issues) clearly describing your intentions on code modifications or additions
64* Ensure your modifications or additions adhere to the existing standard of the shapelets package, specifically detailed documentation for new methods (see existing methods for example documentation)
65* Test your modifications to ensure that the core functionality of the package has not been altered by running the unit tests via the custom command: `shapelets-test`
66* Once the issue has been discussed with a package author, you may open a pull request containing your modifications
67
68## Citation
69
70If you plan to use shapelets in your own work, please cite using the following Bibtex citation:
71
72```
73@article{TinoShapelets2024,
74author = {Tino, Matthew Peres and Abdulaziz, Abbas Yusuf and Suderman, Robert and Akdeniz, Thomas and Abukhdeir, Nasser Mohieddin},
75title = {Shapelets: A Python package implementing shapelet functions and their applications},
76doi = {10.21105/joss.06058},
77journal = {Journal of Open Source Software},
78number = {95},
79pages = {6058},
80volume = {9},
81year = {2024},
82url = {https://joss.theoj.org/papers/10.21105/joss.06058}
83}
84```
85
86## Authors
87
88* Matthew Peres Tino (mptino@uwaterloo.ca)
89* Abbas Yusuf Abdulaziz 
90* Nasser Mohieddin Abukhdeir
91* Robert Suderman 
92* Thomas Akdeniz
93
94"""