sora.lightcurve

The LightCurve Class

class sora.LightCurve(name='', **kwargs)[source]

Defines a Light Curve.

Parameters

  • name (str) – The name of the LightCurve. Each time an LightCurve object is defined the name must be different.

  • tref (astropy.time.Time, str, float) –

    Instant of reference.

    Format: Julian Date, string in ISO format or Time object. Required only if LightCurve have input fluxes and given time is not in Julian Date.

  • central_bandpass (int, float, otpional, default=0.7) – The center band pass of the detector used in observation. Value in microns.

  • delta_bandpass (int, float, optional, default=0.3) – The band pass width of the detector used in observation. Value in microns.

  • exptime (int, float) – The exposure time of the observation, in seconds. NOT required in cases 2, 3 and 4 below. Required in case 1 below.

  • **kwargs (int, float) –

    Object velocity, distance, and star diameter.

    Note

    velint, float

    Velocity in km/s.

    distint, float

    Object distance in AU.

    d_starfloat

    Star diameter, in km.

Warning

Input data must be one of the 4 options below:

  1. Input data from file with time and flux

    file (str): a file with the time and flux. A third column with the error in flux can also be given.

    usecols (int, tuple, array): Which columns to read, with the first being the time, the seconds the flux and third the flux error (optional).

    Example:

    >>> LightCurve(name, file, exptime) # dflux can also be given
  1. Input data when file is not given:

    time: time must be a list of times, in seconds from tref, or Julian Date, or a Time object.

    flux: flux must be a list of fluxes. It must have the same lenght as time.

    dflux: if file not given, dflux must be a list of fluxes errors. It must have the same lenght as time. (not required)

    Example:

    >>> LightCurve(name, flux, time, exptime) # dflux can also be given

Cases for when time and flux are not given.

  1. Input for a positive occultation:

    immersion: The instant of immersion.

    emersion: The instant of emersion.

    immersion_err: Immersion time uncertainty, in seconds.

    emersion_err: Emersion time uncertainty, in seconds.

    Example:

    >>> LightCurve(name, immersion, immersion_err, emersion, emersion_err)
  2. Input for a negative occultation:

    initial_time: The initial time of observation.

    end_time: The end time of observation.

    Example:

    >>> LightCurve(name, initial_time, end_time)
calc_magnitude_drop(mag_star, mag_obj)[source]

Determines the magnitude drop of the occultation.

Parameters

  • mag_star (int, float) – Star magnitude.

  • int (mag_obj) – Object apparent magnitude to the date.

  • float – Object apparent magnitude to the date.

Returns

  • mag_drop (float) – Magnitude drop for the given magnitudes.

  • bottom_flux (float) – Normalized bottom flux for the given magnitudes.

normalize(poly_deg=None, mask=None, flux_min=0.0, flux_max=1.0, plot=False)[source]

Returns the normalized flux within the flux min and flux max defined scale.

Parameters

  • poly_deg (int) – Degree of the polynomial to be fitted.

  • mask (bool array) – Which values to be fitted.

  • flux_min (int, float) – Event flux to be set as 0.

  • flux_max (int, float) – Baseline flux to be set as 1.

  • plot (bool) – If True plot the steps for visual aid.

occ_detect(maximum_duration=None, dur_step=None, snr_limit=None, n_detections=None, plot=False)[source]

Detects automatically the occultation event in the light curve.

Detects a ‘square well’ shaped transit. All parameters are optional.

Parameters

  • maximum_duration (float, default: light curve time span) – Maximum duration of the occultation event.

  • dur_step (float, default: 1/2 of sampling rate) – Step size to sweep occultation duration event.

  • snr_limit (float, default=None) – Minimum occultation SNR.

  • n_detections (int, default=1) – Number of detections regardless the SNR. n_detections is superseded by snr_limit.

  • plot (bool) – True if output plots are desired.

Returns

OrderedDict – An ordered dictionary of name:value pairs for each parameter.

Return type

dict

Examples

>>> lc = LightCurve(time=time, flux=flux, exptime=0.0, name='lc_example')
>>> params = lc.occ_detect()
>>> params
{'rank': 1,
'occultation_duration': 40.1384063065052,
'central_time': 7916.773870512843,
'immersion_time': 7896.7046673595905,
'emersion_time': 7936.843073666096,
'time_err': 0.05011036992073059,
'depth': 0.8663887801707082,
'depth_err': 0.10986223384336465,
'baseline': 0.9110181732552853,
'baseline_err': 0.19045768512595365,
'snr': 7.886138392251848,
'occ_mask': array([False, False, False, ..., False, False, False])}
occ_lcfit(**kwargs)[source]

Monte Carlo chi square fit for occultations lightcurve.

Parameters

  • tmin (int, float) – Minimum time to consider in the fit procedure, in seconds.

  • tmax (int, float) – Maximum time to consider in the fit procedure, in seconds.

  • flux_min (int, float, default=0) – Bottom flux (only object).

  • flux_max (int, float, default=1) – Base flux (object plus star).

  • immersion_time (int, float) – Initial guess for immersion time, in seconds.

  • emersion_time (int, float) – Initial guess for emersion time, in seconds.

  • opacity (int, float, default=1) – Initial guess for opacity. Opaque = 1, Transparent = 0.

  • delta_t (int, float) – Interval to fit immersion or emersion time.

  • dopacity (int, float, default=0) – Interval to fit opacity.

  • sigma (int, float, array, ‘auto’) – Fluxes errors. If None it will use the self.dflux. If ‘auto’ it will calculate using the region outside the event.

  • loop (int, default=10000) – Number of tests to be done.

  • verbose (bool, default=False) – If True, it prints information while fitting.

  • sigma_result (int, float) – Sigma value to be considered as result.

  • method (str, default=`chisqr`) – Method used to perform the fit. Available methods are: chisqr : monte carlo computation method used in versions of SORA <= 0.2.1. fastchi : monte carlo computation method, allows multithreading. least_squares or ls: best fit done used levenberg marquardt convergence algorithm. differential_evolution or de: best fit done using genetic algorithms. All methods return a Chisquare object.

  • threads (int) – Number of threads/workers used to perform parallel computations of the chi square object. It works with all methods except chisqr, by default 1.

Returns

chi2 – ChiSquare object.

Return type

sora.extra.ChiSquare

occ_model(immersion_time, emersion_time, opacity, mask, npt_star=12, time_resolution_factor=10, flux_min=0, flux_max=1)[source]

Returns the modelled light curve.

The modelled light curve takes into account the fresnel diffraction, the star diameter and the instrumental response.

Parameters

  • immersion_time (int, float) – Immersion time, in seconds.

  • emersion_time (int, float) – Emersion time, in seconds.

  • opacity (int, float) – Opacity. Opaque = 1.0, transparent = 0.0,

  • mask (bool array) – Mask with True values to be computed.

  • npt_star (int, default=12) – Number of subdivisions for computing the star size effects.

  • time_resolution_factor (int, float, default: 10*fresnel scale) – Steps for fresnel scale used for modelling the light curve.

  • flux_min (int, float, default=0) – Bottom flux (only object).

  • flux_max (int, float, default=1) – Base flux (object plus star).

plot_lc(ax=None)[source]

Plots the light curve

plot_model(ax=None)[source]

Plots the modelled light curve

reset_flux()[source]

Resets flux for original values

set_dist(dist)[source]

Sets the object distance.

Parameters

dist (int, float) – Object distance in AU.

set_exptime(exptime)[source]

Sets the light curve exposure time.

Parameters

exptime (int, float) – Exposure time, in seconds.

set_filter(central_bandpass, delta_bandpass)[source]

Sets the filter bandwidth in microns.

Parameters

  • central_bandpass (float) – Center band in microns.

  • delta_bandpass (float) – Bandwidth in microns.

set_flux(**kwargs)[source]

Sets the flux for the LightCurve.

Parameters

  • exptime (int, float, required) – The exposure time of the observation, in seconds.

  • file (str) – A file with the time and flux in the first and second columns, respectively. A third column with error in flux can also be given.

  • time – If file not given, time must be a list of times, in seconds from tref, or Julian Date, or a Time object.

  • flux – If file not given, flux must be a list of fluxes. It must have the same lenght as time.

  • dflux – If file not given, dflux must be a list of fluxes errors. It must have the same lenght as time.

  • tref (astropy.time.Time, str, float) – Instant of reference. It can be in Julian Date, string in ISO format or Time object.

  • usecols (int, tuple, array, optional) – Which columns to read, with the first being the time, the seconds the flux and third the flux error.

  • **kwargs (int, float) –

    Object velocity, object distance, star diameter.

    Note

    velint, float

    Velocity in km/s.

    distint, float:

    Object distance in AU.

    d_starfloat

    Star diameter, in km.

set_star_diam(d_star)[source]

Sets the star diameter.

Parameters

d_star (float) – Star diameter, in km.

set_vel(vel)[source]

Sets the occultation velocity.

Parameters

vel (int, float) – Velocity in km/s.

to_file(namefile=None)[source]

Saves the light curve to a file.

Parameters

namefile (str) – Filename to save the data.

to_log(namefile=None)[source]

Saves the light curve log to a file.

Parameters

namefile (str) – Filename to save the log.

Occutation Detection

sora.lightcurve.occdetect.occ_detect(flux, dflux, time, cycle, maximum_duration=None, dur_step=None, snr_limit=None, n_detections=None, plot=False)[source]

Detects automatically the occultation event in the light curve.

Detects a ‘square well’ shaped transit. All parameters are optional.

Parameters

  • flux (float array) – Flux of the time series. Dependent variable.

  • dflux (float array) – Error in the flux. Error in the dependent variable.

  • time (float array) – Time variable. Independent variable.

  • cycle (float) – Sampling value of the time series.

  • maximum_duration (float, default: light curve time span) – Maximum duration of the occultation event.

  • dur_step (float, default: 1/2 cycle) – Step size to sweep occultation duration event.

  • snr_limit (float, default=None) – Minimum occultation SNR.

  • n_detections (int, default=1) – Number of detections regardless the SNR. n_detections is superseded by snr_limit.

  • plot (boolean, default=False) – True if output plots are desired.

Returns

OrderedDict – An ordered dictionary of name:value pairs for each parameter.

Return type

dict

Examples

>>> from sora.lightcurve.occdetect import occ_detect
>>> params = occ_detect(flux, dflux, time, 0.2)
>>> params
{'rank': 1,
'occultation_duration': 40.1384063065052,
'central_time': 7916.773870512843,
'immersion_time': 7896.7046673595905,
'emersion_time': 7936.843073666096,
'time_err': 0.05011036992073059,
'depth': 0.8663887801707082,
'depth_err': 0.10986223384336465,
'baseline': 0.9110181732552853,
'baseline_err': 0.19045768512595365,
'snr': 7.886138392251848,
'occ_mask': array([False, False, False, ..., False, False, False])}

Complementary functions

sora.lightcurve.utils.calc_fresnel(distance, bandpass)[source]

Calculates the Fresnel scale.

Fresnel Scale = square root of half the multiplication of wavelength and object distance.

Parameters

  • distance (int, float array) – Distances, in km.

  • bandpass (int, float, array) – Wavelength, in km.

Returns

fresnel_scale – Fresnel scale, in km.

Return type

float, array

sora.lightcurve.utils.calc_magnitude_drop(mag_star, mag_obj)[source]

Determines the magnitude drop of the occultation.

Parameters

  • mag_star (int, float) – Star magnitude.

  • mag_obj (int, float) – Object apparent magnitude to the date.

Returns

  • mag_drop (float) – Magnitude drop for the given magnitudes.

  • bottom_flux (float) – Normalized bottom flux for the given magnitudes.