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.
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.
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::PenaltyAnalyzerYou 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