Documentation

The imagine economics conceptual modules (see the Modules page) provide a notebook-like interface for learners to explore economics concepts. This interface is composed of a series of blocks followed by simulation and visualization, where each block contains a combination of commands (code) and text.

This documentation explains what code is allowed and the structure it should take. Note that this documentation is an incomplete work-in-progress.

Introduction

The imagine economics conceptual modules work by adding buyers and sellers to a market, simulating a number of rounds, potentially adding additional buyers and/or sellers (or modifying the existing buyers and/or sellers), and then simulating more rounds. This process can continue to be repeated with some limitations on buyers, sellers, and rounds as described below.

Note that, sometimes, all of the commands within a section of a conceptual module act on a single market. For example, about halfway down the introductory page for the dynamic model, buyers and sellers are added to a market and a set of simulation rounds are run. Further down the page, the buyers in this same market are modified and additional rounds are run.

At other times, more than one market may be represented within a single section of a conceptual module. For example, on the assumptions page for the dynamic model, there is a subsection for testing the buyer visibility assumption and another section for testing the seller visibility assumption. Each of these subsections has its own commands that operate on different markets.

Overall, the general process in the conceptual modules is to add, simulate, add/modify, simulate, and so on. It should (hopefully) be clear from the context whether each command block is operating on the same market as the previous commands or whether it is beginning a new market. In the documentation on this page, we use the term "the market" for generality when referring to the market on which commands are acting.

Using Comments

Comments allow explanatory text to be mixed in with code. The only requirement for using comments is that any line that contains a comment must have the hashtag character (#) as the first character on the line (though the hashtag can be preceded by spaces for indentation).

For example, a command with no comments might look like this:

The same command with comments—which will have the same result in terms of the simulation—might look like this:

Comments can appear anywhere before or after a command, or as shown above, within a command. Code blocks can also contain only comments and no code.

The "Add" Command

The "add" command adds buyers or sellers to the market.

The command for adding buyers is:

where [b] is a (non-fractional) number of buyers and [specification] can take one of the following forms:

• of [X]
• between [X] and [Y]

where [X] and [Y] are whole numbers.

The command for adding sellers is similar:

where [s] is a (non-fractional) number of sellers and [specification] can take one of the following forms:

• of [X]
• between [X] and [Y]

where [X] and [Y] are whole numbers.

Note that there can be multiple "add" commands in a row, where each command creates buyers or sellers with different parameters. For instance, we could write something like the following to create two sets of sellers:

The number of these commands is not limited, though simulations are currently limited to 20 total buyers and 20 total sellers (i.e., across all "add buyer" commands, summing all of the individual values [b] cannot total to more than 20, and across all "add seller" commands, summing all of the individual values [s] cannot total to more than 20).

The "Modify" Command

The "modify" command modifies buyers or sellers that are already in the market.

The command for modifying buyers is:

where each instance of [specification] can take one of the following forms:

• of [X]
• between [X] and [Y]

where [X] and [Y] are whole numbers.

The second, third, and fourth lines will select a subset of buyers currently in the market based on their reservation price, demand, and/or visibility. The sixth, seventh, and eighth lines will then modify those buyers to have the specified reservation price(s), demand(s), and/or visibility(ies).

Note that the command requires at least one of lines two, three, and four to be present (i.e., one or more of reservation price, demand, and/or visibility should be used to select buyers) but not necessarily all of them. Similarly, at least one of lines six, seven, and eight should be present (i.e., one or more of reservation price, demand, and/or visibility should be modified for the selected buyers) but not necessarily all of them. As an example, we could have a command like the following:

which would select only those buyers with reservation price between $5 and $10 (inclusive) and change them to have visibility of 20%.

The command for modifying sellers is similar to the command for modifying buyers but with a couple of changes:

where each instance of [specification] can again take one of the following forms:

• of [X]
• between [X] and [Y]

where [X] and [Y] are whole numbers.

Similar to above, the second, third, and fourth lines will select a subset of sellers currently in the market based on their marginal cost, inventory, and/or visibility. The sixth, seventh, and eighth lines will then modify those sellers to have the specified marginal cost(s), inventory(ies), and/or visibility(ies).

The "Simulate" Command

The "simulate" command simulates a given number of rounds in the market. The buyers and sellers in the market include any that have been added by commands above the point where the "simulate" command appears. The command takes this form:

where [r] is a whole number.

The number of these commands is not limited, though simulations are currently limited to 50 rounds at a time (i.e., the number [r] cannot be more than 50).

Back to homepage