The SpotCollection object

class loupiotes.spots.SpotCollection(spotmodels=None, target_name=None)

SpotCollection object.

__init__(spotmodels=None, target_name=None)

SpotCollection is initiated from a list of SpotModel provided by the user. Each observation in each spot model should have a unique timestamp.

Parameters:

• spotmodels (list) – list of spotmodels used to build the collection. Optional, default None. If timestamps is provided for each spot model, the list is reordered according to the start times of their light curves.

• target_name (str) – Name of the considered target. Optional, default None.

computeDynamicDistribution(longitude_shift, rolling=False, win_size_time=3, win_size_lon=21, win_type_time='triang', win_type_lon='triang')

Compute new longitudinal distribution according to dynamic correction for longitudes.

computeDynamicLongitudes(longitude_shift)

Compute dynamic longitude with respect to an input longitude shift.

Parameters:

longitude_shift (ndarray) – Must have length self.start_time.shape[0]

computeLatitudinalDistribution()

Compute temporal grid for latitudinally projected distribution.

Returns:

The 2D-grid with latitudinally projected distribution of filling factors.

Return type:

ndarray

computeLightCurve(step=1, shift_max=False, offset=0)

Compute light curve from the ones provided by each spot model.

Returns:

Tuple of arrays with the timestamps, the spot-model light curve, the observed light curve and corresponding uncertainties.

Return type:

tuple of arrays

computeLongitudinalCorrelation(mode='same', step=1, set_threshold=False, std=1, normalise_max=False, normalise_std=True, rolling=False, win_size_time=3, win_size_lon=21, win_type_time='triang', win_type_lon='triang')

Compute correlation of longitudinal distribution.

Parameters:

• mode (str) – mode to use to compute the correlation (see scipy.signal.correlate2d documentation), must be same or full. Optional, default ``same.

• step (int) – Slicing interval on which correlations will be computed.

• set_threshold – set_threshold

• std – std

• normalise_max (bool) – If set to True, each correlation row will be normalised by its maximal value.

• normalise_std (bool) – If set to True, each correlation row will be normalised by the standard deviation product of the distributions that were used to compute it. If this set to True, the function will automatically set normalise_max to False.

• rolling – rolling

• win_size_time – win_size_time

• win_size_lon – win_size_lon

• win_type_time – win_type_time

• win_type_lon – win_type_lon

Returns:

Tuple of arrays with, in the following order, correlation time reference vector (in days), longitudinal coordinates for correlation (in degrees), 2D (time, longitude) correlation map, longitude of max correlation at each time reference (in degrees), corresponding max correlation and migration rate computed from longitude of max correlation (see Lanza et al. 2019), in degree/day.

Return type:

tuple of arrays

computeLongitudinalDistribution(min_theta=0, max_theta=180, correct_visibility=True, rolling=False, win_size_time=3, win_size_lon=21, win_type_time='triang', win_type_lon='triang', correction_factor=1, progress=False, parallelise=False, nodes=8)

Compute temporal grid for longitudinally projected distribution.

Parameters:

• min_theta (float) – Minimum co-latitude to consider for the projected distribution.

• max_theta (float) – Maximum co-latitude to consider for the projected distribution.

• correct_visibility (bool) – Whether to correct or not visibility, following Lanza et al. 2007.

• rolling (bool) – Whether to apply or not a rolling window on the projected distribution.

• win_size_time (int) – Number of time elements to consider in the time direction of the rolling window.

• win_size_lon (int) – Number of longitude elements to consider in the longitude direction of the rolling window.

• win_type_time (str) – Rolling window type in the time direction.

• win_type_lon (str) – Rolling window type in the longitude direction.

• 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.

Returns:

The computed longitudinal distribution.

Return type:

ndarray

computeLongitudinalShift(mean_latitude, omega_eq=None, omega_diff=None, omega_ref=None)

Compute longitudinal shift assuming mean latitude spot clustering and a simple differential rotation profile omega_eq + omega_diff*sin (mean_latitude)**2. Note that rotation frequencies must be provided in rad/s. If not provided, omega_eq, omega_diff and omega_ref are set to solar values.

compute_stamps(date_origin)

Compute time stamps according to the provided origin date.

extractSubCollection(index_start, index_end)

Return a Collection including only index_start``th to ``index_end-1``th spot models. Note that no copy of the spotmodels will be performed so any memory manipulation of them will also affect the original ``Collection.

Returns:

The extracted sub collection.

Return type:

Collection

hasDivergence()

Check if spot models of the collection have divergence and return the indices list corresponding to the collection.spotmodels elements that exhibit divergence. Therefore, if the function returns an empty list, this means that no model from the Collection has divergences.

Returns:

List of index of SpotModels with HMC divergences.

Return type:

List

plotActiveLongitudes(figsize=(8, 4), date_origin=None, phase=False, step=1, shift_longitude=None, threshold=None, scan_shift_up=30, scan_shift_low=30, lon_low_start=0, rebin=10, modulo=None)

Plot active longitudes found with self.searchActiveLongitudes.

plotLatitudinalDistribution(figsize=(6, 6), cmap='Greys', vmin=None, vmax=None, shading='nearest')

Plot latitudinal distribution of the model collection.

Returns:

The plotted figure.

Return type:

matplotlib.pyplot.figure

plotLightCurve(plot_obs=True, ppm=False, xlabel=None, ylabel=None, figsize=(8, 4), marker=None, lw=2, show_errorbars=True, markersize=3, shift_max=False, step=1, offset=0, zero_time_origin=True, date_origin=None, model_scatter_plot=False, s=1, **kwargs)

Plot the Collection light curve.

Parameters:

• plot_obs (bool) – Plot observed light curve together with spot-model light curve.

• ppm (bool) – If set to True, choose a scale in part-per-million.

• xlabel (str) – Label of the x-axis.

• ylabel (str) – Label of the y-axis.

• figsize (tuple) – Figure size.

• marker (str) – Marker to use for the observed light curve.

• lw (float) – Linewidth of the spot model light curve.

• show_errorbars (bool) – Whether to show (or not) observation error bar.

• markersize (float) – Marker size.

• kwargs (dict) – Keyword arguments of matplotlib.pyplot.subplots.

Returns:

The plotted figure.

Return type:

matplotlib.pyplot.figure

plotLongitudinalCorrelation(figsize=(6, 6), cmap='plasma', shading='nearest', vmin=None, vmax=None, time_xaxis=True, colorbar=True, contourf_plot=False, show_contour=False, normalise_max=False, normalise_std=False, levels=None, cmap_contour='cividis_r', zeroline=True, **kwargs)

Plot longitudinal correlation of the model collection.

Parameters:

• figsize (tuple) – figsize

• cmap (string or colormap instance) – cmap

• shading (str) – shading to use for the figure

• vmin (float) – Minimal value for the colormap.

• vmax – Maximal value for the colormap.

• time_xaxis (bool) – If set to True, the time axis will be the x-axis, otherwise the y-axis.

• colorbar (bool) – Set to True to show the colorbar.

• contourf_plot (bool) – If set to True, will create a contour-filled plot.

• show_contour (bool) – Show correlation contour computed with matplotlib.pyplot.contour.

• normalise_max (bool) – If set to True, each correlation row will be normalised by its maximal value.

• levels (array-like) – Levels to use for the contour-filled and contour drawings.

• cmap_contour (str or colormap instance) – Color map to use for the contours.

• kwargs (dict) – Keyword arguments to be passed to matplotlib.pyplot.contour

Returns:

The plotted figure.

Return type:

matplotlib.pyplot.figure

plotLongitudinalDistribution(figsize=(6, 6), cmap='Greys', shading='nearest', vmin=None, vmax=None, time_xaxis=True, colorbar=True, contourf_plot=False, show_contour=False, extend=True, limit_extent=60, brightness_map=False, normalise=False, levels=None, cbar_scinotation=False, percentage=False, shift_longitude=None, date_origin=None, time_ticks=None, lon_label=None, dynamic=False, phi_norm=None, **kwargs)

Plot longitudinal distribution of the model collection.

Parameters:

• figsize (tuple) – figsize

• cmap (string or colormap instance) – cmap

• shading (str) – shading to use for the figure

• vmin (float) – Minimal value for the colormap.

• vmax – Maximal value for the colormap.

• time_xaxis (bool) – If set to True, the time axis will be the x-axis, otherwise the y-axis.

• colorbar (bool) – Set to True to show the colorbar.

• contourf_plot (bool) – If set to True, will create a contour-filled plot.

• show_contour (bool) – Show correlation contour computed with matplotlib.pyplot.contour.

• shift_longitude (float) – Shift longitude of the plotted map of the given quantity, with respect to the reference value of the Collection.

• kwargs (dict) – Keyword arguments to be passed to matplotlib.pyplot.contour

• date_origin (str) – Time stamp of the first plotted element, under the format YYYY-MM-DD. If this option is chosen, the time axis units will be years.

• phi_norm (float) – Normalisation factor to apply on longitude array.

• lon_label (str) – Label to use for longitude axis.

Returns:

The plotted figure.

Return type:

matplotlib.pyplot.figure

plotMaxCorrelation(figsize=(6, 4), color='darkorange', mec='black', marker='o', refsize=300, ms=5, **kwargs)

Plot max correlation value as a function of time.

plotMeanLatitudinalDistribution(figsize=(6, 6), lw=2, color='darkorange', percentage=True, ylim=None)

Plot mean latitudinal distribution of the model collection.

Returns:

The plotted figure.

Return type:

matplotlib.pyplot.figure

plotMeanLongitudinalDistribution(figsize=(6, 6), lw=2, color='darkorange', percentage=True, ylim=None, xlabel=None, shift_longitude=None, dynamic=False, threshold=None, metric='mean', use_norm_for_threshold=False)

Plot mean longitudinal distribution of the model collection.

Returns:

The plotted figure.

Return type:

matplotlib.pyplot.figure

plotMigrationRate(figsize=(6, 6), color='darkorange', edgecolor='black', marker='o', refsize=300)

Plot spots migration rate as the lag derivative, as derived by Lanza et al. 2019.

plotResiduals(ppm=False, xlabel=None, ylabel=None, s=10, bins=30, figsize=(8, 4), marker='o', lw=2, show_errorbars=True, markersize=3, shift_max=False, step=1, offset=0, zero_time_origin=True, date_origin=None, **kwargs)

Plot the Collection residuals.

Parameters:

• ppm (bool) – If set to True, choose a scale in part-per-million.

• xlabel (str) – Label of the x-axis.

• ylabel (str) – Label of the y-axis.

• figsize (tuple) – Figure size.

• marker (str) – Marker to use for the observed light curve.

• lw (float) – Linewidth of the spot model light curve.

• show_errorbars (bool) – Whether to show (or not) observation error bar.

• markersize (float) – Marker size.

• kwargs (dict) – Keyword arguments of matplotlib.pyplot.subplots.

Returns:

The plotted figure.

Return type:

matplotlib.pyplot.figure

searchActiveLongitudes(shift_longitude=None, threshold=None, scan_shift_up=30, scan_shift_low=30, lon_low_start=0, rebin=10, step=1)

Compute longitudes with maximal spotted area along time direction, assuming the existence of two active longitude separated by approximately 180 degrees. Note that this function is experimental and might produce unexpected results.

Returns:

Tuple with the longitude with maximal spotted area, the longitude with maximal spotted area between 0 and 180 degree, and the longitude with maximal spotted area between 180 and 360 degrees.

Return type:

tuple of array