How It Works

2016-05-24

• Impress your friends!   More like bore your friends.
• Astonish your parents!   More like annoy your parents.
• Thrill your significant other!   More like create some doubts in the mind of your significant other.

Concepts

The saga software makes predictions based on all your previous trips. There will be no predictions until you have done the trip at least once.

Before you can start the first trip, you first need to define places, a route, and optionally some regions. You will also need a configuration file which tells about what route you are doing now.

Imagine the world as a 3D construction of fixed objects. Your route is then a certain fixed path through this 3D world. The world itself, and your route, are rigid and fixed in space.

Now your trip through the world is elastic like a rubber band. Some parts can be done quickly, some parts can be done slowly. Your motion along the route is flexible and subject to change, and that is where it’s fun to have predictions.

Places

This is an example places file.
It is simply a YAML file with this structure.
For each place there is a slug, a title, and a description.

Within the software, you first set up a series of places. The places should be identifiable fixed objects along your route that can be observed while traveling.

Examples of places:

• Home
• A crossroads
• A memorable business
• A funny roadside sculpture
• A highway sign
• A mile marker
• A train station
• A bridge
• A tunnel
• A rest area

The more fun your places are, the more fun it will be to tag them as you pass by.

Before you can start recording data, you need to establish your set of places. The easiest way to do this is to take the trip once and collect a list of places on paper or with the computer. You won’t get any predictions on this first trip, but you will establish a good set of places that you need.

Routes

This is an example route file.
It is simply a list of places in the correct order.
Use the slug of the place.

A route is a list of places in a certain order. The order should be the same order that you will encounter each place, normally, on your trip.

Let’s say you are traveling from home to office. The first place on the route will be home. The last place on the route will be the office. Inbetween these two will be evenly spaced notable places in the order you will pass them.

If you want to also track your trips from the office back to home, then you will need a second route that starts at office, ends at home, and passes all the places in the reverse order.

Regions

This is an example regions file.
Each region can have a slug and a title.
The endpoints of each region are places that must be defined in the places file.

Regions are optional. A region starts at one place, and ends at another place. When you are between those two places, you are therefore in the region.

Regions can be used to record that you move from one state to another state. Or one county to another county. Or from the mountains to the plains.

One thing I have found useful is radio reception. You can define radio reception as a region. When you move into that region, the software tells you a good radio station to tune in.

Regions can be used for fun also. You can make up fantasy meanings for the landscapes you see. A desert could be a circle of hell, for example.

Configuration File

The configuration file looks like this.
Easy peasy!

The configuration file is simple. You just need to tell the software the following four things:

campaign

Tell the software which route you are currently doing. This has to match a route you have set up in a previous step.

mikedate

A string representing the date the travel is taking place. This is used to create a unique data file for documenting the trip. I use the mike date but you can use something that works for you.

local_tz_offset

The distance, in hours, of your computer system clock to the timezone where you are traveling. This is needed because you want any time predictions to be based on local time, not your computer time.

local_tz_str

This is a short moniker for the local time zone. This should match local_tz_offset. It is for confirming to you, via the GUI, of the local time zone of the trip.

Training The Program

This is an example data file produced during a trip.
The last column is the place where the event occured.
The first column is for arriving at a place.
The second column is for departing a place.
The third column is the odometer reading at that place.

You’ve established a bunch of places. You’ve put a series of places in a specific order to create a route. Maybe you made some regions. You set up your configuration file.

Now start off on a new trip. Use the program to depart (d) the first location. Use the program to pass (p) as many places as possible. Use the program to arrive (a) at your destination.

If you are going to stop at a known place during your trip, you want to first arrive (a) at that place when you get there, and then depart (d) that place when you leave. Some landmarks you just pass by. Other landmarks, like rest areas, you sometimes stop for a while.

What this does is creates a new data file for that route on that date. That data can then be used for predictions the next time you do that same trip!

Getting Predictions

After you have set up the route, and trained the program at least once, you can now start getting predictions.

To do so, you just update the configuration file to set a new date, then start off on your new trip. Depart (d) from your starting point. You will immediately get predictions. Pass (p) a few more landmarks on your trip to refine the predictions for the remainder of the trip. Don’t forget to arrive (a) at your destination.

Each subsequent trip that you do over the same route continues to train the program and will be used in later predictions.

The software can’t make predictions for a landmark that you have configured, but that you have not passed at least once.