Assisted specification

Assisted specification algorithm

biogeme.assisted module

File assisted.py

author:

Michel Bierlaire

date:

Sun Mar 19 17:06:29 2023

New version of the assisted specification using Catalogs

class biogeme.assisted.AssistedSpecification(biogeme_object, multi_objectives, pareto_file_name, max_neighborhood=20)[source]

Bases: ProblemClass

Class defining assisted specification problem for the VNS algorithm.

__init__(biogeme_object, multi_objectives, pareto_file_name, max_neighborhood=20)[source]

Ctor

Parameters:

  • biogeme_object (biogeme.biogeme.BIOGEME) – object containnig the loglikelihood and the database

  • multi_objectives (fct(biogeme.results.bioResults) --> list[float]) – function calculating the objectives to minimize

  • pareto_file_name (str) – file where to read and write the Pareto solutions

  • max_neighborhood (int) – maximum number of neighborhood investigated by the algorithm

is_valid(element)[source]

In this implementation, we condider all models to be valid.

Parameters:

element (class SetElement) – representation of the specification

Returns:

True if the model is valid

Return type:

bool

log_statistics()[source]

Report some statistics about the process in the logger

plot(objective_x=0, objective_y=1, label_x=None, label_y=None, margin_x=5, margin_y=5, ax=None)[source]
Plot the members of the set according to two

objective functions. They determine the x- and y-coordinate of the plot.

Parameters:

  • objective_x – index of the objective function to use for the x-coordinate.

  • objective_x – int

  • objective_y – index of the objective function to use for the y-coordinate.

  • objective_y – int

  • label_x (str) – label for the x_axis

  • label_y (str) – label for the y_axis

  • margin_x (int) – margin for the x axis

  • margin_y (int) – margin for the y axis

  • ax (matplotlib.Axes) – matplotlib axis for the plot

reestimate(recycle)[source]

The assisted specification uses quickEstimate to estimate the models. A complete estimation is necessary to obtain the full estimation results.

run(number_of_neighbors=20)[source]

Runs the VNS algorithm

Returns:

object containing the estimation results associated with the description of each configuration

Return type:

dict(str: bioResults)

statistics()[source]

Report some statistics about the process

Returns:

tuple of messages, possibly empty.

Return type:

tuple(str)

class biogeme.assisted.ParetoPostProcessing(biogeme_object, pareto_file_name)[source]

Bases: object

Class to process an existing Pareto set.

__init__(biogeme_object, pareto_file_name)[source]

Ctor

Parameters:

  • biogeme_object (biogeme.biogeme.BIOGEME) – object containnig the loglikelihood and the database

  • pareto_file_name (str) – file where to read and write the Pareto solutions

log_statistics()[source]

Report some statistics about the process in the logger

plot(objective_x=0, objective_y=1, label_x=None, label_y=None, margin_x=5, margin_y=5, ax=None)[source]
Plot the members of the set according to two

objective functions. They determine the x- and y-coordinate of the plot.

Parameters:

  • objective_x – index of the objective function to use for the x-coordinate.

  • objective_x – int

  • objective_y – index of the objective function to use for the y-coordinate.

  • objective_y – int

  • label_x (str) – label for the x_axis

  • label_y (str) – label for the y_axis

  • margin_x (int) – margin for the x axis

  • margin_y (int) – margin for the y axis

  • ax (matplotlib.Axes) – matplotlib axis for the plot

reestimate(recycle)[source]

The assisted specification uses quickEstimate to estimate the models. A complete estimation is necessary to obtain the full estimation results.

statistics()[source]

Report some statistics about the process

Returns:

tuple of messages, possibly empty.

Return type:

tuple(str)

biogeme.assisted.decrease_configuration(catalog_name, element, size=1)[source]

Change the configuration of a catalog

Parameters:

  • catalog_name (str) – name of the catalog to modify

  • element (class SetElement) – ID of the current specification

  • size (int) – number of increments to apply

Returns:

Representation of the new specification, and number of changes actually made

Return type:

tuple(class SetElement, int)

biogeme.assisted.decrement_several_catalogs(element, size=1)[source]

Increment several catalogs in the specification

Parameters:

  • element (class SetElement) – ID of the current specification

  • size (int) – number of catalofs to modify

Returns:

Id of the neighbor, and actual number of modifications

Return type:

tuple(SetElement, int)

biogeme.assisted.generate_operator(name, the_function)[source]
Generate the operator function that complies with the

requirements, from a function that takes the name of the catalog as an argument.

Parameters:

  • name (str) – name of the catalog

  • the_function (function(str, SetElement, int)) – a function that takes the catalog name, the current element and the size ar argument, and that returns a neighbor.

Returns:

a function that takes the current element and the size ar argument, and that returns a neighbor. It can be used as an operator for the VNS algorithm.

Return type:

function(SetElement, int)

biogeme.assisted.increase_configuration(catalog_name, element, size=1)[source]

Change the configuration of a catalog

Parameters:

  • catalog_name (str) – name of the catalog to modify

  • element (class SetElement) – ID of the current specification

  • size (int) – number of increments to apply

Returns:

Representation of the new specification, and number of changes actually made

Return type:

tuple(class SetElement, int)

biogeme.assisted.increment_several_catalogs(element, size=1)[source]

Increment several catalogs in the specification

Parameters:

  • element (class SetElement) – ID of the current specification

  • size (int) – number of catalofs to modify

Returns:

Id of the neighbor, and actual number of modifications

Return type:

tuple(SetElement, int)

biogeme.assisted.modify_random_catalogs(element, step, size=1)[source]

Modify several catalogs in the specification

Parameters:

  • element (class SetElement) – ID of the current specification

  • step (int) – shift to apply to each catalog

  • size (int) – number of catalofs to modify

Returns:

Id of the neighbor, and actual number of modifications

Return type:

tuple(SetElement, int)

biogeme.assisted.modify_several_catalogs(selected_catalogs, element, step)[source]

Modify several catalogs in the specification

Parameters:

  • selected_catalogs (set(str)) – names of the catalogs to be modified. If a name does not appear in the current configuration, it is ignored.

  • element (class SetElement) – ID of the current specification

  • step (int) – shift to apply to each catalog

  • size (int) – number of catalofs to modify

Returns:

Id of the neighbor, and actual number of modifications

Return type:

tuple(SetElement, int)