view release on metacpan or  search on metacpan

lib/Algorithm/Classifier/NaiveBayes.pm  view on Meta::CPAN

package Algorithm::Classifier::NaiveBayes;

use 5.006;
use strict;
use warnings;
use JSON::PP    ();
use File::Slurp qw(read_file write_file);

=head1 NAME

Algorithm::Classifier::NaiveBayes - A multinomial naive Bayes text classifier with Laplace smoothing.

=head1 VERSION

Version 0.0.1

=cut

our $VERSION = '0.0.1';

# version of the saved model format
our $MODEL_VERSION = 1;

=head1 SYNOPSIS

    use Algorithm::Classifier::NaiveBayes;

    my $nb = Algorithm::Classifier::NaiveBayes->new;

    # train it with examples of each class
    $nb->train( 'spam', 'buy cheap pills now' );
    $nb->train( 'spam', 'cheap watches for sale' );
    $nb->train( 'ham',  'meeting at noon tomorrow' );
    $nb->train( 'ham',  'lunch with the team' );

    # classify some new text
    my $class = $nb->classify('cheap pills for sale');
    # $class is now 'spam'

    # or get the score and probability for every class as well
    my ( $best, $scores, $probs ) = $nb->classify('cheap pills for sale');

    # save the model for later and load it again
    $nb->save('model.json');

    my $loaded = Algorithm::Classifier::NaiveBayes->new;
    $loaded->load('model.json');

=head1 DESCRIPTION

This module implements a multinomial naive Bayes classifier. Strings
are broken into tokens and each class is scored using the log of its
prior probability, based on how often the class was trained, plus the
sum of the log probabilities of each token appearing in that class.
Token probabilities are smoothed so tokens never seen for a class do
not zero out the whole score. By default this is add-one, Laplace,
smoothing, but Lidstone, add-alpha, smoothing with a configurable
alpha may be selected instead. Smaller alphas, such as 0.1 to 0.5,
often perform better on small training sets.

By default token occurrences are weighted by their raw counts, but
binary weighting, counting each unique token once per document, may
be selected instead via token_weighting. Class priors default to how
often each class was trained, but may be set to uniform via priors.

Classes are not predefined. A class exists once something has been
trained for it and stops existing if everything for it is untrained.

The model may be saved to a JSON file or string and loaded back later,
allowing training and classification to happen in different processes.

=head1 METHODS

=head2 new

Initiates the object.

    my $nb = Algorithm::Classifier::NaiveBayes->new(%args);

The following args are supported.

    lc_tokens - Lowercase tokens when tokenizing.
        Default: 1

    token_splitter - Regex to use for splitting a string into tokens.
        Default: \s+

    stop_regex - If defined, tokens matching this regex are dropped.
        Matched anchored, so it must match the entire token.
        Default: undef

    smoothing - The smoothing to use for token probabilities. Either
        "laplace", add-one, or "lidstone", add-alpha.
        Default: laplace

    alpha - The alpha to use for lidstone smoothing. Must be a number
        greater than 0. May only be specified when smoothing is set to
        lidstone. Laplace smoothing is lidstone with a alpha of 1.
        Default: 0.5

    ngrams - Max size of n-grams to generate from adjacent tokens when
        tokenizing. 1 means single tokens only. 2 means also generate
        each adjacent pair of tokens joined by a space. 3 also adds
        triplets and so on.
        Default: 1

    token_weighting - How token occurrences are weighted. "count" uses
        raw counts, so a token appearing three times in a document
        counts three times. "binary" counts each unique token once per
        document, both when training and classifying, which often works
        better for short texts. Also known as binarized multinomial
        naive Bayes.
        Default: count

    priors - How class priors are computed when classifying. "trained"
        uses how often each class was trained, so classes with more
        documents are favored. "uniform" gives every class a equal
        prior, useful when the training set is unbalanced in a way real
        usage will not be.
        Default: trained

token_splitter and stop_regex may be either a string or a qr// Regexp.