-
-
Notifications
You must be signed in to change notification settings - Fork 0
Data Mapping
Data mappings tell Orpheus how to use your scouting and pit scouting data. This is a JSON file that you will need to create each year for your new data.
If you are unfamiliar with JSON, I suggest reading the first few sections of this article (Up until the start of "Using JSON files in JavaScript").
Here is an example of an empty mapping:
{
"team": {
"key": "",
"format": ""
},
"match": {
"number_key": "",
"scouter_name_key": "",
"notes": ""
},
"mapping_version": 1,
"constants": {
},
"data": {
},
"pit_scouting": {
"team": {
"key": "",
"format": ""
},
"image": [],
"page": {
},
"data": {
}
},
"ignore": [""]
}Key - The name, or field in your data. For example, if your pit scouting data has a question titled "Drivetrain", the key in your output csv or json file would likely also be "Drivetrain"
"team": {
"key": "",
"format": ""
}Put the key in which the team is stored inside the "key".
There are a few options for format. These are case sensitive.
| Value | What does it do? |
|---|---|
| frc# | The team number preceded by frc, for example frc4915
|
| name | The team name, for example 'Spartronics'. This is not recommended but is an option if you want to use it for some reason. It will not work if TheBlueAlliance API is disabled. |
| Number or # | The team's number, for example, 4915. If the format key/value pair is omitted from the mapping, this will be the default. |
There are three fields in this section, but only one is required.
"match": {
"number_key": "",
"scouter_name_key": "",
"notes": ""
}The only required field is "number_key", which tells Orpheus the key for the match number in the scouting data. Then, "scouter_name_key" is the name for whoever has scouted that match. If included, this will let you see in the team comments who has scouted each match so you can talk to them more. "notes" is also optional, for the key of the note or comments for that match.
Set key mapping_version to 1.
Orpheus has a math evaluator for data and constants.
This can be used to derive more helpful information from your team's scouting data, like maybe Notes scored which adds together Amp notes and Speaker notes scored.
The math evaluator can be simple or complicated, depending on your needs.
Orpheus supports the following operations:
| Symbol | Operation | Example |
|---|---|---|
| + | Addition | 1+1 = 2 |
| - | Subtraction | 7-2 = 5 |
| * | Multiplication | 7*2 = 14 |
| / | Division | 12/2 = 6 |
| % | Modulo | 13 % 6 = 7 |
| ^ | Power | 3^3 = 27 |
Orpheus includes all the "Static methods" included in Javascript's Math object found here.
Examples of how to use these in Orpheus:
cos(2) = -0.4161468365471424
abs(-17) = 17
sin(6)+cos(7) = 0.47448675614437874
Other generic math functions included in Orpheus are:
logbase - Takes two parameters, base, then number.
factorial - Takes one parameter, a number.
Orpheus also includes logic functions
| Function | Parameters | What does it do? |
|---|---|---|
| equal | a, b | Checks if a=b. Returns true or false |
| equals | a, b | Same as equal Checks if a=b. Returns true or false |
| greater | a, b | Returns if a is greater than b |
| greater= | a, b | Returns if a is greater than or equal to b |
| less | a, b | Returns if a is less than b |
| less= | a, b | Returns if a is less than or equal to b |
| or | a, b | Returns true if a and/or b is true |
| xor | a, b | Returns true if a is true or b is true, but false if both are true. |
| and | a, b | Returns true if a and b are both true |
| not | a | Returns true if a is false, and vice-versa |
| if | condition, trueValue, optional falseValue | If the condition is true, then it will return the trueValue. If false, it will return the falseValue, which is 0 if left blank. |
| You might use these in a few cases. For example, checking if a Drivetrain is a Swerve drive, or seeing if a robot climbed or not. |
Orpheus also supports strings as parameters in math functions.
You could do something like:
equal([Drivetrain], 'Swerve')
Wrap strings in 'single quotes' or "double quotes". Please note that, because of the JSON format, if you use double quotes, you need to put a \ beforehand, like \"this\". If your string includes a quote, put \\ beforehand so that Orpheus knows to include that in your string.
For later math calculations, you can set custom constants in your mapping. These can be referenced to later on with their name.
For example, you could be doing math to calculate how many points a robot scored in a match, like this: ... previous point calculations ... + if([Robot Left], leave, 0)
Orpheus has point values saved for the 2024 and 2025 games and will be updated in the future for future games.
{
"2024": {
"leave": 2,
"autoamp": 2,
"autospeaker": 5,
"amp": 1,
"speaker": 2,
"ampspeaker": 5,
"park": 1,
"onstage": 3,
"spotlit": 4,
"harmony": 2,
"trap": 5,
"foul": 2,
"tech": 5
},
"2025": {
"leave": 3,
"autol1": 3,
"autol2": 4,
"autol3": 6,
"autol4": 7,
"autoprocessor": 6,
"autonet": 4,
"l1": 2,
"l2": 3,
"l3": 4,
"l4": 5,
"processor": 6,
"net": 4,
"park": 2,
"shallow": 6,
"deep": 12,
"foul": 2,
"tech": 6
},
"any year": {
"pi": "Approximately 3.14159",
"e": "Approximately 2.718",
"true": 1,
"false": 0,
}
}In your mapping, create a "constants" field, as shown below.
"constants": {
"constant": "calculations"
},Constant names cannot have spaces in them, but you may use underscores for the same effect. If you name your constant the same thing as one of the default constants, the default constant will be overridden.
This is where Orpheus starts to get interesting! In the data field, you can put your column information. There is a lot of options here. First, create your data field. This will be similar to the constants field, where the name is the key, but the value will be another JSON.
Here is an example of a column with all options shown:
"Example Name": {
"value": "",
"variable": false,
"graph": false,
"hidden": false,
"format": "",
"display": "",
"size": 0,
"skip": []
},There's a lot of options, so I'll now go over each of them.
You can also get the match number with [match]
Variables will be calculated first so that their output values can be used in other equations. You refer to them in [brackets] like match fields.
If true, this will tell Orpheus to make this column also a graph.
If true, this will hide the column from view in the tables. It cannot be re-enabled inside Orpheus without changing the mapping. To the user, it will seem like this column doesn't exist. This is useful for data that you want graphed but not shown in the table or for variables that are helpful for calculations later but that you do not want shown.
There are a few options for what format to use for your data.
| Format | Explanation |
|---|---|
| mean | Mean |
| geomean | Geometric mean |
| median | Median |
| sum | Adds all the data together, returning the sum. Note that you may have more data for different teams so this probably isn't a good idea. |
| ratio | See below |
The ratio format is used to show the ratio between data. It adds another required field to your column, "denominator". This will add up all the values as a sum and all the values in "denominator" and then do (sum of values/sum of denominator). Denominator is a calculated field just like "value", which is the numerator in this case.
You can also use [value] to get the final output value for that column
This is the default size of the column. 0 is the smallest while 3 is the largest. 1 is the default if this is left blank.
This is an array of conditions that, if any of them return true, that match would be skipped. You might use this if you have two separate fields, maybe "Did this robot climb?" and "Was the climb deep or shallow?" to see (given that the robot climbed) how often it was deep and how often it was shallow.
This is an array where if any of the conditions are true, a team will be automatically ignored when the mapping is added to Orpheus. All columns, including pit scouting columns, regardless of if they are a variable or not, are accessible via the [bracket] syntax.