Organiser les paramètres du modèle

[Mind-the-Cap]

Besoin : organiser les paramètres du modèle pour donner plus de clarté aux utilisateurs (pourquoi tel paramètre est calibré ainsi par défaut, à quel point peut-on le changer, etc.) et pour permettre une analyse de sensibilité semi-automatique.

Proposition de @FlxPo :
Créer une classe Parameter pour remplacer les valeurs de paramètres brutes par des objets contenant à la fois les valeurs des paramètres et des métadonnées :
• Nom
• Définition
• Valeurs possibles (intervalle, valeurs uniques…)
• Valeur par défaut
• Source des valeurs par défaut
• Type de paramètre (hypothèse comportementale, paramètre de simulation…)

[FlxPo]

We now have a model for how to do this with Pydantic models, see this PR : #258.
Sensitivity analysis metadata are not handled for now but can be added with the json_schema_extra arg when creating a pydantic Field.

The API is quite clean and we can leverage the features of pydantic such as post init logic, constraint enforcement...
A first example can be seen in : https://github.com/mobility-team/mobility/blob/main/mobility/choice_models/population_trips_parameters.py

class PopulationTripsParameters(BaseModel):

    model_config = ConfigDict(extra="forbid")

    n_iterations: Annotated[
        int,
        Field(
            default=1,
            ge=1,
            title="Number of iterations",
            description=(
                "Number of simulation iterations used to compute the population "
                "trips. Increase this to get more diverse programmes and to allow "
                "congestion feedbacks to propagate."
            ),
        ),
    ]

    alpha: Annotated[
        float,
        Field(
            default=0.01,
            ge=0.0,
            title="Next anchor cost weighting",
            description=(
                "Weight of the cost to get to the next anchor destination in the "
                "chain when considering destination options (shopping place when "
                "the next anchor is work, for example) and computing probabilities."
            ),
        ),
    ]

[FlxPo]

Issue traitée (hors sensibilité) dans : #240

[matt-gau]

Le markdown que j'obtiens en appelant la méthode parameters_markdown() est il censé pouvoir etre juste copié collé dans un cellule markdown de notebook par ex ? Dans mon cas, il produit des sauts de ligne '\n' qui ne sont pas gérés et le md n'est donc pas bien formatté.
(PS: Je ne sais pas si j'écris au bon endroit @FlxPo)

(petit bout de log:)
"# Parameters Report\n\n## Summary\n\n- Root asset: PopulationTrips\n- Recursive scan: True\n- Assets with parameters: 25\n- Parameter models found: 19\n- Total parameter fields: 197\n\n## Asset PopulationTrips\n\nAsset type: PopulationTrips\n\n### Model PopulationTripsParameters\n\n#### alpha\n- Path: PopulationTrips.parameters.alpha\n- Value: 0.01\n- Default: 0.01\n- Value source: default\n- Constraints: {'minimum': 0.0}\n- Title: Next anchor cost weighting\n- Description: Weight of the cost to get to the next anchor destination in the chain when considering destination options (shopping place when the next anchor is work, for example) and computing probabilities.\n\n#### cost_uncertainty_sd\n- Path: PopulationTrips.parameters.cost_uncertainty_sd\n- Value: 1.0\n- Default: 1.0\n- Value source: default\n- Constraints: {'exclusiveMinimum': 0.0}\n- Title: Standard deviation of travel costs estimates\n- Description: Travel costs are estimated between specific representative points located in transport zones, but the actual travel costs between all origins and all destinations in the transport zones will be slightly different than these point estimates. cost_uncertainty_sd controls how uncertain are these estimates, and spreads the opportunities in the destination transport zone based on a normal distribution centered on the point estimates and a standard deviation of cost_uncertainty_sd.\n\n#### dest_prob_cutoff\n- Path: PopulationTrips.parameters.dest_prob_cutoff\n- Value: 0.99\n- Default: 0.99\n- Value source: default\n- Constraints: {'maximum': 1.0, 'exclusiveMinimum': 0.0}\n- Title: Destination probability distribution cutoff\n- Description: Cutoff used to prune the less probable destinations for a given origin. Only the first dest_prob_cutoff % of the cumulative distribution is considered.\n\n#### k_mode_sequences\n- Path: PopulationTrips.parameters.k_mode_sequences\n- Value: 6\n- Default: 6\n- Value source: default\n- Constraints: {'minimum': 1}\n- Title: Number of mode combinations\n- Description: Number of mode combinations considered in the simulation, for a given destination sequence. Only the top k combinations are considered.\n\n#### min_activity_time_constant\n- Path: PopulationTrips.parameters.min_activity_time_constant\n- Value: 1.0\n- Default: 1.0\n- Value source: default\n- Constraints: {'minimum': 0.0}\n- Title: Minimum activity time coefficient\n- Description: Coefficient controlling the minimum activity time necessary to get a positive utility from the activity. This minimum time is equal to average_activity_time x exp(-min_activity_time_constant).\n\n#### mode_sequence_search_parallel\n- Path: PopulationTrips.parameters.mode_sequence_search_parallel\n- Value: False\n- Default: True\n- Value source: explicit\n- Title: Parallel mode for the top k mode sequence search\n- Description: Set to False to debug or for small simulations, otherwise set to True to speed up the simulation.\n\n#### n_iter_per_cost_update\n- Path: PopulationTrips.parameters.n_iter_per_cost_update\n- Value: 3\n- Default: 3\n- Value source: default\n- Constraints: {'minimum': 0}\n- Title: Travel costs update period\n- Description: ('The simulation will update the travel costs every n_iter_per_cost_update. ', 'Set n_iter_per_cost_update to zero to ignore congestion in the simulation, set to 1 to update congestion at each iteration, set to a higher level to speed up the simulation.')\n\n#### n_iterations\n- Path: PopulationTrips.parameters.n_iterations\n- Value: 1\n- Default: 1\n- Value source: default\n- Constraints: {'minimum': 1}\n- Title: Number of iterations\n- Description: Number of simulation iterations used to compute the population trips. Increase this to get more diverse programmes and to allow congestion feedbacks to propagate.\n\n#### seed\n- Path: PopulationTrips.parameters.seed\n- Value: 0\n- Default: 0\n- Value source: default\n- Constraints: {'minimum': 0}\n- Title: Simulation seed\n- Description: Seed used to get reproducible results for stochastic simulation steps (like destination sampling when building destination chains). Change this value to get new programmes and results for a given set of inputs.\n\n#### simulate_weekend\n- Path: PopulationTrips.parameters.simulate_weekend\n- Value: False\n- Default: False\n- Value source: default\n- Title: Week day only or week day + weekend day mode\n- Description: Wether to simulate a weekend day or only a week day.\n\n## Asset PopulationTrips.costs_aggregator.bicycle\n\nAsset type: PathGeneralizedCost\n\n### Model GeneralizedCostParameters\n\n#### cost_constant\n- Path: PopulationTrips.costs_aggregator.bicycle.parameters.cost_constant\n- Alternate asset paths: ['PopulationTrips.costs_aggregator.bicycle', 'PopulationTrips.modes[2].generalized_cost']\n- Alternate field paths: ['PopulationTrips.costs_aggregator.bicycle.parameters.cost_constant', 'PopulationTrips.modes[2].generalized_cost.parameters.cost_constant']\n- Value: 0.0\n- Default: 0.0\n- Value source: explicit\n\n#### cost_of_distance\n- Path:

[FlxPo]

Pour le moment tu peux :

• Copier coller dans une visionneuse markdown (https://markdownlivepreview.com/ par exemple).
• Ecrire le string dans un fichier puis ouvrir ce fichier dans une visionneuse (VS code par exemple).

Dans un notebook tu devrais pouvoir faire :

from IPython.display import Markdown
Markdown(asset.parameters_markdown())