Coding windows and statistical windows in SportsCode can be substantially enhanced using scripting, from automating certain event tracking to displaying real-time statistics to creating movie highlights of players or types of plays. However, unlike most analytical software packages, SportsCode uses their own coding syntax, creating the need to learn and understand their software-specific way of writing any command. Some of these are similar to functions in Excel or Numbers, although their slight alterations make it crucial to ensure they are correctly written in order to work. This guide walks through some of the key commands that can make your coding experience in SportsCode a lot smoother.
Where To Use Scripting?
Scripting in SportsCode is done through either a Code window or a Statistical window. You can use an existing code window that you already have or create a new on in File then New then Code window.
SportsCode Code Window
The actual script is written inside a code button. You can either add a new code button or use an existing one. If what you want to do is show an output in that button, then you need to open the “Inspector” popup window for your button, select the “Appearance” tab and tick the “Show output” option. This will set the code button as a button with the function of displaying information. To start writing a script go to the “Script Editor” tab within the Inspector window.
While not necessary, SportsCode recommends adding an “Execute” button in your Code window’s tool bar by right-clicking on the toolbar and selecting “Customize Toolbar…”. This “Execute” button is used to run the code after it is written, although the Play button of the Code window will have the same effect of running the code.
Commands To Select Elements & Events
Prior to starting writing commands, one of the first things to understand from scripting in SportsCode is how to select different elements from your code window and timeline to be used in your scripts. For example, if you want to display the number of shots by the home team together with the number of shots by the away team, you will want to translate that task into the appropriate script syntax that represents the calculation of “shots home team” + “shots away team” from your timeline. To do so, you will need to have the script select the appropriate elements from SportsCode that contain the shot numbers for either team, so that you can then add them together.
Below is a list of how to select an element from your code window or timeline to be used in your script commands.
Selecting Elements From Code Window
SportsCode Script Example:
Display the number of shots for the player appearing in the Button “PlayerName” by retrieving the button name with the name of the player and counting the events in the timeline with that name.
$
Creates a new variable to be used at a later stage in the script.
Examples:
$HomeGoals = count instances where row = “Home Goals”
$AwayGoals = count instances where row = “Away Goals”
$TotalGoals = $HomeGoals + $AwayGoals
$BUTTON_ID
Returns the button ID of the code button where the script is written.
Similar Command:
$THIS_BUTTON (returns the button name of the code button where the script is written)
Examples:
Show “This Code Button’s ID is “ + $BUTTON_ID
BUTTON NAME button_id
Retrieve a code button name using the button id of the button name you want to obtain.
Examples:
BUTTON NAME “Shots On Target”
BUTTON NAME “Home Goals”
BUTTON NAME “Away Goals”
CODE button_name
Selects the output from another button using the button’s name as reference (i.e. if button with the name Goals has a script that outputs 5, it will grab that number 5)
Examples:
CODE "Goals"
CODE “Total Shots”
CODE “Home Possession"
CODE ID
Selects the ID of a different button using that button’s name.
Examples:
CODE ID "Goals FC Barcelona"
(if the button name “Goals FC Barcelona” has an ID called “Home Goals” it will return “Home Goals”)CODE ID “Messi”
(if the button with the name “Messi” has an ID called “Player” it will return the text “Player”)
BUTTON button_name STATE
Specifies whether a button in the code window is activated or not.
Examples:
SHOW BUTTON "FC Barcelona Possession" STATE
(displays whether the possession button for Barcelona is activated or not)
Selecting Events From Timeline
SportsCode Script Example:
Display the total shots that took place in a match for both teams by first, counting the number of shot events in the timeline for each team inside a new variable and then adding the two team variables together by creating a third variable (i.e. $TotalShots) with the total.
ROW
Selects specific row within the timeline (i.e. Home Team Shots).
Similar Command:
ROW_NAME(#) (Specifies the name of the row from the value you select, i.e. 1 = first row, 2 = second row)
Examples:
ROW = “Shots On Target”
ROW > 1
ROW < 10
ROW_NAME (1)
(selects the name of the first row in the timeline)
INSTANCES
Selects specific events tracked within one or multiple rows in the timelines.
Similar Commands:
INSTANCES2 (only instances between red markers in timeline)
INSTANCE[X] (only the ‘x’th instance specified inside the brackets).
Examples:
INSTANCES WHERE ROW = “Shots On Target”
INSTANCES2 WHERE ROW = “Home Goals”
INSTANCES[2] WHERE ROW = “Away Goals”
(selects the second goal by the Away team)
LABEL label_name
Select events with a specific a label in the timeline.
Similar Commands:
LABELS (returns all labels)
LABEL IN (specific instances)
LABELS IN (all labels in specified instances)
”GROUP”.”LABEL” (selects events matching the group and label specified)
”GROUP”:”LABEL” (selects event occurrences matching the group and label specified)
Examples:
SHOW COUNT LABEL “On Target”
SHOW COUNT “On Target”
SHOW COUNT “On Target” WHERE ROW = “Home Team Shots”
SHOW COUNT “ShotType”.“On Target” WHERE ROW = “Home Team Shots”
FROM
If you are using multiple timelines, FROM allows you to specify which timeline to select events from.
Examples:
Show count instances from “Barcelona v Real Madrid” where row= “Barcelona Goals”
(displays a total number of goals scored by Barcelona in the match against Real Madrid)Show count “Messi” from “Barcelona v Real Madrid”, “Barcelona v Atletico” where row= “Barcelona Goals”
(displays the total number of goals scored by Messi in the Barcelona matches against Real Madrid and Atletico.
GROUP
Selects all events with a specific group of labels.
Example:
Show count instances where group = "Shot"
(displays the number of instances with labels in the group shot, i.e. with labels such as “On Target”, “Missed” or “Scored”)
LIMIT
Selects a specific instance or group of instances based on their position in the timeline.
Example:
Instances limit 2 where row= “Goals”
(selects first 2 goal events from the timeline)Instances limit 4,2 where row= “Fouls”
(skips the first 4 fouls and selects the next 2)Instances limit 4,-1 where row= “Free Kick”
(skips the first 4 free kicks and selects all the remaining ones)Instances limit -3,-2 where row= “Saves”
(selects the second and third last saves)
OVERLAP
Selects events in the timeline that occur at the same time.
Similar Commands:
OVERLAP_LENGTH (total length of time in second that two events or labels occur at the same time)
UNIQUE (opposite command to OVERLAP, returning events that occur at completely different times to other events)
Examples:
$MessiAssists = OVERLAP ( "Messi", "Assist" )
(display the events with the label Messi and label Assist taking place at the same time)Show start OVERLAP ("Scored" where row="Shot" ,"Messi" where row="Assist")
(display start time of event when both the shot got scored and Messi assisted overlap)$NotMessi = UNIQUE (“Shot”, “Messi”)
(display the number of shots where Messi was not involved)
START
Select the earliest start time of the labels or instances in the timeline in seconds.
Similar Commands:
START TIME (select events with a specific start time)
END (select the latest end time of the labels or instances in the timeline in seconds)
END TIME (select events with a specific end time)
Examples:
START "Goal"
(display start time of first goal)START "Messi" and "First Half" where row="Goal"
(display the start time of Messi’s first goal in the first half)Count instances where start time < 60
(display the number of instances that occurred in the first 59 seconds)END "Ball In Play"
(display the latest time that the ball was in play)
RANGE
Select events based on when they occur in the timeline.
Similar Command:
HH:MM:SS (select events based on when they occur using hours:minutes:second format)
Example:
Count instances where range > 60
(display the number of events that happen after 60 seconds of play)Count instances where range >= 60
(display the number of events that happen from 60 seconds of play onwards)Count instances where range != 60
(display the number of events that happen before or after, but not at 60 seconds of play)Show count instances where start time > 00:05:01.45
(display the number of events that take place after 5 minutes and 1 second)
SportsCode Script Example:
Display the number of shots in the match that were on target by counting the number of events “Shot” but only those with the label “On Target” in them. Then display the result with a text in front with the message “Total Shots On Target” (i.e. Total Shots On Target 12”).
Commands To Set Conditions
These commands are used to create the logic of your selection. For example, if you want to select all shots in the first half, you may use the AND statement to make sure the scripts only considers the events of “shots” when the events “first half” is also true (i.e. shots AND first half). These commands can also be used for filtering specific events by name, using the WHERE statement (i.e. apply only WHERE an event name is “Shots”).
AND
Add additional true statements to your element selection logic. Used inside other commands.
Example:
SHOW COUNT BUTTON NAME “Shots” AND BUTTON NAME “First Half”
SHOW COUNT $Away_Goals AND $Home_Goals
SHOW COUNT $PlayerOne AND $PlayerTwo
IF (condition, true, false)
Similarly to Excel, it conditions a the script or section of the script to whether the condition in the IF statement is true or false (i.e. IF Home Goals are higher than Away Goals then write “Home Win”, otherwise write “Draw/Loss”).
Examples:
IF ($AwayGoals < $HomeGoals, show “Home Win”, show “Draw/Loss”)
WHERE
Filtering by adding specific conditions (WHERE ROW = X)
Examples:
WHERE ROW = “Shots On Target”
WHERE ROW > 1
WHERE ROW < 10
NOT
Exclude an event or label from your selection.
Examples:
$Goals= NOT “Messi” show count $Goals
(display all goals scored by all players BUT Messi)$Cards = NOT “Red” show count $Cards
(display all cards that are not red, therefore all yellow cards)
OR
Selects events or labels if either one of two conditions is met.
Examples:
$Goals= “Messi” OR “Suarez” show count $Goals
(display all goals scored by either Messi or Suarez)$Pass= NOT “Iniesta” OR “Xavi” show count $Pass
(display all passes by players that are not Iniesta nor Xavi)
Commands To Display Outputs
Counts, percentages, ratios or even time metrics can be displayed in real-time in a code button within the code window. You can also display any text (known as string) by writing it with quotation marks (i.e. “Goals Scored”).
Similarly to Excel or a normal calculator, you can perform calculations inside your Script Editor of the code button and display the results. To do so, you simply add the operation after the word ‘show’ and the code button will display the result.
Scripting also allows you to display both text and numbers in one single code button. To do this, you will use a plus symbol (+) to join the text and the calculation results. This plus symbol allows you to join any text together with a number or other pieces of text. Any calculations will need to be written using parenthesis.
SHOW “text”
Display text or/and numbers in a code button.
Similar Commands:
SHOW calculation (add, subtract, divide or multiply any number and display the result in the code button , i.e. 2+2)
SHOW “text” + numbers (add a label before the number you want to display, i.e. shots = 5)
How it works:
Type the word show in your Script Editor panel.
Anything you type after “show” will be displayed in the code button.
Examples:
Show “Home Team”
Show “Shots On Target”
Show 2 + 2
(the code button will display the number 4)Show (5 – 2) * ( 4 – 1 )
(displays the number 9)Show “shots = “ + 5
(displays ‘shots = 5’)Show “goal difference = “ + (4 – 2)
(displays ‘goal difference = 2’)Show “Team scored “ + (1 + 2) + “goals”
(displays ‘team scored 3 goals’)
TIMER (seconds, format)
Converts a time value that is in seconds to an hourly format.
Similar Command:
TIMER2 (converts a time value format from seconds to minutes)
Examples:
TIMER ( 3601.123,0 )
(displays 1:00:01)TIMER ( 3601.123,2 )
(displays 1:00:01.12)show TIMER ( 3601.123, "HH.mm.ss a" )
(displays 01.00.01 AM)TIMER2 ( 3601.123,2 )
(displays 60:01.12)
SportsCode Script Example:
Display the % possession of each team by first, creating a variable that calculates the total length of time (in seconds) each team had the ball, and then creating a third variable that divides the length of time for a particular team by the total length of time that both teams had the ball. Display the results by removing the decimal points and adding the % sign as text after the calculation result.
Commands To Run Calculations
COUNT
Counts the number of labels in the timeline, even if they appear multiple times in one event.
Examples:
COUNT “Messi”
COUNT “Messi” where row = “FC Barcelona Goals”
COUNT “Missed” where row = “Home Team Shots”
LENGTH
Calculates the length of time (in seconds) of the event labels or instances in the timeline.
Example:
LENGTH “Home Possession”
LENGTH “Home Possession” IN ROW = “Ball In Play”
LENGTH “Home Possession” IN ROW = “First Half” OR “Second Half”
ROUND (#, digits)
Rounds a number to the specified number of digits from the decimal point.
Similar Commands:
DECIMAL (#, digits) (rounds down a number to the specified number of digits from the decimal point, returning it as a string)
FLOOR (#, digits) (rounds down a number to the specified number of digits from the decimal point, returning it as a number)
CEILING (#, digits) (rounds a number up to the nearest decimal point)
ABS (#) (converts a number into its absolute value by removing all decimals)
Examples:
show ROUND (34.235, 2)
show ROUND (3423.456, -2)
show DECIMAL ( ROUND(0.499,0) ,2)
show CEILING (34.23001, 2)
TIME
Selects the events with a specific length of time.
Examples:
Count instances where time < 60
(counts the number of instances shorter than 60 seconds)Count "Counterattack" where row="Possession" and time < 30
(counts the counterattacks of less than 30 seconds)
Commands To Change Formatting & Appearance
SportsCode Script Example:
Create a shot frequency map using toggle buttons of player name that, when pressed, change the name of a separate button. This button is then used as the reference for all six buttons in the pitch location map to count the number of shots for the selected player for each position of the pitch using two types of labels: player name and shot location. The % of each location is then calculated with these counts. Lastly, an IF statement changes the colour of the button based on the % calculated by setting a different colour for different ranges.
BUTTON COLOR
Changes the background colour of the current button.
Similar Command:
SEND BUTTON COLOR (changes the background colour of a different button)
Examples:
BUTTON COLOR (100,0,0)
(red)BUTTON COLOR "FC Barcelona"
(changes the background colour of the current button to that from the button named "FC Barcelona"SEND BUTTON COLOR (100,0,0) TO BUTTON "Manchester Utd"
(changes the background colour of the button “Manchester Utd” to red)
TEXT COLOR
Changes the text colour in the name of the button.
Similar Command:
SEND TEXT COLOR (changes the text colour in a different button)
Examples:
TEXT COLOR (100,0,0)
(red)SEND TEXT COLOR (100,0,0) TO BUTTON "Manchester Utd"
(changes the colour of the text in the “Manchester Utd” button to red)
BUTTON OPACITY
Changes the opacity of the current button
Examples:
BUTTON OPACITY 50
(50% visible)BUTTON OPACITY 0
(hides button)
MOVE BUTTON BACK
Arranges the button so that it moves to the back of the code window not to overlap with other buttons.
Similar Command:
MOVE BUTTON FRONT (moves button to the front over other code buttons)
Examples:
MOVE BUTTON BACK
MOVE BUTTON FRONT
OUTPUT COLOR
Changes the text colour of the output from the button’s script.
Examples:
OUTPUT COLOR (100,0,0) changes the output color of the text to red.
Commands To Perform Actions
PUSH BUTTON button_name UP
Activates or deactivates a button.
Similar Commands:
PUSH BUTTON button_name DOWN (pushes a specific button down)
PUSH BUTTON UP WITH DELAY(pushes current button up after a specified delay in seconds)
PUSH BUTTON DOWN WITH DELAY (pushes current button down after a specified delay in seconds)
PUSH BUTTON UP (pushes the current button up)
PUSH BUTTON DOWN (pushes the current button down)
Examples:
PUSH BUTTON "name1" DOWN
PUSH BUTTON "name1" UP IN WINDOW "window1"
PUSH BUTTON DOWN WITH DELAY 0.2
RENAME new_button_name
Renames the current button.
Similar Commands:
RENAME GROUP new_group_name (renames the group name for the current button)
SEND value TO BUTTON button_name (changes the button name of a different button to the specified value)
Example:
RENAME "Atletico Possession"
RENAME GROUP "Away Team"
SEND "FC Barcelona" TO BUTTON "Home Team"
(renames the button with ID “Home Team” to be called “FC Barcelona”)
OPEN
Check whether a timeline is currently open in SportsCode.
Similar Command:
NOT OPEN (check whether a timeline is currently not open in SporstCode)
Examples:
IF ("FC Barcelona v Real Madrid" open, show "YES")
(display the text "YES" if the timeline is open)