view release on metacpan or  search on metacpan

lib/AI/MaxEntropy/Util.pm  view on Meta::CPAN

use strict;
use warnings;

package AI::MaxEntropy::Util;

use Exporter;

our $VERSION = '0.20';

our @ISA = qw/Exporter/;

our @EXPORT_OK =
    qw/traverse_partially map_partially train_and_test precision recall/;

our %EXPORT_TAGS =
    (all => [@EXPORT_OK]);

sub traverse_partially(&$$;$) {
    my ($code, $samples, $pattern, $t) = @_;
    $t ||= 'x';
    my ($p, $n) = (length($pattern), scalar(@$samples));
    for my $i (grep { substr($pattern, $_, 1) eq $t } (0 .. $p - 1)) {
        for (int($n * $i / $p) .. int($n * ($i + 1) / $p) - 1) {
	    $_ = $samples->[$_];
	    $code->();
	}
    }
}

sub map_partially(&$$;$) {
    my ($code, $samples, $pattern, $t) = @_;
    my @r;
    traverse_partially { push @r, $code->($_) } $samples, $pattern, $t;
    return \@r;
}

sub train_and_test {
    my ($me, $samples, $pattern) = @_;
    traverse_partially { $me->see(@$_) } $samples, $pattern, 'x';
    my $m = $me->learn;
    my $r = map_partially { [$_ => $m->predict($_->[0])] }
        $samples, $pattern, 'o';
    return ($r, $m);
}

sub precision {
    my $r = shift;
    my ($c, $n) = (0, 0);
    for (@$r) {
        my $w = defined($_->[0]->[2]) ? $_->[0]->[2] : 1;
        $n += $w;
        $c += $w if $_->[0]->[1] eq $_->[1];
    }
    return $c / $n;
}

sub recall {
    my $r = shift;
    my $label = shift;
    my ($c, $n) = (0, 0);
    for (@$r) {
        if ($_->[0]->[1] eq $label) {
            my $w = defined($_->[0]->[2]) ? $_->[0]->[2] : 1;
	    $n += $w;
	    $c += $w if $_->[1] eq $label;
	}
    }
    return $c / $n;
}

1;

__END__

=head1 NAME

AI::MaxEntropy::Util - Utilities for doing experiments with ME learners 

=head1 SYNOPSIS

  use AI::MaxEntropy;
  use AI::MaxEntropy::Util qw/:all/;

  my $me = AI::MaxEntropy->new;
  
  my $samples = [
      [['a', 'b', 'c'] => 'x'],
      [['e', 'f'] => 'y' => 1.5],
      ...
  ];

  my ($result, $model) = train_and_test($me, $samples, 'xxxo');

  print precision($result)."\n";
  print recall($result, 'x')."\n";

=head1 DESCRIPTION

This module makes doing experiments with Maximum Entropy learner easier.

Generally, an experiment involves a training set and a testing set
(sometimes also a parameter adjusting set). The learner is trained with
samples in the training set and tested with samples in the testing set.
Usually, 2 measures of performance are concerned.
One is precision, indicating the percentage of samples which are correctly
predicted in the testing set. The other one is recall, indicating the 
precision of samples with a certain label.

=head1 FUNCTIONS

=head2 train_and_test

This function automated the process of training and testing.

    my $me = AI::MaxEntropy->new;
    my $sample = [
        [ ['a', 'b'] => 'x' => 1.5 ],