{"id":21161960,"url":"https://github.com/princetonuniversity/fasttemplateperiodogram","last_synced_at":"2025-10-10T02:03:27.893Z","repository":{"id":65985351,"uuid":"71791362","full_name":"PrincetonUniversity/FastTemplatePeriodogram","owner":"PrincetonUniversity","description":"NlogN algorithm for least-squares fitting of periodic templates to noisy, non-equispaced time-series data.","archived":false,"fork":false,"pushed_at":"2021-01-29T16:22:12.000Z","size":1953,"stargazers_count":52,"open_issues_count":1,"forks_count":10,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-07-09T14:47:57.651Z","etag":null,"topics":["astronomy","fourier-series","frequencies","harmonics","lomb-scargle-periodogram","nfft","optimal-parameters","periodic","periodogram","signal-processing","time-series"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PrincetonUniversity.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-24T13:22:39.000Z","updated_at":"2025-06-02T16:33:38.000Z","dependencies_parsed_at":"2023-02-19T19:15:50.480Z","dependency_job_id":null,"html_url":"https://github.com/PrincetonUniversity/FastTemplatePeriodogram","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/PrincetonUniversity/FastTemplatePeriodogram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrincetonUniversity%2FFastTemplatePeriodogram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrincetonUniversity%2FFastTemplatePeriodogram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrincetonUniversity%2FFastTemplatePeriodogram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrincetonUniversity%2FFastTemplatePeriodogram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PrincetonUniversity","download_url":"https://codeload.github.com/PrincetonUniversity/FastTemplatePeriodogram/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrincetonUniversity%2FFastTemplatePeriodogram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002522,"owners_count":26083398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astronomy","fourier-series","frequencies","harmonics","lomb-scargle-periodogram","nfft","optimal-parameters","periodic","periodogram","signal-processing","time-series"],"created_at":"2024-11-20T13:19:28.679Z","updated_at":"2025-10-10T02:03:27.874Z","avatar_url":"https://github.com/PrincetonUniversity.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"Fast Template Periodogram\n=========================\n\n.. image:: http://img.shields.io/travis/PrincetonUniversity/FastTemplatePeriodogram/master.svg?style=flat\n\t:target: https://travis-ci.org/PrincetonUniversity/FastTemplatePeriodogram\n\n.. image:: https://codecov.io/gh/PrincetonUniversity/FastTemplatePeriodogram/coverage.svg?branch=master\n\t:target: https://codecov.io/gh/PrincetonUniversity/FastTemplatePeriodogram\n\n:Authors:\n\tJohn Hoffman (johnh2o2@gmail.com)\n\tJake VanderPlas (jakevdp@uw.edu)\n\n:Version:\n\t1.0.0\n\n**Check out the** `Scipy 2017 talk \u003chttps://www.youtube.com/watch?v=7STeeVnfYFM\u003e`_\n\nDescription\n-----------\n\n.. image:: plots/templates_and_periodograms.png\n\nThe Fast Template Periodogram extends the Lomb-Scargle\nperiodogram ([Barning1963]_, [Vanicek1971]_, [Lomb1976]_, [Scargle1982]_, [ZechmeisterKurster2009]_) for arbitrary (periodic) signal shapes. It\nnaturally handles non-uniformly sampled time-series data.\n\n:Template:\n\tPeriodic signal shape, expressed as a truncated Fourier series of length ``H``.\n\n:Periodogram:\n\tLeast-squares estimator of the power spectral density (Lomb-Scargle); for more\n\tgeneral models, proportional to the \"goodness of fit\" statistic for the best-fit\n\tmodel at that frequency. See [VanderPlas2017]_ for more details.\n\nUses the the `non-equispaced Fast Fourier Transform \u003chttps://www-user.tu-chemnitz.de/~potts/nfft\u003e`_ to efficiently compute frequency-dependent sums.\n\nThe ``ftperiodogram`` library is complete with API documentation and consistency\nchecks using ``py.test``.\n\n\nInstalling\n----------\n\nInstalling with ``pip`` should work::\n\n    $ pip install ftperiodogram\n\nIf this doesn't work, consult the instructions in ``CONDA_INSTALL.md`` for installing ``ftperiodogram`` and its dependencies with with\n`conda \u003chttps://www.continuum.io/downloads\u003e`_.\n\nExamples\n--------\n\nSee the ``Examples.ipynb`` located in the ``notebooks/`` directory.\n\nTo run this notebook, use the ``jupyter notebook`` command from\ninside the ``notebooks/`` directory::\n\n\t$ cd notebooks/\n\t$ jupyter notebook\n\n\nUpdates\n-------\n\nSee the `issues \u003chttps://github.com/PrincetonUniversity/FastTemplatePeriodogram/issues\u003e`_ section for known bugs. You can also submit bugs and suggest improvements through that interface.\n\nMore information\n================\n\nPrevious implementations\n------------------------\n\nThe `gatspy \u003chttp://www.astroml.org/gatspy/\u003e`_ library has an implementation of\nboth single and multiband template fitting, however this implementation\nuses non-linear least-squares fitting to compute the optimal parameters\n(amplitude, phase, constant offset) of the template fit at each frequency. That\nprocess scales as ``N_obs*N_f``, where ``N`` is the number of observations and\n``N_f`` is the number of frequencies at which to calculate the periodogram.\n\nThis is more or less the procedure used in [Sesar_etal_2017]_ to perform\ntemplate fits to Pan-STARRS photometry, however they used a more sophisticated\nmultiband model that locked the phases, amplitudes and\noffsets of all bands together. They found that template fitting was significantly more accurate for estimating periods of RR Lyrae stars, but the computational resources\nneeded for these fits were enormous (~30 minutes per object per CPU core).\n\nHow does the fast template periodogram improve things?\n------------------------------------------------------\n\nBy rederiving periodic template fitting (or periodic matched filter analysis)\nin the context of least-squares spectral analysis, we found a significantly\nbetter way to perform these fits. Details will be presented in a paper\n(Hoffman et al. 2017, in prep), but the important part is you can reduce\nthe non-linearity of the problem to the following:\n\n\n- Finding the zeros of an order ``6H-1`` complex polynomial at each trial frequency.\n\t- This is done via the ``numpy.polynomial`` library, which performs singular-value decomposition on the polynomial \"companion matrix\", and scales as ``O(H^3)``.\n- Computing the coefficients of these polynomials for all trial frequencies simultaneously by leveraging the non-equispaced fast Fourier transform, a process that scales as ``O(HN_f log(HN_f))``.\n\nThis provides two advantages:\n\n:Improved computational speed and scaling:\n\t.. image:: plots/timing_vs_ndata_const_freq.png\n\tSpeed comparison for a test case using a constant\n\tnumber of trial frequencies but varying the number\n\tof observations.\n\n:Numerically stable and accurate:\n\t.. image:: plots/correlation_with_nonlinopt.png\n\tAccuracy comparison between the fast template periodogram\n\tand a ``gatspy``-like method that uses the ``scipy.optimize.minimize``\n\tfunction to find the optimal phase shift parameter. The minimization\n\tmethod is given 10 random starting values and the best result is kept.\n\tThough in most cases the truly optimal solution is found, in many cases\n\ta sub-optimal solution is chosen instead (i.e. only a locally optimal\n\tsolution was chosen).\n\n\nHow is this different than the multi-harmonic periodogram?\n----------------------------------------------------------\n\nThe multi-harmonic periodogram ([Bretthorst1988]_, [SchwarzenbergCzerny1996]_) is another\nextension of Lomb-Scargle that fits a truncated Fourier series to the data\nat each trial frequency. This algorithm can also be made to scale as\n``HN_f logHN_f`` [Palmer2009]_.\n\nHowever, the multi-harmonic periodogram is fundamentally different than template fitting.\nIn template fitting, the relative amplitudes and phases of the Fourier series are *fixed*.\nIn a multi-harmonic periodogram, the relative amplitudes and phases of the Fourier series are *free parameters*.\n\nThe multiharmonic periodogram is more flexible than the template periodogram, but less\nsensitive to a given signal. If you're hoping to find a non-sinusoidal signal with an\nunknown shape, it might make more sense to use a multi-harmonic periodogram.\n\nFor more discussion of the multiharmonic periodogram and related extensions, see [VanderPlas_etal_2015]_ and [VanderPlas2017]_.\n\nTODO\n----\n\n* Multi-band extensions\n* Speed improvements\n\n\nReferences\n----------\n\n\n.. [ZechmeisterKurster2009] `The generalised Lomb-Scargle periodogram. A new formalism for the floating-mean and Keplerian periodograms \u003chttp://adsabs.harvard.edu/abs/2009A%26A...496..577Z\u003e`_\n\n.. [Lomb1976] `Least-squares frequency analysis of unequally spaced data \u003chttp://adsabs.harvard.edu/abs/1976Ap%26SS..39..447L\u003e`_\n\n.. [Scargle1982] `Studies in astronomical time series analysis. II - Statistical aspects of spectral analysis of unevenly spaced data \u003chttp://adsabs.harvard.edu/abs/1982ApJ...263..835S\u003e`_\n\n.. [Barning1963] `The numerical analysis of the light-curve of 12 Lacertae \u003chttp://adsabs.harvard.edu/abs/1963BAN....17...22B\u003e`_\n\n.. [Vanicek1971] `Further Development and Properties of the Spectral Analysis by Least-Squares \u003chttp://adsabs.harvard.edu/abs/1971Ap%26SS..12...10V\u003e`_\n\n.. [VanderPlas2017] `Understanding the Lomb-Scargle Periodogram \u003chttps://arxiv.org/abs/1703.09824\u003e`_\n\n.. [Sesar_etal_2017] `Machine-Learned Identification of RR Lyrae Stars from Sparse, Multi-band Data: the PS1 Sample \u003chttps://arxiv.org/abs/1611.08596\u003e`_\n\n.. [Bretthorst1988] `Bayesian Spectrum Analysis and Parameter Estimation \u003chttps://link.springer.com/book/10.1007%2F978-1-4684-9399-3\u003e`_\n\n.. [SchwarzenbergCzerny1996] `Fast and Statistically Optimal Period Search in Uneven Sampled Observations \u003chttp://iopscience.iop.org/article/10.1086/309985/meta\u003e`_\n\n.. [Palmer2009] `A FAST CHI-SQUARED TECHNIQUE FOR PERIOD SEARCH OF IRREGULARLY SAMPLED DATA \u003chttp://iopscience.iop.org/article/10.1088/0004-637X/695/1/496/meta\u003e`_\n\n.. [VanderPlas_etal_2015] `Periodograms for Multiband Astronomical Time Series \u003chttp://adsabs.harvard.edu/abs/2015ApJ...812...18V\u003e`_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprincetonuniversity%2Ffasttemplateperiodogram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprincetonuniversity%2Ffasttemplateperiodogram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprincetonuniversity%2Ffasttemplateperiodogram/lists"}