/ 
Sport-Analytics-NHL-1.53
River stage zero No dependents
/ Sport::Analytics::NHL::DB

NAME

Sport::Analytics::NHL::DB - Interface to MongoDB to store NHL reports.

SYNOPSYS

Interface to MongoDB in order to store the semi-structured NHL reports into it. Provides the database handle and most of the bulky database operations. Does not subclass MongoDB - the handle is stored in the class's object.

use Sport::Analytics::NHL::DB;
my $db = Sport::Analytics::NHL::DB->new();
my $team_id = $db->resolve_team_db('San Jose Sharks'); # $team_id becomes 'SJS'.

METHODS

new
Constructor. Sets the database connection. Controlled by global variables:
 * $MONGO_HOST - host of the mongodb server (def. 127.0.0.1)
 * $MONGO_PORT - port of the mongodb server (def. 27017)
 * $MONGO_DB   - name of the mongo database (def 'hockey')
 Also, the database can be specified via $ENV{HOCKEYDB_DBNAME}

The database handle is stored in the dbh field of the object which is a blessed hashref.
resolve_team_db
Resolves a team by a given possible identifier to a normalized 3-letter identifier. The target identifiers are the keys to the %TEAMS hash in Sport::Analytics::NHL::Config.pm (q.v.)
Argument: the team identifier/name (e.g. 'Rangers')
Returns: the system identifier (e.g. NYR)
insert_schedule
Inserts the collected schedule (see Sport::Analytics::NHL::Scraper), initializing the indexes for the schedule collection if necessary.
Collections: schedule
Arguments: the list of scheduled games with their defined fields
Returns: the number of the inserted games
get_existing_game_ids
Gets the list of ids of games already in the database
Collections: games
Arguments: optional - hashref containing the start_season and stop_season of the query
Returns: the arrayref of the ids of the existing games
add_game

Actually puts the fully prepared boxscore, with set references to other collections, into the database.

Argument: the boxscore
Returns: the inserted id
add_game_coaches

Adds the coaches of the teams from the boxscore to the database and provides a reference to the added coach in the boxscore.

Argument: the boxscore
Returns: void, the coaches names are replaced with OIDs in the boxscore.
add_game_player

Adds a player from the boxscore to the database, and sets his team, injury, start and captaincy statuses and histories.

Arguments:
* the player hashref as parsed by Sport::Analytics::NHL::Report::Player
* the game boxscore
* the player's team name
* [optional] overwrite force flag

Returns: void
add_new_coach

Initializes a new entry for a coach in the database.

Arguments:
* the coaches database collection
* the boxscore
* the team of the coach from the boxscore

Returns: the OID of the coach
add_new_player

Initializes a new entry for a player in the database.

Arguments:
* the players database collection
* the player parsed by Sport::Analytics::Report::Player (q.v.)

Returns: the id of the inserted player
create_event

Creates a new event in the database, referencing all relevant fields by their own database catalogs. The event is inserted twice: first, with only least indexing information into the general 'events' collection; second, with the particular information in the event type's collection.

Argument: the event from the boxscore
Returns: the inserted event's id.
create_location

Creates a new location (stadium/arena) entry in the database by its name and capacity.

Argument: the location information from the boxscore
Returns: the location entry as inserted.
ensure_event_indices

Ensures the correct extra indices for the event's type collection.

Arguments:
* the event
* the event's collection

Returns: void
ensure_index

Wraps around the new MongoDB collection index creation routine, replacing its own ensure_index() method.

Arguments:
* the collection
* the index mapping as expected by create_one or create_many
* [optional] - whether to reapply the index on non-empty collection

Returns: the status of the index creation
get_catalog_entry

Creates if necessary a catalog of NHL event subtypes (e.g. zones, penalties, stop reasons) by the name of the event subtype as normalized by the vocabulary in Sport::Analytics::NHL::Config (q.v.), and fetches the corresponding entry.

Arguments:
* the catalog's name to operate upon
* the name of the catalog item
get_collection

A wrapper over $self->{dbh}->get_collection();

remove_game

Removes a game and references to it from the Mongo DB

Arguments: the game

Returns: void

Caveat: removal of all traces is not guaranteed.
set_injury_history

Sets the injury history of the player in the database. Either the current status is extended, or if the status changed, a new chapter is added.

Arguments:
* player's db entry
* the boxscore
* the injury status

Returns: void
set_player_statuses

Sets the status (captain, assistant captain) history of the player in the database. Either the current status (with the same team) is extended, or if the status changed, a new chapter is added.

Arguments:
* player's db entry
* player's boxscore entry
* the boxscore
* the player's team name

Returns: void
set_player_teams

Sets the team history of the player in the database. Either the current team is extended, or if the team changed, a new chapter is added.

Arguments:
* player's db entry
* the boxscore
* the team

Returns: void

This function is similar to the two above and all of them may be merged into one.

wipe_game_from_player_history

During removal of game data, wipes a game from player's history.

Arguments:
* player's db entry
* game's db entry

Returns: void
bootstrap_divisions_conferences

Bootstraps the NHL divisions and conferences from the Sport::Analytics::NHL::Config definitions

Arguments: force overwrite flag (optional)

Returns: void
bootstrap_teams

Bootstraps the NHL teams from the Sport::Analytics::NHL::Config definitions

Arguments: force overwrite flag (optional)

Returns: void
ensure_shift_indices

Ensures the custom indices for the shifts collection.

Arguments: none

Returns: void
find_items_with_games

Returns the iterator of items by given game ids. Mostly used by the website, but should get the usage expanded.

Arguments: the hashref of:
 collection of the items
 condition to apply
 [optional] id_field of the collection
 [optional] game_ids to look up
 [optional] return_fields to return
 [optional] count whether to return the iterator or the count

Returns: the iterator or the count of matching documents.
find_player

Finds a player by given name, team, season, stage

Arguments: the player name
           the team
           the season
           the stage

Returns: player's ID if the player is unambiguously found
         dies if more than one players are found
         warns if no players are found
get_catalog_condition

Get a catalog item's condition for a search

Arguments: the catalog's name
           the vocabulary entry name

Returns: hashref catalog_name => catalog_item_id
get_item_collection

Gets a collection for a given item by name. Expect to be deprecated.

Arguments: the collection itself, or the collection name (optional)

Returns: the collection or by default the games collection.
get_item_condition

Expands an item condition from vocabulary names to catalog IDs

Arguments: the condition

Returns the expanded condition or
        the original condition
         if the 'verbatim' keyword was specified.
insert

A generic wrapper over the MongoDB::Collection's insert_one / insert_many / replace_one methods. Generates the 'inserted' / 'updated' field as well.

Arguments: the collection
           the array of items

Returns: void
prepare_event

Cleans up an event before inserting it into the Mongo DB.

Arguments: the event
           the events hashref for tracking and debugging

Returns: void
update

A generic wrapper over the MongoDB::Collection's update_one / update_many methods. Generates the 'updated' field as well.

Arguments: the one_many flag: 1 means many,
           the collection
           the filter to update
           the update arguments

Returns: void
insert_injuries

Inserts the data structure with injuries as crawled by Sport::Analytics::NHL::Scraper::crawl_injured_players() (q.v.), The players are resolved to the player ids, and the begin and the end of the injuries are marked. If the player is already in an injury status with the same team, the injury "end" property is extended.

Arguments: the injuries structure

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

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2018 More Hockey Stats.

This program is released under the following license: gnu