The Regnus Scripting Tutorial
Part 3: Ratios & Weights
Now you've got the hang of the basic idea of references, let's take a look at how to better control the probability of certain entries being selected by a reference...
Ratios
When you set up a list of entries under a particular group in Regnus using the methods you have learned so far, you will no doubt have noticed that each entry is given an equal probability of being selected. This is, of course, correct for many applications.
However, there are also many times when you may want a particular entry to be more or less likely to be selected than others in the same group. A crude way to achieve this, which you may already have thought of, is to simply repeat entries to increase their probability, like so:
START <Weighting Example>##Probabilities;
GROUP Probabilities
ENTRY 25%
ENTRY 75%
ENTRY 75%
ENTRY 75%
Here, there is a 75% chance of generating the text "75%", and only a 25% chance of "25%". This works, of course, but is not a very good way of defining probability, especially if you have a lot of entries, as it can quickly become confusing to look at, makes your scripts unnecessarily large, and is increasingly difficult to edit if you need to change particular probabilities.
A far more sensible way to alter the probability (or "weight") of a particular entry being selected is to use the "RATIO" qualifier. This qualifier is used in exactly the same way as an "ENTRY" qualifier, but also allows you to define a probability for the text contained. The syntax for using the "RATIO" qualifier is as follows:
START <Weighting Example>##Probabilities;
GROUP Probabilities
RATIO 25:One quarter!
RATIO 75:Three quarters!
Here, we have used two ratio qualifiers to define percentage probabilities for the two entries. Actually, using percentages as in the above example is unnecessary; this example would work just as well written as:
START <Weighting Example>##Probabilities;
GROUP Probabilities
RATIO 1:One quarter!
RATIO 3:Three quarters!
This is because the maximum probability is always calculated as the combined total of all probabilities defined, in this case, 4. Thus, the first entry has a probability of being selected of one in four, just as in the previous example, the probability was twenty-five in one-hundred.
You can also mix and match "RATIO" qualifiers with "ENTRY" qualifiers. Standard entries are always given a probability of 1. So, the following example will have the exact same results as the previous one:
START <Weighting Example>##Probabilities;
GROUP Probabilities
ENTRY One quarter!
RATIO 3:Three quarters!
Ratios can also be fractional values, which is useful if you want a single entry in a group to be less commonly selected than the other entries in that group. For example:
START <Weighting Example>##Probabilities;
GROUP Probabilities
ENTRY Four fifths!
RATIO 0.25:One fifth!
The standard entry has a weight of 1, or four times the weight of the fractionally-weighted entry, so here, the under-weighted entry has a selection probability of one fifth.
Note: Fractional ratios are accurate to a precision of one thousandth (0.001) in the current standard. Values lower than this will not function correctly.
Having a quick play with using ratios should soon give you a firm idea of how they work, but although simple, they can be very useful, especially when writing scripts which need to use specific probabilities (for example in research projects or encounter charts and such for roleplaying games), so it's well worth being aware of how to use them!
Counted Weights
Another way to weight entries is to use the "COUNT" qualifier. This allows you to assign a weight to an entry equal to the number of entries in another group. For example:
START <Weighting Example>##Probabilities;
GROUP Probabilities
ENTRY One quarter!
COUNT AnotherGroup:Three quarters!
GROUP AnotherGroup
ENTRY Something
ENTRY Something else
ENTRY Yet another thing
In this example, the second entry in the "Three quarters!" entry is assigned a weight of three as there are three entries in the referenced group "AnotherGroup".
This is primarily useful when the intention is to combine the contents of two groups for one purpose, while keeping them separate for other purposes, but wanting to ensure that each individual entry is treated with the same weight. For example, consider the following situation:
START <Weighting Example>##Animal;
GROUP Animal
ENTRY ##Cat;
ENTRY ##Dog;
GROUP Cat
ENTRY Lion
ENTRY Tiger
ENTRY Puma
ENTRY Cheetah
ENTRY Felis Silvestris Lybica
GROUP Dog
ENTRY Wolf
ENTRY Rottweiler
In this example, a Reference to the group "Animal" will return an entry from the group "Cat" fifty percent of the time, and an entry from the group "Dog" fifty percent of the time; but as there are five entries in the "Cat" group and only two in the "Dog" group, this means that such a Reference would only return the result "Puma" ten percent of the time, whereas "Rottweiler" would be returned twenty-five percent of the time.
Clearly, this is not the intention, and it can of course be fixed using a "RATIO" qualifier in the following way:
START <Weighting Example>##Animal;
GROUP Animal
RATIO 5:##Cat;
RATIO 2:##Dog;
GROUP Cat
ENTRY Lion
ENTRY Tiger
ENTRY Puma
ENTRY Cheetah
ENTRY Felis Silvestris Lybica
GROUP Dog
ENTRY Wolf
ENTRY Rottweiler
Now, there is an equal one-in-seven chance of any particular animal being returned. However, the problem with using "RATIO" qualifiers here is that the ratios would need to be updated each time a new entry is added to either group. The "COUNT" qualifier makes this much easier:
START <Weighting Example>##Animal;
GROUP Animal
COUNT Cat:##Cat;
COUNT Dog:##Dog;
GROUP Cat
ENTRY Lion
ENTRY Tiger
ENTRY Puma
ENTRY Cheetah
ENTRY Felis Silvestris Lybica
GROUP Dog
ENTRY Wolf
ENTRY Rottweiler
The "COUNT" qualifier takes into account all calculated weights for a named group, including any "COUNT" or "RATIO" qualifiers within that group, so the following would also provide an equal chance of any particular animal being returned:
START <Weighting Example>##Animal;
GROUP Animal
COUNT Cat:##Cat;
COUNT Dog:##Dog;
GROUP Cat
COUNT BigCat:##BigCat;
COUNT SmallCat:##SmallCat;
ENTRY Leopard
ENTRY Puma
GROUP BigCat
ENTRY Lion
ENTRY Tiger
ENTRY Cheetah
GROUP SmallCat
ENTRY Felis Silvestris Lybica
GROUP Dog
ENTRY Wolf
ENTRY Rottweiler
RATIO 1:Great Dane
Note: A "COUNT" qualifier should not be used to count the group in which it appears, as this will create an infinite logic loop and cause your Regnus parser to hang! The same is also true of "COUNT" qualifiers which attempt to count groups which themselves attempt to count the original group, for the same reasons, so be careful!
Finally, it is worth noting that both ratios and counted entries are also able to include labels, just as with "START" and "ENTRY" qualifiers:
START <Random Selection!>##StartPoints;
GROUP StartPoints
ENTRY <Example One>Today is sunny, so I will ##Action;!
RATIO 2:<Example Two>I would like to ##Action; today!
COUNT Action:<Example Three>I don't like to ##Action;!
GROUP Action
ENTRY go out and play
ENTRY stay indoors
ENTRY play with my friends
ENTRY play by myself
ENTRY go to sleep