#!/usr/bin/env python
# coding: utf-8

# # What are `Periodogram` objects?

# *Lightkurve* has a class specifically for dealing with periodograms of time series data. This can be useful for finding the periods of variable stars. Below is a quick example of how to find the period of an [eclipsing binary star](https://en.wikipedia.org/wiki/Binary_star#Eclipsing_binaries).
# 
# First, let's grab a light curve file from the Kepler data archive. We'll use the object named KIC 10264202, which is an eclipsing binary observed by the original Kepler mission. We're just going to use one quarter of data for this demo.

# In[1]:


from lightkurve import search_lightcurvefile
lc = search_lightcurvefile('KIC 10264202', quarter=10).download().PDCSAP_FLUX.remove_nans()


# Let's plot the light curve to see what we're working with.

# In[2]:


lc.scatter();


# This light curve looks like it has some structure in it! Let's use the periodogram class to find the rotation period. You can create a periodogram from the `KeplerLightCurve` object by using the `to_periodogram` method.

# In[3]:


pg = lc.to_periodogram(oversample_factor=1)


# Now we can plot the periodogram in the same way that we plot the original light curve.

# In[4]:


pg.plot();


# This looks like there is a huge signal at a certain frequency! Let's plot it in period space, so that we can see what period the oscillation is occurring at.

# In[5]:


pg.plot(view='period', scale='log');


# This looks like a very fast period. We can access the full period and power data as follows:

# In[6]:


pg.period


# In[7]:


pg.power


# In this case we simply want to know the period that corresponds to the highest peak in the periodogram.  We can directly access this value using the convenient `period_at_max_power` property:

# In[8]:


pg.period_at_max_power


# We can then use this period to fold our light curve:

# In[9]:


lc.fold(pg.period_at_max_power).scatter();


# Oops, the eclipses do not line up nicely. This does not look like the correct period of this eclipsing binary!
# 
# As is quite common for eclipsing binaries with deep secondary eclipses, we have found a harmonic of the period of the eclipsing binary. Let's plot it again with quadruple the period.

# In[10]:


lc.fold(4 * pg.period_at_max_power).scatter();


# That looks better, but the eclipses still don't seem to line up as well as they could.
# 
# Let's try to get a more precise period by increasing the number of points in our periodogram using the `oversample_factor` parameter and by constraining the range of the period value:

# In[11]:


import astropy.units as u
pg = lc.to_periodogram(minimum_period=0.9*u.day, maximum_period=1.2*u.day, oversample_factor=10)
pg.period_at_max_power


# In[12]:


lc.fold(pg.period_at_max_power).scatter();


# This has improved our fit. It looks like this eclipsing binary has a period of approximately 1 day.