Frequently Asked Questions¶
Installation¶
Q: pip install pgmuvi fails with a PyTorch error.
pgmuvi depends on torch and gpytorch. On some platforms (e.g., certain
Linux systems without a GPU), pip may install a CPU-only PyTorch build. If you
encounter errors, install PyTorch first following the instructions at
https://pytorch.org/get-started/locally/ and then install pgmuvi.
Q: The docs say Python >=3.10 is required. Will it work on 3.9?
No. pgmuvi uses Python 3.10+ syntax and typing features such as
PEP 604 union types (for example, X | None). If you need to use an
older Python version, please open an issue on the GitHub repository.
Data and Input¶
Q: What time unit should I use?
Any consistent unit is fine. pgmuvi does not assume a specific time unit;
it only needs the xdata and ydata to be in consistent units. The inferred
periods will be in the same unit as your input times. Common choices are days or
Modified Julian Date (MJD).
Q: Can I use pgmuvi with data in magnitudes rather than flux?
Not yet natively. The magnitudes option of
Lightcurve is not currently implemented.
For now, convert magnitudes and their uncertainties to (relative) fluxes
before constructing the Lightcurve. A standard
conversion is \(f \propto 10^{-0.4\,m}\); see
Working with Magnitudes for a code example.
Q: My data have irregular gaps. Is that a problem?
No — handling irregular sampling is one of the main strengths of GP-based methods. Lomb–Scargle initialisation also handles irregular data naturally.
Q: How many observations do I need?
There is no hard minimum, but as a rough guide:
At least 20–30 observations per band for reliable GP fitting.
At least 10 observations per estimated period to resolve the periodicity.
Bands with fewer than ~10 observations should be treated with caution.
Use assess_sampling_quality() for a
data-driven assessment.
Fitting and Convergence¶
Q: fit_LS() is very slow. How can I speed it up?
Subsample dense datasets (see Data Preprocessing).
Reduce
num_mixtures(fewer parameters → faster optimisation).Move the light curve to a GPU before fitting:
lc.cuda().
Q: The fit converges to a period that makes no physical sense.
Check that the physical period lies within the detectable range (see
compute_sampling_metrics()) and that your
constraints allow it. Also try running with num_mixtures=1 first to find the
dominant period, then increase.
Q: Should I use fit() or fit_LS()?
fit_LS() runs a Lomb–Scargle periodogram
to identify candidate periods and can be used as a diagnostic tool.
fit() performs the actual GP MAP
optimisation. For the most common workflow, call fit()
with use_mls_init=True (the default) so that MLS-based frequency seeding is
applied automatically before fitting.
Q: fit() finds too many / too few mixture components.
fit_LS() does not take a
num_mixtures argument. To change the number of mixture components, pass
num_mixtures to fit() or to
set_model():
lc.fit(model="1D", num_mixtures=2)
# or equivalently
lc.set_model("1D", num_mixtures=2)
lc.fit()
Q: MCMC is very slow.
Periods and Interpretation¶
Q: The inferred period is twice (or half) the expected period.
This is a classical harmonic aliasing issue. The periodogram may detect harmonics rather than the fundamental frequency. Try restricting the frequency range via a constraint (see Setting Priors and Constraints) to encourage the model to find the fundamental.
Q: I see multiple peaks in the PSD. Which one is the true period?
The highest-weighted component typically corresponds to the dominant variability timescale. However, inspect the PSD shape carefully:
Peaks near the Nyquist frequency or at the observing cadence may be sampling aliases.
Peaks at integer multiples of the dominant period are harmonics.
Very broad peaks (large
mixture_scales) indicate stochastic / quasi-periodic variability, not a precise period.
Q: How do I get period uncertainties from a MAP fit?
With MAP optimisation, no formal uncertainty is reported on the period. A
practical proxy is the inferred bandwidth mixture_scales: a wider bandwidth
corresponds to a less coherent signal and a less precisely determined period.
Full posterior uncertainties via MCMC are planned for a future release of
pgmuvi (see the note in the MCMC question above).
Multiband Data¶
Q: Do I have to use the same set of times for each band?
No. The observations for each band can be at completely different times. Simply
stack all observations into a single array with a wavelength/band label in the
second column of xdata (see Multiwavelength (2D) Analysis).
Q: Which band is used for Lomb–Scargle initialisation in 2D?
By default, the multiband Lomb–Scargle periodogram is used to seed the
spectral-mixture kernel frequencies. If one band has substantially more
observations than others, pass use_best_band_init=True to
fit() to use a 1-D Lomb–Scargle on the
most-sampled band instead of the multiband periodogram for frequency
initialisation.
Contributing and Support¶
Q: I found a bug. How do I report it?
Please open an issue on the GitHub repository. Include a minimal reproducible example and the full error traceback.
Q: I want to add a new feature. Where do I start?
See the contributing guidelines on GitHub. New contributors are very welcome!