NAME
Sport::Analytics::NHL::PenaltyAnalyzer - analyze the penalties, generate their actual start and finish time and allow determination of on-ice strength and of PB population at any time.
SYNOPSIS
Analyze the game penalties and derive as much as possible useful information from them. This is a very complicated module that implements the NHL penalty rulebook as well as its changes over the years. It builds the timelines of all penalties during the game which indicates the on-ice strength and penalty box population at any point of time in the game. Often, the analysis contradict the NHL's own records, and that's because NHL's own records are erroneous. When the analysis can be tested by the actual on-ice player record, we do the verification, but prior to that, i.e. before 1999, we consider our implementation to be correct even when they contradict the record strength of a goal.
The generated strengths are then inserted into their own collection which is constructed like a timeline for each game.
my
$opts
= ...
my
$game_id
= 201820001;
analyze_game_penalties(
$game_id
,
$opts
->{dry_run});
set_strengths(
$game_id
,
$opts
->{dry_run});
Two main functions listed in the snippet are exported. All the rest are auxiliary and the author has a limited understand of why and how they work. But they do.
The teams are managed as indices: away is 0, home is 1.
FUNCTIONS
decrease_onice
-
The global variable two-member arrayref ON_ICE counts the number of players on ice for each team. This function decreases the on-ice count for the given team. The count cannot go below 4. The penalty shot situations are not analyzed here.
Arguments:
index
of the team (0|1)
Returns: void
increase_onice
-
This function increases the on-ice count for the given team. The count cannot go above 6.
Arguments:
index
of the team (0|1)
Returns: void
create_player_cache
-
Creates a cache of game player ids mapped to their positions. The cache is stored in $CACHE (see Sport::Analytics::NHL::Vars) global variable.
Arguments: the game
Returns: void.
dump_penalty
-
Debugging function that neatly formats a penalty by its attributes
Arguments: the penalty
Returns: void, prints output.
dump_pbox
-
Debugging function that produces the output of all penalties of both teams
Arguments: the current penalty box (a 2-vector arrayref)
Returns: void, prints output.
is_major_penalty
-
Checks if the penalty is a major one by the name, despite not carrying a 5-minute length.
Arguments: the penalty
the vocabulary of the penalty names
(see Sport::Analytics::NHL::Config)
Returns: 1
if
it is, 0
if
it isn't.
check_gross_misconduct
-
Checks if a gross misconduct has occurred and assigns an extra 5-minute major to it.
Arguments: the penalty
the gross misconduct vocabulary entry
the penalties array of the game
Returns: void
stack_penalties
-
Stacks two penalties that overlap but in fact must occur one after another - in a double minor or in a excessive penalty box population cases.
Arguments: the penalty to be stacked
the penalty it should be stacked
with
the flag to ignore the already existing stacking
link
Returns: void
split_double_minor
-
Splits the double minor into two stacked minor penalties
Arguments: the double penalty
the penalties array of the game
the
index
of the penalty in the array
Returns: void
check_multiple_penalties_by_player
-
Checks if the penalized player is already serving a penalty in the box
Arguments: the current penalty
the penalty box
Returns: the matched penalties
if
any.
prepare_penalties
-
Prepares a group of penalties by applying the functions described above to be processed later. Penalties that don't go on the clock are marked as such as well.
Arguments: the penalties vocabulary (
q.v.
)
the penalties to be prepared
the penalty box
Returns: void
expire_penalty
-
Expires a penalty that ran out its clock.
Arguments: the penalty
the penalized team's
index
the timestamp of the moment
the penalty box
Returns: void
expire_penalties
-
Loops through the penalty box to find the penalties to be expired at a given time.
Arguments: the
time
point
the penalty box
Returns: void
get_coincidental_penalties
-
Finds penalties awarded coincidentally at the same time point and groups them by length: 0, 2, 5, 10
Arguments: the current penalty
all penalties in the group
Returns: the hash of the coincidental penalties.
assign_0_10
-
Assigns 0-minute and 10-minute penalties to the penalty box
Arguments: the penalty box
the hash of the coincidental penalties
Returns: void
apply_captain_decision
-
Applies a deducted captain's decision on which penalties shall expire sooner.
Arguments: the coincidentals hashref
Returns: 1
if
there was a captain's decision
0
if
the order is FIFO.
has_coincidental_bench
-
Checks if coincidental penalties include a bench penalty
Arguments: the coincidentals hashref
Returns: 1
if
there was a bench penalty
0 otherwise
get_c52_count
-
Gets the count of coincidental matching 5 vs 2 penalties
Arguments: the coincidentals hashref
the penalty box
the
length
of the penalty (2 or 5)
Returns: the count of the coincidentals 5 vs 2.
adjudicate_substitute
-
Adjudicates whether the penalty is substituted
Arguments: the
length
of the penalty
the coincidentals hashref
the count of 5 vs 2 (see above)
the reference to a flag where 2-minute coincidentals
force a substitution
Returns: 1
if
a subsistution was required
0 otherwise
assign_coincidentals
-
Properly assigns coincidental penalties, adjusts their begin and end marks and sets them as matching penalties where applicable.
Arguments: the penalty box
the coincidentals hashref
the
length
of coincidentals to work
with
(5 or 2)
the reference to a flag where 2-minute coincidentals
force a substitution
Returns: void
assign_different_coincidentals
-
Assigns a special case of 5 vs 2 coincidentals in the last minutes or in the OT.
Arguments: the penalty box
the coincidentals hash
Returns: void
has_same_player1_or_servedby
-
Checks if two penalties has the same offending player or the same servedby
Arguments: penalty1
penalty2
Returns: 1 or 0
find_same_player_penalty
-
Finds penalties by the same player that was assigned another penalty
Arguments: the penalty box
that another penalty
Returns: 1 or 0
find_stack_penalty
-
Find the penalty that was stacked to the given penalty for the given team.
Arguments: the penalty box
the
given
penalty
the team
index
Returns: the stacked penalty or
undef
.
assign_remaining
-
After assigning the coincidental penalties, assign the remaining penalties to the penalty box.
Arguments: the penalty box
the remaining penalties
the
length
of these penalties
Returns: void
process_penalties
-
Processes a list of penalties assigning them to the penalty box and marking their derived properties.
Arguments: the arrayref of penalties
the penalty box
Returns: void
get_active_penalties
-
Gets penalties that are currently on the clock at the time of an event.
Arguments: the penalty box
the event
Returns: the penalties on the clock.
set_indicator
-
Sets the on-ice event strength indicator (type from 44 to 66, away team first, strength such as PP2 or SH1 or EV5) based on the penalty tracker.
Arguments: the indicator hashref
the event
the penalty box
the active penalties
Returns: void. Dies
if
invalid indicator is detected.
mark_scores
-
Marks the penalties if a goal was scored on them.
Arguments: the goal
the penalties on the clock, sorted
Returns: void
terminate_penalty
-
Terminates a penalty that was scored upon and thus ended.
Arguments: the goal
the penalties on the clock
Returns: void, penalties are modified.
restore_on_ice_player
-
Restores a player who is out of the box to the ice when the on-ice tracker of the NHL fails to do that.
Arguments: the goal
the penalty box
Returns: void, the event is updated.
get_real_on_ice
-
Gets the on ice count as provided by the NHL, or as explicitly marked in our constants at the top of this file.
Arguments: the event
Returns: the
"real"
ice count
Caveats: bad function name; debugging/testing only.
process_goal
-
Processes the penalties when a goal has been scored.
Arguments: the goal
the penalty box
Returns: void
clone_match_penalty
-
Clone a match penalty based on description when it should've accompanied a major.
Arguments: the major penalty
the end timestamp of the game
Returns: void
update_penalty
-
Updates a penalty in the database with all the information gathered.
Arguments: the penalty
the vocabulary entry
for
misconduct
the end timestamp of the game
Returns: void
update_penalties
-
Loops through the game penalties to update them
Arguments: the penalty box
the vocabulary of penalties
the end timestamp of the game
Returns: void
analyze_game_penalties
-
The main exporting function to prepare, process and update the penalties.
Arguments: the game
[optional] the dry run flag
Returns: void
init_strengths
-
Initializes the 'str' collection of strengths in the database.
Arguments: none
Returns: the collection
'str'
get_strength_affecting_penalties
-
Gets the list of on-ice strength affecting penalties from a game
Arguments: the game
Returns: the list of penalties
set_timeline
-
Sets the timeline array of penalties, with 1 marking the penalty start and 0 marking the finish
Arguments: the game
the game penalties
Returns: the timeline
update_on_ice_for_ot
-
Updates the special case of on-ice count during the regular season overtime based on the OT rules of that season.
Arguments: the on-ice count
the game
Returns: void
update_stack_on_ice_match
-
Updates either the on-ice count, or the penalty box stack count or the matched penalties count.
Arguments: the penalty entry from the timeline
the on-ice count
the stack count
the matching penalty count reference
Returns: void
push_strengths
-
Pushes a new entry to the strengths arrayref to be inserted later into the database.
Arguments: the strengths arrayref
the current timestamp
the
next
penalty timestamp
the game
the on_ice count
Returns: void
set_strengths
-
The main exporting function to prepare, process and insert the strengths.
Arguments: the game
[optional] the dry run flag
Returns: void
AUTHOR
More Hockey Stats, <contact at morehockeystats.com>
BUGS
Please report any bugs or feature requests to contact at morehockeystats.com
, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sport::Analytics::NHL::PenaltyAnalyzer. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Sport::Analytics::NHL::PenaltyAnalyzer
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
https://rt.cpan.org/NoAuth/Bugs.html?Dist=Sport::Analytics::NHL::PenaltyAnalyzer
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Sport::Analytics::NHL::PenaltyAnalyzer
CPAN Ratings
https://cpanratings.perl.org/d/Sport::Analytics::NHL::PenaltyAnalyzer
Search CPAN
https://metacpan.org/release/Sport::Analytics::NHL::PenaltyAnalyzer