Package: maxsmooth
maxsmooth:Derivative Constrained Function FittingAuthor:Harry Thomas Jones BevinsVersion:1.2.1Homepage:https://github.com/htjb/maxsmoothDocumentation:https://maxsmooth.readthedocs.io/InstallationIn the following two sections we highlight the purpose ofmaxsmoothand
show an example. To install the software follow these instructions:The software can be pip installed from the PYPI repository like so,pip install maxsmoothor alternatively it can be installed from the git repository via,git clone https://github.com/htjb/maxsmooth.git
cd maxsmooth
python setup.py install --userDerivative Constrained Functions andmaxsmoothmaxsmoothis an open source software, written in Python (supporting version 3 upwards),
for fitting derivative constrained
functions (DCFs) such as Maximally Smooth Functions
(MSFs) to data sets. MSFs are functions for which there are no zero
crossings in derivatives of order m >= 2 within the domain of interest.
More generally for DCFs the minimum
constrained derivative order, m can take on any value or a set of
specific high order derivatives can be constrained.
They are designed to prevent the loss of
signals when fitting out dominant smooth foregrounds or large magnitude signals that
mask signals of interest. Here “smooth” means that the foregrounds follow power
law structures in the band of interest.
In some cases DCFs can be used to
highlight systematics in the data.maxsmoothuses quadratic programming implemented withCVXOPTto fit
data subject to a fixed linear constraint, Ga <= 0, where the product
Ga is a matrix of derivatives.
The constraint on an MSF are not explicitly
linear and each constrained derivative can be positive or negative.maxsmoothis, however, designed to test the <= 0 constraint multiplied
by a positive or negative sign. Where a positive sign in front of the mthorder derivative forces the derivative
to be negative for all x. For an Nthorder polynomialmaxsmoothcan test
every available sign combination but by default it implements a sign navigating algorithm.
This is detailed in themaxsmoothpaper (see citation), is summarized
below and in the software documentation.The available sign combinations act as discrete parameter spaces all with
global minima andmaxsmoothis capable of finding the minimum of these global
minima by implementing a cascading algorithm which is followed by a directional
exploration. The cascading routine typically finds an approximate to the global
minimum and then the directional exploration is a complete search
of the sign combinations in the neighbourhood
of that minimum. The searched region is limited by factors
that encapsulate enough of the neighbourhood to confidently return the global minimum.The sign navigating method is reliant on the problem being “well defined” but this
is not always the case and it is in these instances it is possible to run the code testing
every available sign combination on the constrained derivatives. For a definition of
a “well defined” problem and it’s counter part see themaxsmoothpaper and the
documentation.maxsmoothfeatures a built in library of DCFs or
allows the user to define their own. The addition of possible inflection points
and zero crossings in higher order derivatives is also available to the user.
The software has been designed with these two
applications in mind and is a simple interface.Example FitShown below is an example MSF fit performed withmaxsmoothto data that
follows a y = x-2.5power law with a randomly generated Gaussian
noise with a standard deviation 0.02. The top panel shows the data and the
bottom panel shows the residual
after subtraction of the MSF fit alongside the actual noise in the data.
The software using the default built-in DCF model is shown to be
capable of recovering the random noise.Further examples can be found in the Documentation (https://maxsmooth.readthedocs.io/)
and in the github repository in the files ‘example_codes/’ and
‘example_notebooks/’ (notebooks can also be accessed onlinehere).Licence and CitationThe software is free to use on the MIT open source license. However if you use
the software for academic purposes we request that you cite themaxsmoothpapers. They are detailed below.MNRAS paper (referred to throughout the documentation as themaxsmoothpaper),H. T. J. Bevins et al.,maxsmooth: Rapid maximally smooth function fitting with
applications in Global 21-cm cosmology,
Monthly Notices of the Royal Astronomical Society, 2021;, stab152,https://doi.org/10.1093/mnras/stab152Below is the BibTex citation,@article{10.1093/mnras/stab152,author={Bevins, H T J and Handley, W J and Fialkov, A and Acedo, E de Lera and Greenhill, L J and Price, D C},title="{maxsmooth: rapid maximally smooth function fitting with applications in Global 21-cm cosmology}",journal={Monthly Notices of the Royal Astronomical Society},year={2021},month={01},issn={0035-8711},doi={10.1093/mnras/stab152},url={https://doi.org/10.1093/mnras/stab152},note={stab152},eprint={https://academic.oup.com/mnras/advance-article-pdf/doi/10.1093/mnras/stab152/35931358/stab152.pdf},}JOSS paper,Bevins, H. T., (2020). maxsmooth: Derivative Constrained Function Fitting. Journal of Open Source Software, 5(54), 2596,https://doi.org/10.21105/joss.02596and the BibTex,@article{Bevins2020,doi={10.21105/joss.02596},url={https://doi.org/10.21105/joss.02596},year={2020},publisher={The Open Journal},volume={5},number={54},pages={2596},author={Harry T. j. Bevins},title={maxsmooth: Derivative Constrained Function Fitting},journal={Journal of Open Source Software}}ContributingContributions tomaxsmoothare welcome and can be made via:Opening an issue to purpose new features/report bugs.Making a pull request. Please consider opening an issue to discuss
any proposals beforehand and ensure that your PR will be accepted.An example contribution may be the addition of a basis function into the
standard library.DocumentationThe documentation is available at:https://maxsmooth.readthedocs.io/Alternatively, it can be compiled locally from the git repository and requiressphinxto be installed.
You can do this via:cd docs/
make SOURCEDIR=source htmlorcd docs/
make SOURCEDIR=source latexpdfThe resultant docs can be found in the docs/_build/html/ and docs/_build/latex/
respectively.RequirementsTo run the code you will need the following additional packages:matplotlibnumpyCVXOPTscipyprogressbarWhen installing via pip or from source using the setup.py file
the above packages will also be installed if absent.To compile the documentation locally you will need:sphinxnumpydocTo run the test suit you will need:pytestBasin-hopping/Nelder-Mead CodeIn themaxsmoothMNRAS paper and JOSS paper we provide a comparison ofmaxsmoothto a Basin-hopping/Nelder-Mead approach for fitting DCFs. For
completeness we provide in this repo the code used to make this comparison
in the file ‘Basin-hopping_Nelder_Mead/’.The code times_chis.py is used to callmaxsmoothand the Basin-hopping
methods (in the file ‘BHNM/’). It will plot the recorded times and objective
function evaluations.The Basin-hopping/Nelder-Mead code is designed to fit MSFs and is not
generalised to all types of DCF. It is also not documented, however there are
minor comments in the script and it should be self explanatory. Questions
on this are welcome and can be posted as an issue or by contacting the author.