senpy package

Submodules

senpy.neyer module

class senpy.neyer.Neyer(latent='normal', inverted=False, method='L-BFGS-B', num_restarts=3, t1_min=None, t1_max=None, t2_guess=None, precision=8, resolution=None, lower_bound=None, upper_bound=None, hist=False, log_file=None)

Bases: object

The Neyer model. Given an assumed form for the latent distribution, either ‘normal’, ‘logistic’, or ‘log-logistic’, the maximum likelihood estimates of the distribution parameters are computed. Neyer also provides a sequential design algorithm.

Parameters

  • latent (string, optional) – DESCRIPTION. The form of the latent distribution. Either ‘normal’, ‘logistic’, or ‘log-logistic’. The default is ‘normal’.

  • inverted (boolean, optional) – DESCRIPTION. If the probability of a ‘go’ increases as the stimulus level decreases, then the data is ‘inverted’. The default is False.

  • method (string, optional) – DESCRIPTION. Name of the optimization routine called when computing the maximum likelihood estimates. The default is ‘L-BFGS-B’.

  • num_restarts (int, optional) – DESCRIPTION. The number of random initializations to use when maximizing the likelihood function. Note, the available latent distributions only use two parameters. Consequently, the resulting likelihood function is typically convex. The default is 3.

  • t1_min (flaot, optional) – DESCRIPTION. When using the sequential design algorithm and starting with no (or minimal) data, an intial guess on the lower bound of the first parameter, theta_1, is required. For the normal and logistic distributions theta_1 is mu. For the log-logistic distribution theta_1 is alpoha. If None is provided and the sequential algorithm is called, the program will prompt the user for the value. The default is None.

  • t1_max (float, optional) – DESCRIPTION. The initial guess for the upper bound of theta_1. See t1_min for more details. The default is None.

  • t2_guess (float, optional) – DESCRIPTION. The initial guess for theta_2. Required when using the sequential design algorithm. See t1_min for more details. For the normal and logisit distributions, theta_2 is sigma. For the log-logistic distribution, theta_2 is beta. The default is None.

  • precision (int, optional) – DESCRIPTION. Number of decimal points to incude in the final output. The default is 8.

  • resolution (float, optional) – DESCRIPTION. The smallest change in stimulus level available. For example, a drop-weight apparatus may only have adjustments at quarter inch intervals. Thus, the algorithm should not suggest testing at 12.105 inches, etc. The default is None.

  • lower_bound (float, optional) – DESCRIPTION. The lowest stimulus level a user can phsically test. The default is None.

  • upper_bound (float, optional) – DESCRIPTION. The highest stimulus level a user can phsically test. The default is None.

  • hist (boolean, optional) – DESCRIPTION. If True the determinant of the information matrix is computed over a range of stimulus levels at each stage of the sequential design. Typically used for debugging only! The default is False.

  • log_file (str, optional) – DESCRIPTION. File path for a log file. The log consists of the steps taken during the sequential design algorithm. The default is None.

available_opt_methods = ('L-BFGS-B', 'SLSQP', 'TNC')
fit(X, Y)

Compute the maximum likelihood estimates of the distribution parameters.

Parameters

  • X (2D array) – The tested stimulus levels. Must be of shape (n_pts, 1)

  • Y (array) – The observed response at each stimulus level. 1 for ‘go’ and 0 for ‘no-go’.

Returns

Return type

self

get_estimators()

Provides access to the stored estimate of theta. For example, [mu, sigma] or [alpha, beta].

Returns

Current parameter estimates. Shape is (2,)

Return type

array

loop(iterations=1000000)

This method suggests new test levels and accepts user input to calculate maximum likelihood estimates. That is, this method constitutes a loop. Loop will continue indefinitely until ‘end’ is received as user input during the either the test level or result input queries. Alternatively, if a set number of specimens is to be used then the number of loops can be specified with the ‘iterations’ keyword argument.

Parameters

iterations (int, optional) – End the loop automatically after n iterations. The default is 1000000.

Returns

Return type

None.

next_pt()

The sequential design algorithm. When this method is called, the next suggested stimulus level for testing is printed to the console.

Returns

Return type

self

plot_confidence_region(limits, n, CI_levels=10, save_dst=None, show=True)

A high-level function to plot the confidence region of the parameters.

Parameters

  • limits (list) – The plot limits provided as [lower xlim, upper xlim, lower ylim, upper ylim].

  • n (int or list of length 2) – The number locations to sample in the x (theta_1) and y (theta_2) directions.

  • CI_levels (int or list, optional) – If an integer, a filled contour plot will be produced with that many levels. If it is a list, the list values specify the confidence levels at which to draw contour lines. The default is 10.

  • save_dst (str, optional) – The file path (including file type) where the plot should be saved. The default is None

  • show (boolean, optional) – If True, simply calls matplotlib.plt.show(). May be required for some IDEs. The default is True.

Returns

Return type

None.

plot_probability(include_data=True, xlabel=None, ylabel=None, alpha=1.0, save_dst=None, show=True, **kwargs)

A high-level method to call self.predict_probability and plot the result.

Parameters

  • include_data (boolean, optional) – Whether or not to plot the data (stimuli and responses). The default is True.

  • xlabel (str, optional) – If provided, the text for the plot xlabel. The default is None.

  • ylabel (str, optional) – If provided, the text for the plot ylabel. The default is None.

  • alpha (float, optional) – opacity of the observed data points. Must be between 0 and 1. Only used if include_data is True. Useful to visualize many overlapping data points. The default is 1.0.

  • save_dst (str, optional) – The file path (including file type) where the plot should be saved. The default is None.

  • show (boolean, optional) – If True, simply calls matplotlib.plt.show(). May be required for some IDEs. The default is True.

  • **kwargs – All keyworkd arguments provided to predict_probability can also be provided here.

Returns

Return type

None.

post_test_outcome(res, pt)

Append a stimulus level and result to the existing data.

Parameters

  • res (int or boolean) – The observed result at the tested stimulus level. Either 0, 1 or False, True.

  • pt (float) – The stimulus level at which the test was performed.

Returns

Return type

None.

predict_probability(pts=None, confidence=None, CI_level=[0.5, 0.8, 0.9, 0.95], num_samples=1000, max_iter=5)

Returns the probability of a ‘go’ at pts. p(y=0|pt)

Parameters

  • pts (array, optional) – The stimulus levels at which to compute probability predictions. The default is None. If None, range = max(X) - min(X) and pts = np.linspace(min(X)-0.5*range, max(X)+0.5*range, 100)

  • confidence (str, optional) – The name of the method used to supply confidence intervals. Options are ‘delta’, ‘perturbation’ (same as delta), ‘likelihood-ratio’, ‘parametric-bootstrap’, and ‘nonparametric-bootstrap’. The default is None.

  • CI_level (list, optional) – The confidence levels. Ignored if confidence is None. The default is [.5, .8, .9, .95].

  • num_samples (int, optional) – The number of bootstrapped samples generated. Only used if confidence = ‘parametric-bootstrap’ or ‘nonparametric=bootstrap’. The default is 1000.

  • max_iter (int, optional) – The maximum number of attempts to map the likelihood ratio. Only used if confidence = ‘likelihood-ratio’. The default is 5.

Returns

Consists of the stimulus points, the predicted probability, and arrays of the lower bounds and upper bounds of the confidence levels if confidence was requested. (pts (n_pts, 1), predicted probability (n_pts, 1)) or (pts (n_pts, 1), predicted probability (n_pts, 1), lower CI bounds, upper CI bounds) where the shape of lower and upper CI bounds is (n_pts, n_levels)

Return type

tuple

print_estimators(cost=False)

Prints the current parameter estimates to the console.

Parameters

cost (boolean, optional) – If true, the value of the negative log-likelihood, or cost, at the current parameter estimates is also printed to the console. The default is False.

Returns

Return type

None.

Module contents

Created on Sun Mar 22 17:28:13 2020

@author: alexc