Ctrl+K
Ctrl+K

The SpotModel object

The SpotModel object#

class loupiotes.spots.SpotModel(large_dim=(180, 180), reduced_dim=(18, 18), inclination=90, t0=0, omega=2.6e-06, filling_factors=None, limb_darkening_coeff=None, Q=0, cf0=1, cs=1, initialise_grid=True)#

SpotModel object, including all necessary tools to generate spot-modelled light curves.

__init__(large_dim=(180, 180), reduced_dim=(18, 18), inclination=90, t0=0, omega=2.6e-06, filling_factors=None, limb_darkening_coeff=None, Q=0, cf0=1, cs=1, initialise_grid=True)#
Parameters:

  • large_dim (tuple) – Dimension of the large grids of the spot model. First element of the tuple is the number of latitudinal nodes, second element the number of longitudinal nodes. Optional, default (180,180).

  • reduced_dim (tuple) – Dimension of the reduced grids (used to set parameters in common for the large grid). First element of the tuple is the number of latitudinal nodes, second element the number of longitudinal nodes. Optional, default (180,180).

  • inclination (float) – Stellar inclination with respect to the observer (in degrees). Optional, default 90.

  • t0 (float) – Initial time (in days) to consider in the model. Optional, default 0.

  • omega (float or ndarray) – Stellar angular frequency, in rad/Hz. Can be a float or a 1D-array of length reduced_dim[0]. Optional, default 2.6e-6 (solar value)

  • filling_factors (ndarray) – Initial filling factors of the model, must be of reduced_dim dimension. Optional, default None.

  • limb_darkening_coeff (tuple) – Quadratic limb-darkening coefficient, following the formulation of Claret (2000).

  • Q (float) – Ratio between the spot and facula filling factors. Optional, default 0.

  • cf0 (float) – Faculae contrast coefficient.

  • cs (float) – Spot contrast coefficient.

computeFluxGrid()#

Compute the flux grid from the unperturbed reference, taking into account spot and facula coverage.

Returns:

A view of the updated flux grid.

Return type:

ndarray

computeLatitudinalDistribution(normalise_max=False, correct_visibility=True)#

Compute latitudinal distribution of filling factors.

computeLongitudinalDistribution(normalise_max=False, min_theta=0, max_theta=180, correct_visibility=True, correction_factor=1)#

Compute longitudinal distribution of filling factors.

Parameters:

correction_factor (float) – Correction factor to apply on the distribution. Might be useful to renormalise filling factor distribution when analysing pure spots model (Q=0) with arbitrary contrast factors.

computeObservedFlux()#

Use the grids to compute the scalar observed flux in the current configuration.

Returns:

Computed flux value.

Return type:

float

computeUnperturbed()#

Compute the unperturbed flux grid taking into account limb-darkening effects (using a quadratic law).

Returns:

A view of the unperturbed grid.

Return type:

ndarray

computeUnperturbedFlux()#

Use the grids to compute the scalar unperturbed flux in the current configuration.

Returns:

Computed flux value.

Return type:

float

computeVisibilityFraction()#

Compute the visibility correction of surface elements for postprocessing, according to Eq. 8 from Lanza et al. 2007.

In the current implementation, it assumes that datapoints are regularly sampled.

explore_distribution(timestamps, lc_data, err_data=1, prior_distribution_filling_factors='Uniform', initval_filling_factors=None, prior_omega='TruncatedNormal', sigma=0.1, active_latitude=False, beta=1, upper_active_latitude=60, filename=None, maximum_entropy=False, lambda_me=1, new_sampling=True, lower_filling_factors=None, sample_omega=False, sigma_omega=None, ppm=False, sample_Q=False, lower_Q=0, upper_Q=20, sample_cf0=False, lower_cf0=0.05, upper_cf0=0.3, summary_metric='mean', nuts_sampler='pymc', zero_mean=False, use_map=False, maxeval_map=10000, **kwargs)#

Perform a MCMC exploration of the posterior distribution.

Parameters:

  • timestamps (ndarray) – timestamps of the observation contained in lc_data.

  • lc_data (ndarray) – observed values

  • err_data (ndarray or float) – the estimated error on lc_data. Optional, default 1.

  • prior_distribution_filling_factors (str) – prior distribution to consider for the filling factors of the model. Should be Uniform or TruncatedNormal Optional, default TruncatedNormal.

  • sigma (float) – if prior_distribution_filling_factors is TruncatedNormal, standard deviation of the related normal distribution. Optional, default 0.01.

  • draws (int) – number of samples to create with the NUTS sampler. Optional, default 1000.

  • tune (int) – number of samples used for the tuning step of the NUTS sampler. Optional, default 1000.

  • filename (str or Path object) – if provided, the InferenceData object created by the sampling will be saved under filename. Optional, default None.

  • maximum_entropy (bool) – whether to consider or not a maximum entropy problem when sampling the posterior. See Lanza 2016. Optional, default False.

  • lambda_me (float) – value of the Lagrangian multiplier used in the maximum entropy problem. Optional, default 1.

  • new_sampling (bool) – if set to False, the function will simply return the existing idata (in the case where no idata attribute exists, it will proceed with the PyMC sampling).

  • lower_filling_factors (float) – lower bounds for the filling factors distribution (whether it is Uniform or TruncatedNormal).

  • ppm (bool) – If True, the function will consider that the inputs lc_data and err_data normalised in ppm.

  • **kwargs – Any additional argument provided will be passed to pymc.sample.

Returns:

If use_map is False, returns InferenceData from the pyMC sampling. This object is also accessible through the idata attribute of the SpotModel object. If use_map is True, returns the result object from scipy.optimize.minimize.

Return type:

arviz.InferenceData

generateLightCurve(timestamps, use_numba=True, use_pymc=False, use_broadcast=False, zero_mean=False)#

Generate a light curve from the spot model.

After calling this function if use_pymc is False and use_broadcast is False, the grids of the ``SpotModel object will be in the state corresponding to t=timestamps[-1].

Parameters:

  • timestamps (ndarray) – timestamps (in seconds) of the light curve.

  • use_numba (bool) – whether or not to use the numba implementation of the light curve generation function. Optional, default True.

  • use_pymc (bool) – whether to compute a tensorial expression for the light curve rather than returning a light curve array. This is mainly aimed at being used wrapped inside the explore_distribution function. Optional, default False.

  • use_broadcast (bool) – Compute the light curve with a numpy broadcast method rather than using an explicit loop of the elements of timestamps. precomputeBroadcast has to be called first by the SpotModel object. Optional, default False.

  • zero_mean (bool) – if set to True, the mean of the generated light curve will be substracted to ensure that it is zero. Optional, default True.

Returns:

If use_pymc is False, returns the generated 1D light curve, as an array which has length timestamps.size. It is also set as the current value of self.lc. Otherwise, return a tensor object (see pymc and pytensor documentation) that can be used to evaluate the light curve profile.

Return type:

ndarray or pytensor object

generateUnperturbedLightCurve(timestamps, zero_mean=True, normalise=True)#

Generate unperturbed light curve. This is mainly intended to provide a sanity check for grid resolution effects.

getLightCurve()#

Provide stored light curve and corresponding timestamps.

Returns:

The timestamps and light curve arrays as a tuple.

Return type:

tuple of arrays

hasDivergence()#

Check if the idata corresponding to the sampled model has any divergence.

initialiseGeometry()#

Intialise geometric elements of the model.

initialiseGrid()#

Intialise grids of the model.

plotFluxGrid(figsize=(6, 6), cmap='afmhot', show=True, filename=None, dpi=300, projection=None, normscale='linear', plot_unperturbed=False)#

Plot the flux grid as currently observed.

Parameters:

  • figsize (tuple) – Figure size. Optional, default (6,6).

  • cmap (str or Colormap instance) – color map to use. Optional, default afmhot.

  • show (bool) – whether to call plt.show (). Optional, default True.

  • filename (str or Path instance) – if provided, the figure will be saved under this name. Optional, default None.

  • dpi (int) – Optional, default 300.

  • projection (str) – should be mercator, mollweide or None. If None, the projection will be NearsidePerspective from the cartopy module.

  • plot_unperturbed (bool) – if set to True, the Unperturbed grid will be plotted rather than the FluxGrid with spots and faculae. Optional, default False.

Returns:

The matplotlib figure object used to plot the grid.

Return type:

matplotlib.pyplot.figure

plotGrid(gridname='filling_factors', figsize=(6, 6), vmin=None, vmax=None, cmap='binary', show=True, filename=None, dpi=300, projection=None, colorbar=True)#

Plot the chosen grid in its current state.

Parameters:

  • figsize (tuple) – Figure size. Optional, default (6,6).

  • vmin (float) – min value to use with the color map. Optional, default None.

  • vmax (float) – max value to use with the color map. Optional, default None.

  • cmap (str or Colormap instance) – color map to use. Optional, default binary.

  • show (bool) – whether to call plt.show (). Optional, default True.

  • filename (str or Path instance) – if provided, the figure will be saved under this name. Optional, default None.

  • dpi (int) – Optional, default 300.

  • projection (str) – should be mercator, mollweide or None. If None, the projection will be NearsidePerspective from the cartopy module.

  • colorbar (bool) – whether to show the colorbar on the figure. Optional, default True.

Returns:

The matplotlib figure object used to plot the grid.

Return type:

matplotlib.pyplot.figure

plotLatitudinalDistribution(normalise_max=False, figsize=(4, 8), style='classic', cmap='gist_heat_r', ax=None, correct_visibility=True)#

Plot latitudinal distribution of filling factors.

plotLightCurve(timestamps=None, lc_obs=None, err_obs=None, plot_obs=True, ppm=False, unperturbed=False, zero_mean=False, figsize=(8, 4), marker='none', lw=2, xlabel='Time (day)', ylabel=None, show_errorbars=False, color='darkorange', **kwargs)#

Plot light curve corresponding to the spot model, as well as the reference observed light curve when plot_obs is True.

plotLongitudinalDistribution(normalise_max=False, figsize=(8, 4), style='classic', cmap='gist_heat_r', ax=None, correct_visibility=True)#

Plot longitudinal distribution of filling factors.

plotProjectedDistributions(normalise_max=False, figsize=(8, 4), cmap='gist_heat_r', vmin=None, vmax=None, colorbar=True, correct_visibility=True)#

Plot filling factor distributions and corresponding projections along latitude and longitudes.

precomputeBroadcast()#

Precompute arrays that will be necessary to generate light curves in the broadcast mode.

removeBroadcastedElements()#

Remove broadcasted elements and set to None corresponding variables.

removeInferenceData()#

When this function is called, replace existing self.idata by None and reset self.SamplingPerformed attribute to False.

removelcTensor()#

When this function is called, replace existing self.lcTensor by None.

resetAdditionalProperties()#

Reset additional properties. This can be useful to ensure that a spotmodel for an older variation has every required variable names initialised.

save(filename, netcdf_file=None)#

Save the model to filename as pickled file.

Parameters:

  • filename (str or Path instance) – path of the file to be saved.

  • netcdf_file (str or Path instance) – if provided, the InferenceData object (if existing), will also be saved independently under this name.

to_hdf5(filename, create_netcdf=True, override=True)#

Save the model to an hdf5 files.

Parameters:

  • filename (str or Path instance) – path of the hdf5 file where to save the model.

  • create_netcdf (bool) – If set to True and the model has an idata, it will be save to a netcdf file with same basename as the hdf5 file.

updateVisibility(t)#

Update array at a time t.

Parameters:

t (float) – time to consider to update the grids.

Returns:

A view of the updated mu and visibility grids.

Return type:

ndarray

update_from_idata(sample_omega=False, sample_Q=False, sample_cf0=False, active_latitude=False, summary_metric='mean', zero_mean=False)#

Update the state of the Spot model using the sampled Inference Data.

update_from_map_result(map_result, sample_omega=False, sample_Q=False, sample_cf0=False, active_latitude=False, summary_metric='mean', zero_mean=False, multi_channel=False)#

Update the state of the Spot model using the result of the MAP computation.

loupiotes.spots.load_from_hdf5(filename, load_netcdf=True, netcdf_file=None)#

Load spotmodel stored in an hdf5 file.

Parameters:

  • filename (str or Path instance) – path of the hdf5 file to read.

  • load_netcdf (bool) – whether to load the netcdf file with the idata from a sampling. If no file is found, the function will issue a warning.

Returns:

The loaded spotmodel instance.

Return type:

SpotModel

loupiotes.spots.load_spot_model(filename, reset_additional_properties=True)#

Load an existing SpotModel from a pickled file.

Parameters:

  • filename (str or Path instance) – filename of the spotmodel to load.

  • reset_additional_properties (bool) –

Contents