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.
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.
use Sport::Analytics::NHL::PenaltyAnalyzer 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.
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.
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.
More Hockey Stats, <contact at morehockeystats.com>
<contact at morehockeystats.com>
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.
contact at morehockeystats.com
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
To install Sport::Analytics::NHL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Sport::Analytics::NHL
CPAN shell
perl -MCPAN -e shell install Sport::Analytics::NHL
For more information on module installation, please visit the detailed CPAN module installation guide.