Enhanced light curve plotting behavior

[dwysocki]

Currently, plotypus.lightcurve.plot_lightcurve expects phased data. It takes a period as well, but only for display on the time axis. To better support multi-frequency fits, I propose the following changes.

Most importantly, the function should expect unphased data, as the meaning of phased becomes less clear-cut in this case.

If period=None, then the unphased data should be plotted as-is, with the fit plotted from min(time) to max(time). This solves part of what was proposed in #40.

If period=scalar, then phase the data with that period. This will produce the same output as it currently does, the only difference being the input (phased/unphased).

If period=array-like, return a list with the same dimensions, and each element of the list containing the result of recursively calling plot_lightcurve with period=element in array-like. This can actually easily support arbitrary-dimensional arrays, through the use of recursion.

In the command line program, we should separate the option --output-plot-lightcurve into phased and unphased versions (still deciding on the naming). This way it will only call plot_lightcurve with period=None if the unphased version is requested, and with period=result["period"] if the phased version is.

One thing that doesn't quite mesh with this approach is the current output argument to plot_lightcurve. We would need some sort of way to get indexing information to it. Perhaps it would be best to simply move saving from the plot function itself to cli.py, since it has access to all of the matplotlib.Figure objects.

[dwysocki]

I just remembered another issue that crops up when plotting multifrequency signals. Since a signal with 2 or more incommensurable periods is not truly periodic, when we phase it, the interpolating function is ambiguous. From times t*period to (t+1)*period, the value of the interpolating function will be different than for T*period to (T+1)*period, for any t != T. So this leaves us with a few options.

1. Choose an arbitrary time interval, whose length is one period, on which to sample the interpolating function.
   • Pros: It looks clean.
   • Cons: This is not completely honest, as it loses a lot of information, and may depend heavily on the chosen interval.
2. Sample the interpolating function from min(time) to max(time).
   • Pros: This is the most honest way to go
   • Cons: This is the ugliest way to plot it, as there will be a lot of overlap. See the plot below for the triple-period star, OGLE-LMC-CEP-2147, which Earl made a while back.

Perhaps we should just support both methods, and use a different option for each? Either way we go, it will require a decent bit of refactoring, so we should think before we code. There's also the question of which time interval to use for option 1, which is not a very easy question. Perhaps we do something like always use min(time) to min(time) + period (or the reverse with max(time)), or use the time interval with the smallest residual (that's an extra optimization problem right there!), or somehow ask the user for a range (that's a headache for the user!).

[dwysocki]

The more I think about it, the more it seems like we just need to support both options 1. and 2.

The remaining questions then are how we choose the time interval for 1., and how we separate these options. Probably with two output specifiers, like --output-plot-X-lightcurve and --output-plot-Y-lightcurve. I can't think of any good names right now.

[dwysocki]

Actually, there is a 3rd and 4th possibility for plotting, which I just remembered.

3 . Same as 2., but take the average at each phase point.

• Pros: Looks nice (I hope)
• Cons: Loses information that 2. provides, but is not dependent on arbitrary intervals like 1.

4 . Compute the interpolating function using only the coefficients which correspond only to the one period used.

• Pros: Looks nice
• Cons: This is essentially equivalent to fitting a Fourier series with only the one period.

I honestly think all of these plot types are desirable in some sense, but it should also be possible to produce them externally, using the tabular output, so we don't necessarily need to implement them all within plotypus. Maybe we should just implement option 2., and leave out the rest. Another advantage of this plot type is that in the singly-periodic case, it reduces to the existing behavior.