RW

class biophysics_fitting.exploration_from_seedpoint.RW.RW(df_seeds=None, param_ranges=None, params_to_explore=None, evaluation_function=None, MAIN_DIRECTORY=None, min_step_size=0, max_step_size=0.02, checkpoint_every=100, checkpoint_by_time=None, n_iterations=60000, mode=None, mode_condition_fun=None, aim_params=None, stop_n_inside_with_aim_params=-1)

Class to perform RW exploration from a seedpoint.

Parameters:
df_seeds : pd.DataFrame

individual seed points as rows and the parameters as columns

param_ranges : pd.DataFrame

parameters as rows and has a min_ and max_ column denoting range of values this parameter may take

params_to_explore : list

list of parameters that should be explored. If None, all parameters are explored.

evaluation_function : Callable

takes one argument (a new parameter vector) and returns: - inside: boolean that indicates if the parameter vector is within experimental constraits (i.e. results in acceptable physiology) or not. - evaluation: dictionary that will be saved alongside the parameters. For example, this should contain ephys features.

checkpoint_every : int

iteration interval at which the results are saved e.i., n for checkpointing every n iterations. If both checkpoint_every and checkpoint_by_time are set, checkpointing will be done by time.

checkpoint_by_time : float

time interval (in minutes) at which results are saved e.i., n for checkpointing every n minutes. If both checkpoint_every and checkpoint_by_time are set, checkpointing will be done by time.

mode : str

Random walk mode. Options: (None, ‘expand’, ‘custom’). If none, no additional constraints will be considered when proposing new points. ‘expand’: only propose new points that move further away from seedpoint ‘custom’: use custom conditions to propose new points. If this mode is used, mode_condition_fun must be provided to evaluate the new points. Default: None

mode_condition_fun : Callable

A function that takes a parameter vector and returns a boolean indicating if the proposed point is acceptable. Used if mode is set to custom.

aim_params : dict

this param will make the exploration algorithm propose only new points such that a set of parameters aims certain values during exploration. Default: {}

stop_n_inside_with_aim_params : int

number of successful models / set of parameters inside space with aim_params to find before stopping exploration

MAIN_DIRECTORY : str

output directory in which results are stored.

Attributes:
df_seeds

individual seed points as rows and the parameters as columns

Type:

pd.DataFrame

param_ranges

parameters as rows and has a min_ and max_ column denoting range of values this parameter may take

Type:

pd.DataFrame

params_to_explore

list of parameters that should be explored. If None, all parameters are explored.

Type:

list

evaluation_function

Function use to evaluate a vector of biphysical parameters. Must take one argument (a parameter vector as a pd.Series) and return a tuple of (inside, evaluation):

  • inside (bool): Boolean that indicates if the parameter vector is within experimental constraits (i.e. results in acceptable physiology) or not.

  • evaluation (dict|:class:pd.DataFrame`|:class:`pd.Series): Evaluation metrics, containing relevant evaluation metrics, and their corresponing parameters.

This function is usually evaluation_function_incremental_helper().

Type:

Callable

MAIN_DIRECTORY

output directory in which results are stored.

Type:

str

min_step_size

minimum step size for the random walk

Type:

float

max_step_size

maximum step size for the random walk

Type:

float

checkpoint_every

save the results every n iterations

Type:

int

checkpoint_by_time

time interval in minutes for checkpointing for using time-based checkpointing. If both checkpoint_every and checkpoint_by_time are set, checkpointing will be done by time.

Type:

float

n_iterations

number of iterations to run the random walk

Type:

int

mode

Random walk mode. Options: (None, ‘expand’, ‘custom’). default: None ‘expand’: only propose new points that move further away from seedpoint ‘custom’: use custom conditions to propose new points. If this mode is used, mode_condition_fun must be provided to evaluate the new points.

Type:

str

mode_condition_fun

Function that takes a parameter vector and returns a boolean indicating whether the point is acceptable or not. This function is used in ‘custom’ mode to propose new points.

Type:

Callable

aim_params

this param will make the exploration algorithm propose only new points such that a set of parameters aims certain values during exploration. Default: {}

Type:

dict

stop_n_inside_with_aim_params

number of successful models / set of parameters inside space with aim_params to find before stopping exploration

Type:

int

normalized_aim_params

normalized aim parameters

Type:

pd.Series

Methods:

_normalize_params(p)

Normalize parameters to be between 0 and 1.

_unnormalize_params(p)

Unnormalize parameters to be between min and max.

_normalize_aim_params(aim_params)

Normalize aim parameters to be between 0 and 1.

assess_aim_params_reached(normalized_params, tolerance)

Check whether the aim parameters have been reached.

_ensure_direction_toward_aim(movement, reached_aim_params, seed_pt_pd)

Ensure that the movement is in the right direction for the aim parameters,

_check_movement_towards_aim(current_np, proposal)

Check if the proposed parameters are closer to the aim parameters than the current parameters.

_flag_aim_params_success(seed_dir)

Create a flag in the seedpoint directory to indicate that aim parameters have been reached

_save_checkpoint(iteration, out, op_dir)

Save the results saved in “out” to a pickle file.

_propose_new_position(p_normalized_np, seed_normalized_np, dist, reached_aim_params, seed_pt_pd)

Propose a new position to move to in the parameter space.

_concatenate_and_clean(seed_folder, particle_id)

Concatenate the intermediate .pickle results and save as one parquet file.

_clean_the_pickles(outdir, files, iteration)

Remove the pickle files that correspond to the intermediate results of a iteration.

_load_pickle_or_parquet(outdir, iteration, mode)

Load the results of a iteration from a pickle or parquet file.

_load_existing_exploration(OPERATION_DIR, iteration_files, file_list)

Load the existing exploration results from the specified directory to continue the random walk.

run_RW(selected_seedpoint, particle_id, seed)

Run random walk exploration from a seed point.