NAME
    "Set::Partitions::Similarity" - Routines to measure similarity of
    partitions.

SYNOPSIS
      use Set::Partitions::Similarity qw(getAccuracyAndPrecision);
      use Data::Dump qw(dump);

      # set elements are Perl strings, sets are array references
      # partitions are nested arrays.
      dump getAccuracyAndPrecision ([[qw(a b)],[1,2]], [[qw(a b 1)],[2]]);
      # dumps:
      # ("0.5", "0.25")

      # a partition is equivalent to itself, even the empty partition.
      dump getAccuracyAndPrecision ([[1,2], [3,4]], [[2,1], [4,3]]);
      dump getAccuracyAndPrecision ([], []);
      # dumps:
      # (1, 1)
      # (1, 1)

      # accuracy and precision are symmetric functions.
      my ($p, $q) = ([[1,2,3], [4]], [[1], [2,3,4]]);
      dump getAccuracyAndPrecision ($p, $q);
      dump getAccuracyAndPrecision ($q, $p);
      # dumps:
      # ("0.333333333333333", "0.2")
      # ("0.333333333333333", "0.2")

      # checks partitions and throws an exception.
      eval { getAccuracyAndPrecision ([[1]], [[1,2]], 1); };
      warn $@ if $@;
      # dumps:
      # partitions are invalid, they have different set elements.

DESCRIPTION
    A partition of a set is a collection of mutually disjoint subsets of the
    set whose union is the set. "Set::Partitions::Similarity" provides
    routines that measure the *accuracy* and *precision* between two
    partitions of a set. The measures can assess the performance of a binary
    clustering algorithm by comparing the clusters the algorithm creates
    against the correct clusters of test data.

  Accuracy and Precision
    Let "S" be a set of "n" elements and let "P" be a partition of "S". Let
    T(S) be the set of all sets of two distinct elements of "S"; so T(S) has
    "n*(n-1)/2" sets. The partition "P" uniquely defines a partitioning of
    T(S) into two sets, C(P) and D(P) where C(P) is the set of all pairs in
    T(S) such that both elements of a pair occur in the same set in "P", and
    define D(P) as "T(S)-C(P)", the complement.

    Given two partitions "P" and "Q" of the set "S", the *accuracy* is
    defined as "(|C(P) ^ C(Q)| + |D(P) ^ D(Q)|) / (n*(n-1)/2)", where | |
    gives the size of a set and ^ represents the intersection operator. The
    *precision* is defined as "|C(P) ^ C(Q)| / (|C(P) ^ C(Q)| + |C(P) ^
    D(Q)| + |D(P) ^ C(Q)|)". The *accuracy* and *precision* return values
    ranging from zero (no similarity) to one (equivalent partitions). The
    *distance* between two partitions is defined as *1-accuracy*, and in
    mathematics is a metric. The *distance* returns values ranging from zero
    (equivalent partitions) to one (no similarity).

    All the methods implemented that compute the *accuracy*, *precision*,
    and *distance* run in time linear in the number of elements of the set
    partitioned.

ROUTINES
  "areSubsetsDisjoint ($Partition)"
    The routine "areSubsetsDisjoint" returns true if the subsets of the
    partition are disjoint, false otherwise. It can be used to check the
    validity of a partition.

    $Partition
        The partition is stored as a nested array reference of the form
        "[[],...[]]". For example, the set partition "{{a,b}, {1,2}}" of the
        set "{a,b,1,2}" should be stored as the nested array reference
        "[['a','b']],[1,2]]". Note the elements of a set are represented as
        Perl strings.

    An example:

      use Set::Partitions::Similarity qw(areSubsetsDisjoint);
      use Data::Dump qw(dump);
      dump areSubsetsDisjoint ([[1,2,3], [4]]);
      dump areSubsetsDisjoint ([[1,2,3], [4,1]]);
      # dumps:
      # "1"
      # "0"

  "getAccuracy ($PartitionP, $PartitionQ, $CheckValidity)"
    The routine "getAccuracy" returns the *accuracy* of the two partitions.

    "$PartitionP, $PartitionQ"
        The partitions are stored as nested array references of the form
        "[[],...[]]". For example, the set partition "{{a,b}, {1,2}}" of the
        set "{a,b,1,2}" should be stored as the nested array references
        "[['a','b']],[1,2]]". Note the elements of a set are represented as
        Perl strings.

    $CheckValidity
        If $CheckValidity evaluates to true, then checks are performed to
        ensure both partitions are valid and an exception is thrown if they
        are not. The default is false.

    An example:

      use Set::Partitions::Similarity qw(getAccuracy);
      use Data::Dump qw(dump);
      dump getAccuracy ([[qw(a b)], [qw(c d)]], [[qw(a b c d)]]);
      dump getAccuracy ([[qw(a b c d)]], [[qw(a b)], [qw(c d)]]);
      # dumps:
      # "0.333333333333333"
      # "0.333333333333333"

  "getAccuracyAndPrecision ($PartitionP, $PartitionQ, $CheckValidity)"
    The routine "getAccuracyAndPrecision" returns the *accuracy* and
    *precision* of the two partitions as an array "(accuracy, precision)".

    "$PartitionP, $PartitionQ"
        The partitions are stored as nested array references of the form
        "[[],...[]]". For example, the set partition "{{a,b}, {1,2}}" of the
        set "{a,b,1,2}" should be stored as the nested array references
        "[['a','b']],[1,2]]". Note the elements of a set are represented as
        Perl strings.

    $CheckValidity
        If $CheckValidity evaluates to true, then checks are performed to
        ensure both partitions are valid and an exception is thrown if they
        are not. The default is false.

    An example:

      use Set::Partitions::Similarity qw(getAccuracyAndPrecision);
      use Data::Dump qw(dump);
      dump getAccuracyAndPrecision ([[1,2], [3,4]], [[1], [2], [3], [4]]);
      dump getAccuracyAndPrecision ([[1], [2], [3], [4]], [[1,2], [3,4]]);
      # dumps:
      # ("0.666666666666667", 0)
      # ("0.666666666666667", 0)

  "getDistance ($PartitionP, $PartitionQ, $CheckValidity)"
    The routine "getDistance" returns *1-accuracy* of the two partitions, or
    "1-getAccuracy($PartitionP, $PartitionQ, $CheckValidity)".

    "$PartitionP, $PartitionQ"
        The partitions are stored as nested array references of the form
        "[[],...[]]". For example, the set partition "{{a,b}, {1,2}}" of the
        set "{a,b,1,2}" should be stored as the nested array references
        "[['a','b']],[1,2]]". Note the elements of a set are represented as
        Perl strings.

    $CheckValidity
        If $CheckValidity evaluates to true, then checks are performed to
        ensure both partitions are valid and an exception is thrown if they
        are not. The default is false.

    An example:

      use Set::Partitions::Similarity qw(getDistance);
      use Data::Dump qw(dump);
      dump getDistance ([[1,2,3], [4]], [[1], [2,3,4]]);
      # dumps:
      # "0.666666666666667"

  "getPrecision ($PartitionP, $PartitionQ, $CheckValidity)"
    The routine "getPrecision" returns the *precision* of the two
    partitions.

    "$PartitionP, $PartitionQ"
        The partitions are stored as nested array references of the form
        "[[],...[]]". For example, the set partition "{{a,b}, {1,2}}" of the
        set "{a,b,1,2}" should be stored as the nested array references
        "[['a','b']],[1,2]]". Note the elements of a set are represented as
        Perl strings.

    $CheckValidity
        If $CheckValidity evaluates to true, then checks are performed to
        ensure both partitions are valid and an exception is thrown if they
        are not. The default is false.

    An example:

      use Set::Partitions::Similarity qw(getPrecision);
      use Data::Dump qw(dump);
      dump getPrecision ([[1,2,3], [4]], [[1], [2,3,4]]);
      # dumps:
      # "0.2"

EXAMPLE
    The code following measures the *distance* of a set of 512 elements
    partitioned equally into subsets of size $s to the entire set.

      use Set::Partitions::Similarity qw(getDistance);
      my @p = ([0..511]);
      for (my $s = 1; $s <= 512; $s += $s)
      {
        my @q = map { [$s*$_..($s*$_+$s-1)] } (0..(512/$s-1));
        print join (', ', $s, getDistance (\@p, \@q, 1)) . "\n";
      }
      # dumps:
      # 1, 1
      # 2, 0.998043052837573
      # 4, 0.99412915851272
      # 8, 0.986301369863014
      # 16, 0.970645792563601
      # 32, 0.939334637964775
      # 64, 0.876712328767123
      # 128, 0.75146771037182
      # 256, 0.500978473581213
      # 512, 0

INSTALLATION
    To install the module run the following commands:

      perl Makefile.PL
      make
      make test
      make install

    If you are on a windows box you should use 'nmake' rather than 'make'.

BUGS
    Please email bugs reports or feature requests to
    "bug-set-partitions-similarities@rt.cpan.org", or through the web
    interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Set-Partitions-Similarit
    y>. The author will be notified and you can be automatically notified of
    progress on the bug fix or feature request.

AUTHOR
     Jeff Kubina<jeff.kubina@gmail.com>

COPYRIGHT
    Copyright (c) 2009 Jeff Kubina. All rights reserved. This program is
    free software; you can redistribute it and/or modify it under the same
    terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.

KEYWORDS
    accuracy, clustering, measure, metric, partitions, precision, set,
    similarity

SEE ALSO
