view release on metacpan or  search on metacpan

lib/Algorithm/AM/DataSet/Item.pm  view on Meta::CPAN

our $VERSION = '3.13';
# ABSTRACT: A single item for classification training and testing
use Carp;
our @CARP_NOT = qw(Algorithm::AM::DataSet);
use Exporter::Easy (
    OK => ['new_item']
);

# use to assign unique ids to new items; not meant to be secure
# or anything, just unique.
my $current_id = 'a';


#pod =head1 SYNOPSIS
#pod
#pod   use Algorithm::AM::DataSet::Item 'new_item';
#pod
#pod   my $item = new_item(
#pod     features => ['a', 'b', 'c'],
#pod     class => 'x',
#pod     comment => 'a sample, meaningless item'
#pod   );
#pod
#pod =head1 DESCRIPTION
#pod
#pod This class represents a single item contained in a data set. Each
#pod item has a feature vector and possibly a class label and comment
#pod string. Once created, the item is immutable.
#pod
#pod =head1 METHODS
#pod
#pod =head2 C<new>
#pod
#pod Creates a new Item object. The only required argument is
#pod 'features', which should be an array ref containing the feature
#pod vector. Each element of this array should be a string indicating the
#pod value of the feature at the given index. 'class' and 'comment'
#pod arguments are also accepted, where 'class' is the classification
#pod label and 'comment' can be any string to be associated with the item.
#pod A missing or undefined 'class' value is assumed to mean that the item
#pod classification is unknown. For the feature vector, empty strings are
#pod taken to indicate null values.
#pod
#pod =cut
sub new {
    my ($class, %args) = @_;
    if(!exists $args{features} ||
        'ARRAY' ne ref $args{features}){
        croak q[Must provide 'features' parameter of type array ref];
    }
    my $self = {};
    for(qw(features class comment)){
        $self->{$_} = $args{$_};
        delete $args{$_};
    }
    if(my $extra_keys = join ',', sort keys %args){
        croak "Unknown parameters: $extra_keys";
    }
    $self->{id} = $current_id;
    $current_id++;
    bless $self, $class;
    return $self;
}

#pod =head2 C<new_item>
#pod
#pod This is an exportable shortcut for the new method. If exported, then
#pod instead of calling C<<Algorithm::AM::DataSet::Item->new>>, you may
#pod simply call C<new_item>.
#pod
#pod =cut
sub new_item {
    # unpack here so that warnings about odd numbers of elements are
    # reported for this function, not for the new method
    my %args = @_;
    return __PACKAGE__->new(%args);
}

#pod =head2 C<class>
#pod
#pod Returns the classification label for this item, or undef if the class
#pod is unknown.
#pod
#pod =cut
sub class {
    my ($self) = @_;
    return $self->{class};
}

#pod =head2 C<features>
#pod
#pod Returns the feature vector for this item. This is an arrayref
#pod containing the string value for each feature. An empty string
#pod indicates that the feature value is null (meaning that it has
#pod no value).
#pod
#pod =cut
sub features {
    my ($self) = @_;
    # make a safe copy
    return [@{ $self->{features} }];
}

#pod =head2 C<comment>
#pod
#pod Returns the comment for this item. By default, the comment is
#pod just a comma-separated list of the feature values.
#pod
#pod =cut
sub comment {
    my ($self) = @_;
    if(!defined $self->{comment}){
        $self->{comment} = join ',', @{ $self->{features} };
    }
    return $self->{comment};
}

#pod =head2 C<cardinality>
#pod
#pod Returns the length of the feature vector for this item.
#pod