view release on metacpan or  search on metacpan

lib/Algorithm/AM/Result.pm  view on Meta::CPAN

# encapsulate information about a single classification result
package Algorithm::AM::Result;
use strict;
use warnings;
our $VERSION = '3.13';
# ABSTRACT: Store results of an AM classification
use Text::Table;

#pod =head2 SYNOPSIS
#pod
#pod   use Algorithm::AM;
#pod
#pod   my $am = Algorithm::AM->new('finnverb', -commas => 'no');
#pod   my ($result) = $am->classify;
#pod   print @{ $result->winners };
#pod   print $result->statistical_summary;
#pod
#pod =head2 DESCRIPTION
#pod
#pod This package encapsulates all of the classification information
#pod generated by L<Algorithm::AM/classify>, including the assigned class,
#pod score to each class, gang effects, analogical sets,
#pod and timing information. It also provides several methods for
#pod generating printable reports with this information.
#pod
#pod Note that the words 'score' and 'point' are used here to represent
#pod whatever count is assigned by analogical modeling during
#pod classification. This can be either pointers or occurrences. For an
#pod explanation of this, see L<Algorithm::AM::algorithm>.
#pod
#pod All of the scores returned by the methods here are scalars with
#pod special PV and NV values. You should excercise caution when doing
#pod calculations with them. See L<Algorithm::AM::BigInt> for more
#pod information.
#pod
#pod =cut

## TODO: variables consider exporting someday
## @itemcontextchain
## %itemcontextchainhead
## %context_to_class
## %context_size
use Class::Tiny qw(
    exclude_nulls
    given_excluded
    cardinality
    test_in_train
    test_item
    count_method

    start_time
    end_time

    training_set

    scores
    high_score
    total_points
    winners
    is_tie
    result

    scores_normalized
), {
    'scores_normalized' => sub {
        my ($self) = @_;
        my $total_points = $self->total_points;
        my $scores = $self->scores;
        my $normalized = {};
        for my $class (keys %$scores){
            $normalized->{$class} = $scores->{$class} / $total_points
        }
        return $normalized;
    },
};
use Carp 'croak';
use Algorithm::AM::BigInt 'bigcmp';

# For printing percentages in reports
my $percentage_format = '%.3f';

#pod =head1 REPORT METHODS
#pod
#pod The methods below return human eye-friendly reports about the
#pod classification. The return value is a reference, so it must be
#pod dereferenced for printing like so:
#pod
#pod  print ${ $result->statistical_summary };
#pod
#pod =head2 C<config_info>
#pod
#pod Returns a scalar (string) ref containing information about the
#pod configuration at the time of classification. Information from the
#pod following accessors is included:
#pod
#pod     exclude_nulls
#pod     given_excluded
#pod     cardinality
#pod     test_in_train
#pod     test_item
#pod     count_method
#pod
#pod =cut
sub config_info {
    my ($self) = @_;
    my @headers = ('Option', 'Setting');
    my @rows = (
        [ "Given context", (join ' ', @{$self->test_item->features}) .
            ', ' . $self->test_item->comment],
        [ "Nulls", ($self->exclude_nulls ? 'exclude' : 'include')],
        [ "Gang",  $self->count_method],

lib/Algorithm/AM/Result.pm  view on Meta::CPAN

Return a hash describing gang effects. Gang effects are similar to
analogical sets, but the total effects of entire subcontexts and
supracontexts are also calculated and printed.

TODO: details, details! Maybe make a gang class to hold this structure.

=head2 C<analogical_set>

The analogical set is the set of items from the training set that
had some effect on the item classification. The analogical effect of
an item in the analogical set is the score it contributed towards
a classification matching its own class label.

This method returns the items in the analogical set along with their
analogical effects, in the following structure:

 { 'item_id' => {'item' => item, 'score' => score}

C<item> above is the actual item object. The item_id is used so that
the analogical effect of a particular item can be found quickly:

 my $set = $result->analogical_set;
 print 'the item's analogical effect was '
     . $set->{$item->id}->score;

=head2 C<high_score>

Returns the highest score assigned to any of the class labels.

=head2 C<scores>

Returns a hash mapping all predicted classes to their scores.

=head2 C<scores_normalized>

Returns a hash mapping all predicted classes to their score,
divided by the total score for all classes. For example,
if the L</scores> method returns the following:

 {'e' => 4, 'r' => 9}

then this method would return the following (values below are
rounded):

 {'e' => 0.3076923, 'r' => 0.6923077}

=head2 C<winners>

Returns an array ref containing the classes which had the highest
score. There is more than one only if there is a tie for the highest
score.

=head2 C<is_tie>

Returns true if more than one class was assigned the high score.

=head2 C<total_points>

The sum total number of points assigned as a score to any contexts.

=head2 C<start_time>

Returns the start time of the classification.

=head2 C<end_time>

Returns the end time of the classification.

=head1 AUTHOR

Theron Stanford <shixilun@yahoo.com>, Nathan Glenn <garfieldnate@gmail.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Royal Skousen.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut