petab_select.candidate_space
Classes and methods related to candidate spaces.
Functions
|
Get a candidate space class, given its method name. |
Classes
|
The backward method class. |
|
The brute-force method class. |
|
A base class for collecting candidate models. |
|
The FAMoS method class. |
|
The forward method class. |
|
Find models with the same number of estimated parameters. |
- class petab_select.candidate_space.BackwardCandidateSpace(*args, predecessor_model=None, max_steps=None, **kwargs)[source]
The backward method class.
- __init__(*args, predecessor_model=None, max_steps=None, **kwargs)
- accept(model, distance)
Add a candidate model to the candidate space.
- Parameters:
- Return type:
FIXME(dilpath) #keep_others: # Whether to keep other models that were previously added to the # candidate space.
- consider(model)
Add a candidate model, if it should be added.
- Parameters:
model (
Optional[Model]) – The candidate model. This value may beNoneif theModelSubspacedecided to exclude the model that would have been sent.- Return type:
- Returns:
Whether it is OK to send additional models to the candidate space. For example, if the limit of the number of accepted models has been reached, then no further models should be sent.
FIXME(dilpath) TODO change to return whether the model was accepted, and instead add self.continue to determine whether additional models should be sent.
- distance(model)
Compute the distance between two models that are neighbors.
- distances_in_estimated_parameters(model, predecessor_model=None)
Distance between two models in model space, using different metrics.
All metrics are in terms of estimated parameters.
- Metrics:
- l1:
The L_1 distance between two models.
- size:
The difference in the number of estimated parameters between two models.
- exclude(model)
Exclude model(s) from future consideration.
- exclude_hashes(hashes)
Exclude models from future consideration, by hash.
- is_plausible(model)
Determine whether a candidate model is plausible.
A plausible model is one that could possibly be chosen by model selection method, in the absence of information about other models in the model space.
For example, given a forward selection method that starts with an initial model
self.predecessor_modelthat has no estimated parameters, then only models with one or more estimated parameters are plausible.
- reset(predecessor_model=None, exclusions=None, limit=None)
Reset the candidate models, optionally reinitialize with a model.
- update_after_calibration(*args, **kwargs)
Do work in the candidate space after calibration.
For example, this is used by the
FamosCandidateSpaceto switch methods.Different candidate spaces require different arguments. All arguments are here, to ensure candidate spaces can be switched easily and still receive sufficient arguments.
- wrap_search_subspaces(search_subspaces)
Decorate the subspace searches of a model space.
Used by candidate spaces to perform changes that alter the search. See
BidirectionalCandidateSpacefor an example, where it’s used to switch directions.
- class petab_select.candidate_space.BruteForceCandidateSpace(*args, **kwargs)[source]
The brute-force method class.
- accept(model, distance)
Add a candidate model to the candidate space.
- Parameters:
- Return type:
FIXME(dilpath) #keep_others: # Whether to keep other models that were previously added to the # candidate space.
- consider(model)
Add a candidate model, if it should be added.
- Parameters:
model (
Optional[Model]) – The candidate model. This value may beNoneif theModelSubspacedecided to exclude the model that would have been sent.- Return type:
- Returns:
Whether it is OK to send additional models to the candidate space. For example, if the limit of the number of accepted models has been reached, then no further models should be sent.
FIXME(dilpath) TODO change to return whether the model was accepted, and instead add self.continue to determine whether additional models should be sent.
- distance(model)
Compute the distance between two models that are neighbors.
- distances_in_estimated_parameters(model, predecessor_model=None)
Distance between two models in model space, using different metrics.
All metrics are in terms of estimated parameters.
- Metrics:
- l1:
The L_1 distance between two models.
- size:
The difference in the number of estimated parameters between two models.
- exclude(model)
Exclude model(s) from future consideration.
- exclude_hashes(hashes)
Exclude models from future consideration, by hash.
- is_plausible(model)
Determine whether a candidate model is plausible.
A plausible model is one that could possibly be chosen by model selection method, in the absence of information about other models in the model space.
For example, given a forward selection method that starts with an initial model
self.predecessor_modelthat has no estimated parameters, then only models with one or more estimated parameters are plausible.
- reset(predecessor_model=None, exclusions=None, limit=None)
Reset the candidate models, optionally reinitialize with a model.
- update_after_calibration(*args, **kwargs)
Do work in the candidate space after calibration.
For example, this is used by the
FamosCandidateSpaceto switch methods.Different candidate spaces require different arguments. All arguments are here, to ensure candidate spaces can be switched easily and still receive sufficient arguments.
- wrap_search_subspaces(search_subspaces)
Decorate the subspace searches of a model space.
Used by candidate spaces to perform changes that alter the search. See
BidirectionalCandidateSpacefor an example, where it’s used to switch directions.
- class petab_select.candidate_space.CandidateSpace(method, predecessor_model=None, exclusions=None, limit=inf, summary_tsv=None, previous_predecessor_model=None)[source]
A base class for collecting candidate models.
The intended use of subclasses is to identify suitable models in a model space, that will be provided to a model selection method for selection.
- distances
The distances of all candidate models from the initial model.
FIXME(dilpath) change list to int? Is storage of more than one value useful?
- predecessor_model
The model used for comparison, e.g. for stepwise methods.
- previous_predecessor_model
The previous predecessor model.
- models
The current set of candidate models.
- exclusions
A list of model hashes. Models that match a hash in
exclusionswill not be accepted into the candidate space. The hashes of models that are accepted are added toexclusions.
- limit
A handler to limit the number of accepted models.
- method
The model selection method of the candidate space.
- governing_method
Used to store the search method that governs the choice of method during a search. In some cases, this is always the same as the method attribute. An example of a difference is in the bidirectional method, where
governing_methodstores the bidirectional method, whereas method may also store the forward or backward methods.
- summary_tsv
A string or
pathlib.Path. A summary of the model selection progress will be written to this file.
FIXME(dilpath) #limited: # A descriptor that handles the limit on the number of accepted models. #limit: # Models will fail self.consider if len(self.models) >= limit.
- __init__(method, predecessor_model=None, exclusions=None, limit=inf, summary_tsv=None, previous_predecessor_model=None)[source]
- accept(model, distance)[source]
Add a candidate model to the candidate space.
- Parameters:
- Return type:
FIXME(dilpath) #keep_others: # Whether to keep other models that were previously added to the # candidate space.
- consider(model)[source]
Add a candidate model, if it should be added.
- Parameters:
model (
Optional[Model]) – The candidate model. This value may beNoneif theModelSubspacedecided to exclude the model that would have been sent.- Return type:
- Returns:
Whether it is OK to send additional models to the candidate space. For example, if the limit of the number of accepted models has been reached, then no further models should be sent.
FIXME(dilpath) TODO change to return whether the model was accepted, and instead add self.continue to determine whether additional models should be sent.
- distances_in_estimated_parameters(model, predecessor_model=None)[source]
Distance between two models in model space, using different metrics.
All metrics are in terms of estimated parameters.
- Metrics:
- l1:
The L_1 distance between two models.
- size:
The difference in the number of estimated parameters between two models.
- is_plausible(model)[source]
Determine whether a candidate model is plausible.
A plausible model is one that could possibly be chosen by model selection method, in the absence of information about other models in the model space.
For example, given a forward selection method that starts with an initial model
self.predecessor_modelthat has no estimated parameters, then only models with one or more estimated parameters are plausible.
- reset(predecessor_model=None, exclusions=None, limit=None)[source]
Reset the candidate models, optionally reinitialize with a model.
- update_after_calibration(*args, **kwargs)[source]
Do work in the candidate space after calibration.
For example, this is used by the
FamosCandidateSpaceto switch methods.Different candidate spaces require different arguments. All arguments are here, to ensure candidate spaces can be switched easily and still receive sufficient arguments.
- class petab_select.candidate_space.FamosCandidateSpace(*args, predecessor_model=None, critical_parameter_sets=[], swap_parameter_sets=[], method_scheme=None, n_reattempts=0, consecutive_laterals=False, **kwargs)[source]
The FAMoS method class.
This candidate space implements and extends the original FAMoS algorithm (doi: 10.1371/journal.pcbi.1007230).
- critical_parameter_sets
A list of lists, where each inner list contains parameter IDs. All models must estimate at least 1 parameter from each critical parameter set.
- swap_parameter_sets
A list of lists, where each inner list contains parameter IDs. The lateral moves in FAMoS are constrained to be between parameters that exist in the same swap parameter set.
- method_scheme
A dictionary that specifies how to switch between methods when the current method doesn’t produce a better model. Keys are n-tuples that described a pattern of length n methods. Values are methods. If the previous methods match the pattern in the key, then the method in the value will be used next. The order of the dictionary is important: only the first matched pattern will be used. Defaults to the method scheme described in the original FAMoS publication.
- n_reattempts
Integer. The total number of times that a jump-to-most-distance action will be performed, triggered whenever the model selection would normally terminate. Defaults to no reattempts (
0).
- consecutive_laterals
Boolean. If
True, the method will continue performing lateral moves while they produce better models. Otherwise, the method scheme will be applied after one lateral move.
- __init__(*args, predecessor_model=None, critical_parameter_sets=[], swap_parameter_sets=[], method_scheme=None, n_reattempts=0, consecutive_laterals=False, **kwargs)[source]
- accept(model, distance)
Add a candidate model to the candidate space.
- Parameters:
- Return type:
FIXME(dilpath) #keep_others: # Whether to keep other models that were previously added to the # candidate space.
- check_critical(model)[source]
Check if the model contains all necessary critical parameters
- Return type:
- check_swap(model)[source]
Check if parameters that are swapped are contained in the same swap parameter set.
- Return type:
- consider(model)[source]
Re-define
considerof FAMoS to be theconsidermethod of theinner_candidate_space. Update all the attributes changed in theconsidermethod.- Return type:
- distance(model)
Compute the distance between two models that are neighbors.
- distances_in_estimated_parameters(model, predecessor_model=None)
Distance between two models in model space, using different metrics.
All metrics are in terms of estimated parameters.
- Metrics:
- l1:
The L_1 distance between two models.
- size:
The difference in the number of estimated parameters between two models.
- exclude(model)
Exclude model(s) from future consideration.
- exclude_hashes(hashes)
Exclude models from future consideration, by hash.
- get_most_distant(calibrated_models)[source]
Get most distant model to all the checked models. We take models from the sorted list of best models (
self.best_models) and construct complements of these models. For all these complements we compute the distance in number of different estimated parameters to all models from history. For each complement we take the minimum of these distances as it’s distance to history. Then we choose the complement model with the maximal distance to history.TODO: Next we check if this model is contained in any subspace. If so we choose it. If not we choose the model in a subspace that has least distance to this complement model.
- Return type:
- insert_model_into_best_models(model_to_insert, criterion)[source]
Inserts a model into the list of best_models which are sorted w.r.t. the criterion specified.
- Return type:
- is_plausible(model)[source]
Determine whether a candidate model is plausible.
A plausible model is one that could possibly be chosen by model selection method, in the absence of information about other models in the model space.
For example, given a forward selection method that starts with an initial model
self.predecessor_modelthat has no estimated parameters, then only models with one or more estimated parameters are plausible.
- jump_to_most_distant(calibrated_models)[source]
Jump to most distant model with respect to the history of all calibrated models.
- reset(predecessor_model=None, exclusions=None, limit=None)
Reset the candidate models, optionally reinitialize with a model.
- reset_accepted()[source]
Changing the reset_accepted to reset the
inner_candidate_spaceas well.- Return type:
- set_predecessor_model(predecessor_model)[source]
Setting the predecessor model for the
inner_candidate_spaceas well.
- switch_inner_candidate_space(exclusions)[source]
Switch the inner candidate space to match the current method.
- switch_method(calibrated_models)[source]
Switch to the next method with respect to the history of methods used and the switching scheme in
self.method_scheme.- Return type:
- update_after_calibration(*args, calibrated_models, newly_calibrated_models, criterion, **kwargs)[source]
See CandidateSpace.update_after_calibration.
- Return type:
- update_from_newly_calibrated_models(newly_calibrated_models, criterion)[source]
Update
self.best_modelswith the latestnewly_calibrated_modelsand determine if there was a new best model. If so, returnFalse.Trueotherwise.- Return type:
- wrap_search_subspaces(search_subspaces)[source]
Decorate the subspace searches of a model space.
Used by candidate spaces to perform changes that alter the search. See
BidirectionalCandidateSpacefor an example, where it’s used to switch directions.- Parameters:
search_subspaces – The method that searches the subspaces of a model space.
- class petab_select.candidate_space.ForwardCandidateSpace(*args, predecessor_model=None, max_steps=None, **kwargs)[source]
The forward method class.
- direction
1for the forward method,-1for the backward method.
- max_steps
Maximum number of steps forward in a single iteration of forward selection. Defaults to no maximum (
None).
- accept(model, distance)
Add a candidate model to the candidate space.
- Parameters:
- Return type:
FIXME(dilpath) #keep_others: # Whether to keep other models that were previously added to the # candidate space.
- consider(model)
Add a candidate model, if it should be added.
- Parameters:
model (
Optional[Model]) – The candidate model. This value may beNoneif theModelSubspacedecided to exclude the model that would have been sent.- Return type:
- Returns:
Whether it is OK to send additional models to the candidate space. For example, if the limit of the number of accepted models has been reached, then no further models should be sent.
FIXME(dilpath) TODO change to return whether the model was accepted, and instead add self.continue to determine whether additional models should be sent.
- distances_in_estimated_parameters(model, predecessor_model=None)
Distance between two models in model space, using different metrics.
All metrics are in terms of estimated parameters.
- Metrics:
- l1:
The L_1 distance between two models.
- size:
The difference in the number of estimated parameters between two models.
- exclude(model)
Exclude model(s) from future consideration.
- exclude_hashes(hashes)
Exclude models from future consideration, by hash.
- is_plausible(model)[source]
Determine whether a candidate model is plausible.
A plausible model is one that could possibly be chosen by model selection method, in the absence of information about other models in the model space.
For example, given a forward selection method that starts with an initial model
self.predecessor_modelthat has no estimated parameters, then only models with one or more estimated parameters are plausible.
- reset(predecessor_model=None, exclusions=None, limit=None)
Reset the candidate models, optionally reinitialize with a model.
- update_after_calibration(*args, **kwargs)
Do work in the candidate space after calibration.
For example, this is used by the
FamosCandidateSpaceto switch methods.Different candidate spaces require different arguments. All arguments are here, to ensure candidate spaces can be switched easily and still receive sufficient arguments.
- wrap_search_subspaces(search_subspaces)
Decorate the subspace searches of a model space.
Used by candidate spaces to perform changes that alter the search. See
BidirectionalCandidateSpacefor an example, where it’s used to switch directions.
- class petab_select.candidate_space.LateralCandidateSpace(*args, predecessor_model, max_steps=None, **kwargs)[source]
Find models with the same number of estimated parameters.
- __init__(*args, predecessor_model, max_steps=None, **kwargs)[source]
- Additional args:
- max_number_of_steps:
Maximal allowed number of swap moves. If 0 then there is no maximum.
- accept(model, distance)
Add a candidate model to the candidate space.
- Parameters:
- Return type:
FIXME(dilpath) #keep_others: # Whether to keep other models that were previously added to the # candidate space.
- consider(model)
Add a candidate model, if it should be added.
- Parameters:
model (
Optional[Model]) – The candidate model. This value may beNoneif theModelSubspacedecided to exclude the model that would have been sent.- Return type:
- Returns:
Whether it is OK to send additional models to the candidate space. For example, if the limit of the number of accepted models has been reached, then no further models should be sent.
FIXME(dilpath) TODO change to return whether the model was accepted, and instead add self.continue to determine whether additional models should be sent.
- distance(model)
Compute the distance between two models that are neighbors.
- distances_in_estimated_parameters(model, predecessor_model=None)
Distance between two models in model space, using different metrics.
All metrics are in terms of estimated parameters.
- Metrics:
- l1:
The L_1 distance between two models.
- size:
The difference in the number of estimated parameters between two models.
- exclude(model)
Exclude model(s) from future consideration.
- exclude_hashes(hashes)
Exclude models from future consideration, by hash.
- is_plausible(model)[source]
Determine whether a candidate model is plausible.
A plausible model is one that could possibly be chosen by model selection method, in the absence of information about other models in the model space.
For example, given a forward selection method that starts with an initial model
self.predecessor_modelthat has no estimated parameters, then only models with one or more estimated parameters are plausible.
- reset(predecessor_model=None, exclusions=None, limit=None)
Reset the candidate models, optionally reinitialize with a model.
- update_after_calibration(*args, **kwargs)
Do work in the candidate space after calibration.
For example, this is used by the
FamosCandidateSpaceto switch methods.Different candidate spaces require different arguments. All arguments are here, to ensure candidate spaces can be switched easily and still receive sufficient arguments.
- wrap_search_subspaces(search_subspaces)
Decorate the subspace searches of a model space.
Used by candidate spaces to perform changes that alter the search. See
BidirectionalCandidateSpacefor an example, where it’s used to switch directions.