Add Support for Days and Months

[ThomasThelen]

Background

In the Sept 17th call, we decided that we want to add support for representing time using the Mayan calendar system. The main goal of this is to tie events to particular dates.

Use Cases:

I want to be able to tell, based on a year and month what season it is and what events happen that month.

I want to be able to convert from the Mayan calendar system to the Gregorian system

Other Questions

Which calendar system do we want to support? It looks the the two predominant ones are the 260 day calendar and the 365 day calendar? It's of course possible to support both, but would take more time.

Other Notes

If we're adding support for the month and year-we're going to have to inevitably do it for days too (not a big problem).

Right now we're using the word 'year' as a proxy for the time step. What the year actually represents is dictated by the dynamics defined in the model (my opinion). It sounds like we want to iterate the timestep on the daily resolution, which is fine. I want to make sure we don't lose the ability to simulate on the daily or yearly level either.

To get around this, I'm thinking that we let the user decide the timescale by the way they specify dates. We also don't want to restrict the usage to just the mayan calendar, so we need to define what a mayan date looks like. For example, ISO_8601 clearly defines the format for a date in the Gregorian calendar.

Take the following Gregorian date, 1900-01-01, January first of 1900. Because the year, month, and day were specified-the model runs at the daily resolution. If someone enters the start date as 1900-01, the simulation would run on the monthly level. If someone enters 1900, then it's run on a yearly timescale.

Because the Mayan calendar system is mappable to the Gregorian calendar, I propose we use the Gregorian calendar, within the villager library.

Because dates are important in the models, most of the mayan date time checking will be done outside of villager. For example, if a trade is to be done on each day that is Imix-that logic goes in the researcher's trade function.

Solution

Because the Mayan date time features belong outside of villager, I propose we make a new library (or use an existing, see below) for converting Mayan date times to ISO 8601.

Features

1. Convert from ISO-8601 to ______ (preferred Mayan calendar)
2. Given a Mayan calendar date, tell me what the season is
3. Given a Mayan calendar date, tell me what events are happening on that date (so we can decide whether to trade or not)
4. Given a Mayan date, give me the pictorial representation (Bonus points)

To Do

1. Figure out a clever name
2. Create a repository using the clever name
3. devtools::create("clever-name")
4. Create functions for doing features 1-3

Usage

An example of what this would look like if a trade was allowed to happen every 20th day (when events were held)

library(clever-name)

trade <- function(currentState) {

mayan_date <- as.tzolkin(currentState$year)

if (tzolkin.name(mayan_date)) == 'Ajaw') {
# Then do some trade
}


}

[ThomasThelen]

And just to note-this can probably be done with a few functions (should't take a huge amount of time and there's already a library that does this in R; https://github.com/edgararuiz/maya

We can definitely use that library and contribute to it to include things that we need-but we'd at the mercy of the maintainer's opinion and time schedule.

There are a number of reasons to do it in-house:

1. We don't depend on someone else's schedule/opinion as to what we can do (for example, if we want to tie an event to a particular day/event, and we're using the library exists-what do we do if the maintainer doesn't like that idea?)
2. Adds to our 'suite' of computational mayan software

There are also a number of reasons to use the existing library:

1. The person who made it works for RStudio
2. He also co-authored the dbplyr library
3. He also wrote a library for the Gregorian calendar, which we'd probably want to use
4. It has an MIT license, so we can always fork it and do what we want with it (keeping the MIT license)

We also don't know until we ask! So I think it's worth jotting down exactly what we want to do with Mayan date times and then taking the considerations above and making a decision