SYNOPSIS

use Games::Go::AGA::BayRate::Collection;
my $collection = Games::Go::AGA::BayRate::Collection->new(
        iter_hook      => \&iter_hook,
        tournamentDate => $tournamentDate,
        strict_compliance => $strict_compliance, # match original bayrate C++ code exactly
        #f_iterations   => 50,    # iteration limit for f method
        #fdf_iterations => 50,    # iteration limit for fdf method
        #verbose => 1,            # lots of debugging info (to STDOUT)
);

  foreach my $player (@players) {
      $collection->add_player(
          id     => $_player->id,
          seed   => $_player->seed,
        # sigma  => 0.0,  # may not need this
      );
  }

  # enter all the games
  foreach my $game (@games) {
      $collection->add_game(
          white     => $game->white->id,
          black     => $game->black->id,
          whiteWins => $game->whiteWins,
          handicap  => $game->handicap,
          komi      => $game->komi,
      );
  }

  $collection->initSeeding($tdList);

  $collection->calc_ratings;
  # Copy the new ratings into the internal TDList for the next tournament update
  foreach my $c_player (@{$collection->players}) {
      ... # do something with new $c_player->get_rating
  }

DESCRIPTION

Games::Go::AGA::BayRate::Collection is a perl implementation of collection.cpp found in the bayrate.zip package from the American Go Association (http://usgo.org).

Much of the following documentation is shamelessly stolen directly from collection.cpp.

METHODS

= $collection->add_player( %args )

Add tournament players. %args must include:

id   => unique_strings,
seed => value,

%args may include:

sigma => value,

ids are unique for all players in the tournament.

seed is the AGA rating converted (if necessary) to a floating point number with a 'gap' between -1.0 (1 kyu) and +1.0 (1 dan). Specifically, a medium-strength 1 dan converts to 1.5. A player who is just barely above 1 kyu is 1.01. A player who is just below 1 dan is -1.01, and a medium strength 1 kyu player is -1.5.

sigma is the standard deviation of the seed and represents the uncertainty in the seed. Higher sigma means less certain. If sigma is not given, an initial sigma is assigned based on some rather esoteric criterion (see AGARatings-Math.pdf at http://usgo.org and initSeeding) below).

$collection->add_game( %args )

Add a game to the collection. %args must include:

white     => white_id,
black     => black_id,
whiteWins =>  0 | 1,
handicap  => $handicap,
komi      => $komi,

where white_id and black_id correspond the the id given for a previous add_player. Games should only be added if they have a winner, who is indicated by the whiteWins argument. handicap and komi are numbers (should be 0 if appropriate).

initSeeding ()

Given players playing in a tournament, games in the tournament and the TDList data prior to a tournament, set each player's seed rating and sigma and calculate the handicap equivalent and sigma_px for each game.

Call initSeeding after all players and games have been added, and prior to calling calc_ratings.

calc_ratings ()

Calculates new ratings for all players based on seeds and game results.

findImprobables ()

Identify games that are highly improbable (<1% chance of being correct) Improbables usually indicates a data entry error or a player who has improved dramatically since their last rating who needs to be reseeded.

calc_sigma ()

This method calls calc_sigma1 and if that fails, it failsover to call calc_sigma2. In bayrate, it simply calls calc_sigma2.

calc_sigma2 ()

Calculate the new sigmas for players. This function uses numerical integration technique to calculate the variances directly.

calc_sigma1 ()

Calculate the new sigmas for players. This function uses the Laplace approximation to calculate the sigmas. This call can die if the matrix is not positive definite. In that case calc_sigma2() should be used as a backup.

calc_pt ()

Calculate the logarithm of the total likelihood of a particular set of ratings

calc_pt_df ()

Calculate the gradient of the logarithm of the total likelihood of a particular set of ratings

The likelihood function has a player contribution, which is nominally Gaussian (linear when a logarithm is taken) and depends only on sigma and the deviation from a player's seed ratings. There is also a game contribution, which depends on the result and game conditions of a particular contest

calc_ratings_f ()

Calculate ratings using a multidimensional simplex method. This technique is slower than the conjuagate gradient method, but it is more reliable.

This function should be slow, but foolproof. If an error occurs here the program prints an error message and fails.

calc_ratings_fdf ()

Calculate ratings using a conjugate gradient method. Technique fails if the initial guess happens to be exactly correct, which makes 'easy' test cases a little more difficult.