""".. _plot_b21a_multiple_models:

21a. Assisted specification
===========================

 Example of the estimation of several versions of the model using
 assisted specification algorithm. The catalog of specifications is
 defined in :ref:`plot_b21b_multiple_models_spec`. All specifications
 are estimated. Have a look at :ref:`plot_b22a_multiple_models` for an
 example where the number of specifications is too high to be
 enumerated.

Michel Bierlaire, EPFL
Sat Jun 28 2025, 19:21:26
"""

import biogeme.biogeme_logging as blog
from biogeme.assisted import AssistedSpecification
from biogeme.multiobjectives import loglikelihood_dimension
from biogeme.results_processing import compile_estimation_results

from plot_b21b_multiple_models_spec import PARETO_FILE_NAME, the_biogeme

logger = blog.get_screen_logger(blog.INFO)
logger.info('Example b21a_multiple_models')

# %%
# Creation of the object capturing the assisted specification algorithm.
# Its constructor takes three arguments:
#
#    - the biogeme object containing the specifications and the
#      database,
#    - an object defining the objectives to minimize. Here, we use the
#      opposite of the log likelihood and the number of estimated
#      parameters.
#    - the name of the file where the estimated are saved, and
#      organized into a Pareto set.
assisted_specification = AssistedSpecification(
    biogeme_object=the_biogeme,
    multi_objectives=loglikelihood_dimension,
    pareto_file_name=PARETO_FILE_NAME,
)

# %%
# The algorithm is run.
non_dominated_models = assisted_specification.run()

# %%
summary, description = compile_estimation_results(
    non_dominated_models, use_short_names=True
)
print(summary)

# %%
# Explanation of the short names of the model.
for k, v in description.items():
    if k != v:
        print(f'{k}: {v} AIC={summary.at["Akaike Information Criterion", k]}')