Using Python scripts with MassMotion – Creating a timetable schedule from an OD matrix

Introduction

MassMotion’s timetables are incredibly powerful, but can be time-consuming to pull together by hand. On the other hand, simple programs can do much of the donkey work, converting files such as Origin/Destination Matrices (OD Matrices) or train schedules into a form that MassMotion can read. In this article I will be looking at converting an OD Matrix into a timetable schedule file using a programming language called Python.

Python

Python is a free scripting language that is simple to use, powerful, and importantly for us great for working with comma separated value (.csv) files, which are a typical output from Excel.

Python comes in two slightly different versions: Python2x and Python3x. The x refers to the particular build: I am currently using Python3.4.3. You may find a certain amount of controversy online regarding which it is best to use, as Python3x cannot read libraries written in 2x. This is mostly academic now, as over the last few years the majority of libraries have now been updated. My recommendation is that you should use Python3x, and only use Python2x if you have a definite need to work with legacy systems.

You can download the main version of Python from www.python.org, including the IDLE shell, which is a programming environment aimed to help you write and run the programs. There are other Python shells out there out there that might offer some advantages to you, and there will be lots of online discussions extoling the various merits of each. You can even write your scripts in Notepad or Notepad++ and run them with a Windows command line if you wish.

Coding with Python

There is lots of guidance available on how to write Python programs, including much which is free on the web (https://docs.python.org/3/tutorial/ is a good place to start). Here I will go through a few key points, but I do recommend that you do one of the many excellent courses or books that are out there.

If you are used to programming in other languages, you may note that a main difference between it and other languages is that loops and other relationships are shown by indenting. For example, a FOR/NEXT loop does not include a NEXT, but instead looks something like this:

for row in input_file:
    input_rows.append(row)

Comments always start with a #, so Python will ignore anything you write after one.

Rather than creating Arrays, Python uses Lists, and allows an item in a List to also be a List. In the script below I create a List, where each item is a line from the OD matrix csv. As items in a List are separated by commas, each line becomes its own list, allowing me to pluck individual values out. For example, to retrieve the value from the second column in the third row of the csv I might ask for (as Python always has the first item as zero):

row[2][1]

While Python has many commands that you can use, there are modules and libraries available to make your life easier. In our case, we will import the csv module, which enables us to read and write such files without having to do so much coding. We do this with:

import csv

Commands using this module start with “csv.”, such as csv.reader and csv.writer.

Note that for a general program you might want to add in browse dialogs to grab the files and locations, but for something like this I suggest that you just edit the names directly into the script and save the script into the same folder as the files you want to work on.

The Data

For this exercise I have created a very simple OD matrix, but the program will work with one of any size:

And the end result will look like this:

I have only shown the first few lines, just enough to show how it works. The end result has one line per non-zero value in the OD matrix plus the headers. Some items are optional, so for example you might leave the Action column blank if you are not applying any to the agents when they spawn.

As these are csv files the OD matrix (OD_matrix.csv) actually looks like this:

OD Matrix,ExitPortal1,ExitPortal2,ExitPortal3,ExitPortal4,ExitPortal5,ExitPortal6,ExitPortal7
EntryPortal1,0,80,51,0,19,81,7
EntryPortal2,51,10,70,40,110,0,12
EntryPortal3,99,26,20,47,58,39,3
EntryPortal4,39,16,119,0,5,4,75
EntryPortal5,11,44,0,35,10,108,0
EntryPortal6,0,1,115,77,0,21,47

And the results look similar.

The program

As you will see, the resultant Python script (OD-schedule.py) is not long and hopefully easy to follow.

# OD matrix to MassMotion Timetable
# read OD matrix csv and write Schedule csv

import csv     # enable the use of csv commands

# set up standard values - adjust to suit:
offset = '00:00:00'   # from start of simulation for start of arrivals (optional)
curve = 'Arrival_curve' # defined in Timetable_curve.csv (optional)
avatar = 'Orange_LowPoly'   # default agent avatar (optional)
profile = 'DefaultProfile'   # agent profile (optional)
action = 'Action1'   # initial action applied to agents (optional)
tokens = 'Token1'   # tokens given to agents (optional)

# open input & output files, then create reader/writer objects for them
with open('OD_matrix.csv') as csv_od_matrix:
    input_file= csv.reader(csv_od_matrix)
    with open('Timetable_Schedule.csv', 'w', newline = '') as csv_schedule:
        output_file = csv.writer(csv_schedule)

                  # create empty list and copy OD matrix into it
        input_rows = []
        for row in input_file:
            input_rows.append(row)

        # write the headers in the first row of the schedule:
        output_file.writerow(['From', 'To', 'Population', 'Time offset', 'Curve',
                              'Avatar', 'Profile', 'Init Action', 'Give Tokens...'
                              ])

        # write each cell in OD matrix into schedule if not zero
        exit_portals = input_rows[0]
        for row in input_rows[1:]:
            entrance_portal = row[0]
            for column_index in range(1, len(row)):
                pedestrians = int(row[column_index])
                if pedestrians > 0:
                    output_file.writerow([entrance_portal,
                                          exit_portals[column_index],
                                          pedestrians, offset, curve, avatar,
                                          profile, action, tokens
                                          ])
print('Timetable written')

Conclusion

I hope that you find this script useful, but I am sure that there are improvements you can make to it. For example, it currently sets all the avatar colours to be Orange, but how would you change it to make the colours be based on either the origin or destination. You might also write scripts to create other timetable files; in the next article I will show you how to convert a train or plane schedule.

To create the script and data files, just copy the relevant text above and save with the given names.

I would love to hear how you get on. You can head on over to LinkedIn and make a contribution there: