view release on metacpan or  search on metacpan

lib/Baseball/Sabermetrics.pm  view on Meta::CPAN

package Baseball::Sabermetrics;

use Baseball::Sabermetrics::Team;
use Baseball::Sabermetrics::Player;
use strict;
use warnings;
use base qw/ Baseball::Sabermetrics::Team /;

=head1 NAME

Baseball::Sabermetrics - A Baseball Statistics Module

=cut

our $VERSION = '0.03';

=head1 SYNOPSIS

Baseball::Sabermetrics provides an easy interface for calculating baseball statistics, given a data importer.  In this package, I've written CPBL.pm for (I<Chinese Professional Baseball League>, L<http://www.cpbl.com.tw>).

  use Baseball::Sabermetrics;
  use Baseball::Sabermetrics::CPBL;

  my $league = Baseball::Sabermetrics->new(league => 'CPBL');

  # Actually these are predefined.
  # Those data with 'p_' or '_allowed' here are for seperating pitchers
  # and batters.

  $league->define(
      rc => 'ab * obp',
      babip => '(h_allowed - hr_allowed) / (p_pa - h_allowed - p_so - p_bb - hr_allowed',
      # what started with '$' will be reserved.
      # Players have team and league predefined, and team has league.
      formula1 => 'hr / $_->team->hr';
      formula2 => 'hr / $_->league->hr';
      complex => sub {
	    print "You can write a sub directly\n";
	    $_->slg - $_->ba;
      },
      ...
  );

  # Some formulas can be applied to players, teams, and league, depend on what
  # columns are used in the formula.  For example, ab and obp are defined for
  # players, teams, and league, so that rc is available for all of them.

  # top 5 obp of teams
  $_->print qw/ team name ba obp slg isop / for $league->top('teams', 5, 'obp');

  # top 10 obp of players
  $_->print qw/ team name ba obp slg isop / for $league->top('players', 10, 'obp');

  # show a player's information
  $league->players('Chien-Ming Wang')->print qw/ win lose ip so bb whip go_ao /;
  $league->teams('Yankees')->players('Chien-Ming Wang')->print qw/ win lose ip so bb whip go_ao /;

  # show team statistics data (accumulated from players')
  $league->{Yankees}->print qw/ win lose ip so bb whip go_ao /;

  # give a brief report for pitchers/batters of the team
  $league->{Yankees}->report_pitchers qw/ name ip p_so p_bb whip go_ab /;
  $league->{Yankees}->report_batters  qw/ name ba obp slg isop /;

  $league->report_teams qw/ name win lose era obp /;

  # show all available formula
  print join ' ', $league->formula_list;

=head1 Data Structure

Baseball::Sabermetrics is aimed for providing a base class of your interested teams (a league, for example).  You'll need to provide a data retriever to pull data out.  The following example shows how you have to fill data into this structure.

 $league = {
    teams => {
	Yankees => {
	    players => {
		"Chien-Ming Wang" => {
		    bio => {
			bats => 'right', # coule be left, switch
			throws => 'right',
		    },
		    ip => 57.33333333333,
	     	    game => 9,
		       ...
		    fielding => {
			p => {
			    tc => 43,
			    pop => 4,
			    ...
			},
			# b1 => { }, b2 => { }, b3 => { },
			# first, second and thrid baseman should be
			# b1, b2, and b3 respectively for convenient in
			# fielding context.  Because the initial of the
			# name of subroutine can't be a number in perl.
		    },
		};
		...
	    }
	},
	Athletics => {
	    ...
	},
    },
 };

=head1 TERMS

Available terms of players (including teams and league, which are accumulated from players and could be treated as an abstract player) are:

    # pitching
    p_game win lose tie gs sv bs hld cg sho ip p_pa np h_allowed
    hr_allowed sh_allowed sf_allowed p_bb p_ibb hb p_so wp bk ra er

    # batting
    pa ab rbi r h 1b 2b 3b hr tb dp sh sf ibb bb hbp so sb cs
    tc po a e f_dp ppo tp pb c_cs c_sb

    # fielding
    pos fgame tc po a e f_dp tp pb c_cs c_sb

And there are additional terms for team:

    game win lose tie


=head1 FUNCTIONS