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: