view release on metacpan or  search on metacpan

lib/Algorithm/KernelKMeans.pm  view on Meta::CPAN

package Algorithm::KernelKMeans;

use strict;
use warnings;
use UNIVERSAL::require;

our $VERSION = '0.03';

BEGIN {
  for my $impl (qw/XS PP/) {
    my $impl_class = __PACKAGE__ . '::' . $impl;
    if ($impl_class->require) {
      our $IMPLEMENTATION = $impl;
      parent->use($impl_class); # be child of $impl_class
      last;
    }
  }
}

1;

__END__

=head1 NAME

Algorithm::KernelKMeans - Weighted kernel k-means clusterer

=head1 SYNOPSIS

  use Algorithm::KernelKMeans;
  use Algorithm::KernelKMeans::Util qw/generate_polynominal_kernel/;
  use List::MoreUtils qw/zip/;
  use Try::Tiny;
  
  my @vertices = map {
    my @values = split /\s/;
    my @keys = 0 .. $#values;
    +{ zip @keys, @values };
  } (<>);
  my $kernel = generate_polynominal_kernel(1, 2); # K(x1, x2) = (1 + x1x2)^2
  my $wkkm = Algorithm::KernelKMeans->new( # default weights are 1
    vertices => \@vertices,
    kernel => $kernel
  );
  
  my @clusters;
  try {
    @clusters = $wkkm->run(k => 6);
    for my $cluster (@clusters) {
      ...
    }
  } catch {
    # during iteration, number of clusters became less than k_min
    if (/number of clusters/i) { ... }
  }

=head1 DESCRIPTION

C<Algorithm::KernelKMeans> provides weighted kernel k-means vector clusterer.

Note that this is a very early release. All APIs may be changed incompatibly.

=head2 IMPLEMENTATION

This class is just a placeholder. Implementation code is in other class and this class just inherits it.

Currently there are 2 implementations: L<Algorithm::KernelKMeans::PP> and L<Algorithm::KernelKMeans::XS>.

C<$Algorithm::KernelKMeans::IMPLEMENTATION> indicates which implementation is loaded.

Both of these implements same interface (documented below) and C<Algorithm::KernelKMeans> uses faster (XS) implementation if it's available.
So it's not necessary usually to use the classes directly tough, you can do it if you want.

=head1 METHODS

=head2 new(%opts)

Constructor. you can specify options below:

=head3 vertices

Required. Array ref of vectors.
Each vector is represented as an hash ref of positive real numbers.

e.g.:

 my $wkkm = Algorithm::KernelKMeans->new(
   vertices => [ [ 229, 151, 42 ], [ 61, 151, 251 ], [ 11, 120, 55 ] ]
 );
]

=head3 weights