New release for publishing in Journal of Open Source Software.

Fixed

Added

• Python version 3.12 support.
• Support for geopandas v0.15, gdal >= v3.5, and python-Levenshtein v0.26.

Changed

Fixed

• fix person attributes type conversion bug (#263)

Added

Changed

• User install instructions to prefer direct install from mamba (or PyPI if a user is willing to deal with installing non-python libs themselves).

What's Changed

• Post-release updates & fixes by @brynpickering in https://github.com/arup-group/pam/pull/261
• fix bug by @Theodore-Chatziioannou in https://github.com/arup-group/pam/pull/264

Full Changelog: https://github.com/arup-group/pam/compare/v0.3.0...v0.3.1

Fixed

• readme CI badge ([#248])
• plan cropping as per issue [#241] ([#240]).
• [][pam.optimise.grid.grid_search] ([#239]).
• [TourPlanner][pam.samplers.tour.TourPlanner] prevents sampling of duplicate destinations, and prevents origin being sampled as a destination ([#231]).
• [][pam.activity.Plan.simplify_pt_trips] as per issue [#221], improving "pt simplification" ([#222])
• Slow loading of data with e.g., [pam.read.load_travel_diary][pam.read.diary.load_travel_diary] when using pandas v2.1.1 (caused by pandas.MultiIndex.groupby, see pandas issue #55256). ([#258])

Added

• MATSim warm starting example ([#239]).
• Support for MATSim vehicles files ([#215]).
• Anaconda package of PAM, available on the city-modelling-lab channel ([#211]).
• Python versions 3.9 to 3.11 support ([#192], [#210]).
• Documentation, now available at https://arup-group.github.io/pam ([#197]).
• Time-space prism method for selecting the location of non-mandatory activities ([#252]).
• Simple IPF approach for generating synthetic populations ([#253]).
• More control over the look of activity plan plots, with keyword arguments for [][pam.plot.plot_activities] (accessed via e.g. [pam.core.Person.plot]) extended to allow figure width and per-activity label font sizes to be updated ([#249]).

Changed

• Documentation and examples improved ([#239]).
• [TourPlanner][pam.samplers.tour.TourPlanner] class sequences stops using GreedyTSP algorithm, rather than previous method sorting by distance from depot ([#231]).
• Minor changes to docs for zsh users (eg pip install '.[dev]')([#219]).
• Recommended installation instructions, to use mamba instead of pip ([#192], [#211]).
• Docker image entry point from python to bash ([#230]).

Removed

• Example data files not accessed by any example notebook ([#196]).
• ActivityDuration class, replaced with methods in [TourPlanner][pam.samplers.tour.TourPlanner] and in pam.samplers.tour ([#231]).

Allows retaining existing facility locations during facility sampling.

By passing population.sample_locs(sampler, location_override=False) , any activities which already have a location (under act.location.loc will be skipped.

This can be of use when applying hybrid location choice approaches, where part of the location choice is done at zone level (+facility sampling), and part is done directly at facility level.

Introduces abstract mode and location choice modules.

The pam.planner.choice class allows the user to apply a choice model for selecting the location of activities and the mode for accessing them, given person characteristics, network conditions and/or zone attraction data. The module is designed to be extendable, supporting different kinds of choice models and sampling approaches.

The typical workflow goes as follows:

choice_model = ChoiceMNL(population, od, zones) # initialize the model and point to the data objects choice_model.configure(u, scope) # configure the model by specifying a utility function and the scope of application. choice_model.apply() # apply the model and update the population with the results. The module design is shown below:

We use the planner.choice.Choice class as a mediator between the population, data, and configuration.

The od object manages origin-destination data, for example travel time and travel distance between each origin and destination, for each travel mode. The zones dataset includes destination attraction data, for example the number of jobs or schools in each likely destination zone. Population is a PAM population (pam.core.Population) object We configure the model by specifying:

• the scope of the model. For example, work activities.
• the utility formulation of each alternative. Both settings are defined as strings. The strings may comprise mathematical operators, coefficients, planner data objects (od / zones), and/or PAM population objects (person/ act).

Coefficients can be passed either as a number, or as a list, with each element in the list corresponding to one of the modes in the od object.

An example application is presented in this notebook: examples/14_Advanced_Plan_Cropping.ipynb.

Introduces the PAM planner module.