Package: phmin
phminA basic python package for determining periods in time series data through phase dispersion minimization.Author: Erik William StaceyDate: 7 Feb, 2023Installationphmin is available through pip:pip install phminOr, alternatively, download and install directly from this repo:git clone https://github.com/erikstacey/phmin.git ./phmin
cd phmin
pip install .UsageThe ph_minner class is used to store and operate on time series data. Here's a basic example snippit setting up a ph_minner:import numpy as np
from phmin import ph_minner

x, y, y_err = np.loadtxt("sample.txt", unpack=True)
example_minner = ph_minner(x=x, y=y, err=y_err)To run the minimizer, call the run method:example_minner.run()To print or plot the results, callexample_minner.print_results()
example_minner.plot_results()Advanced UsageIn most cases, the user will want to specify the bin widths and number of bins in accordance with the characteristics of
the time series under examination. These are set through the optional parameters of the ph_minner classnbandnc:example_minner = ph_minner(x=x, y=y, err=y_err, nb = 10, nc=4)Thenbandncparameters are unintuitive as how they control the phase binning. Firstly, the bin width is
equivalent to1/nb, and the total number of bins is equivalent tonb*nc. As the bins must remain within[0,1],
settingnc>1will result in overlapping bins with bin centers evenly spaced by1/(nb*nc)and wrapping around
the edges of the phase interval[0,1]. The default parameters setnb=5, nc=2, resulting in 10 0.2-width bins.The ph_minner class can also be initialized with optional parameters periods and t0. Setting periods manually defines the period grid, and setting t0 manually sets the reference time for the phasing.manual_period_grid = np.linspace(4.4, 4.8, 500)
example_minner = ph_minner(x=x, y=y, err=y_err, periods=manual_period_grid, t0=2457000.0)The results can be directly accessed through attributes of theph_minnerclass.ph_minner.periods- Array of periodsph_minner.thetas- Array of theta values. See Stellingwerf (1978, ApJ, 224, 953) for details. In short,
as theta approaches zero the statistical significance of the measured frequency increases. On the contrary, theta at 1
indicates minimum statistical significance. Additionally, the minimum theta value and its corresponding period can be retrieved usingbest_P, min_theta = ph_minner.best_fit_pars()This package also includes a classls_ph_minner, which operates similarly to the phase dispersion minimizer. However
this class actually relies on chi squared minimization of a sinusoidal variability model against the phased data at each candidate
period, making it statistically equivalent to a Lomb-Scargle analysis (and functionally different from a phase dispersion
minimization analysis). This is useful for quickly identifying a single sinusoidal frequency in spaced data,
however for LS frequency analysis myPyPreWpackage is significantly more capable.MethodThis package is intended to solve the problem of determining the principal frequency present in time series data through
phase dispersion minimization. During the initialization process, a set of candidate periods are either user-provided
or generated. A set of (overlapping, for nc>1) bins in phase are also generated. When the run method is called, it
iterates over all candidate frequencies and at each iteration it:Converts the timeseries time stamps to phases,Evaluate the variance in each bin,Compare the bin variances against the total variance in the time series to yield the theta parameter,Stores the theta parameter to later identify which candidate period had the minimal theta.More details on the phase dispersion minimization methodology are presented byStellingwerf (1978, ApJ, 224, 953). Also
seeSchwarzenberg-Czerny (1997, ApJ, 489(2), 941)for
an updated statistical treatment of this method.ChangelogV1.0.0 (7 Feb, 2023)-Changed ph_minner to implement phase dispersion minimization
-Moved previously-placeholder Lomb-Scargle equivalent functionality to ls_ph_minnerV0.1.4 (6 Feb, 2023)-Fixed plot_results()V0.1.3 (6 Feb, 2023)-Removed redundant fmt in plot_results()V0.1.2 (6 Feb, 2023)-Fixed label in ph_minner.plot_results()V0.1.0 (6 Feb, 2023)-Added methods to ph_minner for printing and plotting results
-Throws an exception if the user tries to plot or print without running firstV0.0.1 (6 Feb, 2023)-Working package published on github