##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

##========================================================================
## NAME
=pod

=head1 NAME

DiaColloDB::Profile::Diff - diachronic collocation db, diff profiles

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Profile::Diff;
 
 ##========================================================================
 ## Constructors etc.
 
 $prf   = $CLASS_OR_OBJECT->new(%args);
 $dprf2 = $dprf->clone();
 
 ##========================================================================
 ## Basic Access
 
 ($prf1,$prf2) = $dprf->operands();
 $bool = $dprf->empty();
 
 ##========================================================================
 ## I/O: JSON
 
 $obj = $CLASS_OR_OBJECT->loadJsonData( $data,%opts);
 
 ##========================================================================
 ## I/O: Text
 
 undef = $CLASS_OR_OBJECT->saveTextHeader($fh, hlabel=>$hlabel, titles=>\@titles);
 $bool = $prf->saveTextFh($fh, %opts);
 
 ##========================================================================
 ## I/O: HTML
 
 $bool = $prf->saveHtmlFile($filename_or_handle, %opts);
 
 ##========================================================================
 ## Compilation
 
 $dprf = $dprf->populate();
 $dprf = $dprf->compile($func,%opts);
 $dprf = $dprf->uncompile();
 
 $opname = $CLASS_OR_OBJECT->diffop($opNameOrAlias);
 $opsub  = $CLASS_OR_OBJECT->diffsub($opNameOrAlias);
 $how    = $CLASS_OR_OBJECT->diffpretrim($opNameOrAlias);
 $key    = $CLASS_OR_OBJECT->diffkbest($opNameOrAlias);
 
 $diff   = diffop_diff($ascore,$bscore);
 $diff   = diffop_sum($ascore,$bscore);
 $diff   = diffop_min($ascore,$bscore);
 $diff   = diffop_max($ascore,$bscore);
 $diff   = diffop_avg($ascore,$bscore);
 $diff   = diffop_havg($ascore,$bscore);
 $diff   = diffop_gavg($ascore,$bscore);
 $diff   = diffop_lavg($ascore,$bscore);
 
 ##========================================================================
 ## Trimming
 
 \@keys    = $dprf->which(%opts);
 $dprf     = $dprf->trim(%opts);
 ($pa,$pb) = $CLASS_OR_OJBECT->pretrim($pa,$pb,%opts);
 
 ##========================================================================
 ## Stringification
 
 $dprf = $dprf->stringify( $obj);
 
 ##========================================================================
 ## Binary operations
 
 $dprf = $dprf->_add($dprf2,%opts);
 

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

DiaColloDB::Profile::Diff is a
L<DiaColloDB::Profile|DiaColloDB::Profile> subclass
class for representing
low-level collocate frequency comparison data
for a single date-slice
as arising from the comparison of two
L<DiaColloDB::Profile|DiaColloDB::Profile> objects.

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Profile::Diff: Globals & Constants
=pod

=head2 Globals & Constants

=over 4

=item @ISA

DiaColloDB::Profile::Diff inherits from
L<DiaColloDB::Profile|DiaColloDB::Profile>.

=item %DIFFOPS

Canonical diff-operation names keyed by alias.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Profile::Diff: Constructors etc.
=pod

=head2 Constructors etc.

=over 4

=item new

 $prf = $CLASS_OR_OBJECT->new(%args);
 $prf = $CLASS_OR_OBJECT->new($prf1,$prf2,%args)

%args, object structure:

 ##-- DiaColloDB::Profile::Diff
 prf1 => $prf1,     ##-- 1st operand
 prf2 => $prf2,     ##-- 2nd operand
 diff => $diff,     ##-- low-level score-diff binary operation (default='adiff')
 ##-- DiaColloDB::Profile keys
 label => $label,   ##-- string label (used by Multi; undef for none(default))
 #N   => $N,         ##-- OVERRIDE:unused: total marginal relation frequency
 #f1  => $f1,        ##-- OVERRIDE:unused: total marginal frequency of target word(s)
 #f2  => \%f2,       ##-- OVERRIDE:unused: total marginal frequency of collocates: ($i2=>$f2, ...)
 #f12 => \%f12,      ##-- OVERRIDE:unused: collocation frequencies, %f12 = ($i2=>$f12, ...)
 ##
 eps => $eps,       ##-- smoothing constant (default=undef: no smoothing)
 score => $func,    ##-- selected scoring function ('f12', 'mi', or 'ld')
 mi => \%mi12,      ##-- DIFFERENCE: score: mutual information * logFreq a la Wortprofil; requires compile_mi()
 ld => \%ld12,      ##-- DIFFERENCE: score: log-dice a la Wortprofil; requires compile_ld()
 fm => \%fm12,      ##-- DIFFERENCE: score: frequency per million; requires compile_fm()

The C<diff> option selects the function to be used to to compute final scores from operand profiles.
The default value is 'adiff'. Currently known values are:

 adiff     # $score=$a-$b      # aliases=qw(absolute-difference abs-difference abs-diff adiff adifference a-) ; select=kbesta
 diff      # $score=$a-$b      # aliases=qw(difference diff d minus -)
 sum       # $score=$a+$b      # aliases=qw(sum add plus +)
 min       # $score=min($a,$b) # aliases=qw(minimum min <)
 max       # $score=max($a,$b) # aliases=qw(maximum max >)
 avg       # $score=avg($a,$b) # aliases=qw(average avg mean)
 havg      # $score~=harmonic_avg($a,$b)  # aliases=qw(harmonic-average harmonic-mean havg hmean ha h)
 gavg      # $score~=geometric_avg($a,$b) # aliases=qw(geometric-average geometric-mean gavg gmean ga g)
 lavg      # $score~=log_avg($a,$b)       # aliases=qw(logarithmic-average logarithmic-mean log-average log-mean lavg lmean la l)

To avoid singularities resulting from sparse data,
the C<havg> and C<gavg> operations actually compute the arithmetic average
of the harmonic (rsp. geometric) mean of and the raw arithmetic mean; e.g.

 score_havg($a,$b) = (($a<0 || $b<0 ? 0 : (2*$a*$b)/($a+$b) ##-- harmonic mean
                      + ($a+$b)/2                           ##-- arithmetic mean
                     )/2                                    ##-- average of harmonic- and arithmetic-means

The default C<diff> operation is C<adiff>, which selects those items with the greatest absolute differences
among the (pre-trimmed) k-best items in its operand profiles.
The C<sum> and C<avg> operations return equivalent rankings,
but may assign undesirably high score values for non-uniform operand values
(e.g. C<avg(0,8)=avg(4,4)=4>, but only the latter configuration indicates similar collocation behavior
in the operand profiles).
The C<havg>, C<gavg>, and C<lavg> operations attempt to address this shortcoming
by penalizing non-uniform score-pairs, and tend to return similar rankings in the
range [$a:$b].

=item clone

 $dprf2 = $dprf->clone();
 $dprf2 = $dprf->clone($keep_compiled);

clones %$dprf;
if $keep_score is true, compiled data is cloned too.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Profile::Diff: Basic Access
=pod

=head2 Basic Access

=over 4

=item operands

 ($prf1,$prf2) = $dprf->operands();

get operand profiles.

=item empty

 $bool = $dprf->empty();

returns true iff both operands are empty

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Profile::Diff: I/O: JSON
=pod

=head2 I/O: JSON

=over 4

=item loadJsonData

 $obj = $CLASS_OR_OBJECT->loadJsonData( $data,%opts);

guts for loadJsonString(), loadJsonFile()

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Profile::Diff: I/O: Text
=pod

=head2 I/O: Text

See also L<DiaColloDB::Persistent|DiaColloDB::Persistent>.

=over 4

=item saveTextHeader

 undef = $CLASS_OR_OBJECT->saveTextHeader($fh, hlabel=>$hlabel, titles=>\@titles);

print column title header for text output.

=item saveTextFh

 $bool = $prf->saveTextFh($fh, %opts);

save flat TAB-separated text, format:

 Na Nb F1a F1b F2a F2b F12a F12b SCOREa SCOREb SCOREdiff LABEL ITEM2...

%opts:

 label => $label,   ##-- override $prf->{label} (used by Profile::Multi), no tab-separators required
 format => $fmt,    ##-- printf score formatting (default="%.4f")
 header => $bool,   ##-- include header-row? (default=1)
 hlabel => $hlabel, ##-- prefix header item-cells with $hlabel (used by Profile::MultiDiff)

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Profile::Diff: I/O: HTML
=pod

=head2 I/O: HTML

=over 4

=item saveHtmlFile

 $bool = $prf->saveHtmlFile($filename_or_handle, %opts);

Save flat HTML table data with rows of the form

 SCOREa SCOREb DIFF PREFIX? ITEM2...

If C<verbose> option is specified and true, saved table has the form

 Na Nb F1a F1b F2a F2b F12a F12b SCOREa SCOREb DIFF PREFIX? ITEM2...

Options %opts:

 table   => $bool,    ##-- include <table>..</table> ? (default=1)
 body    => $bool,    ##-- include <html><body>..</html></body> ? (default=1)
 header  => $bool,    ##-- include header-row? (default=1)
 verbose => $bool,    ##-- include verbose output? (default=0)
 hlabel  => $hlabel,  ##-- prefix header item-cells with $hlabel (used by Profile::Multi), no '<th>..</th>' required
 label   => $label,   ##-- prefix item-cells with $label (used by Profile::Multi), no '<td>..</td>' required
 format  => $fmt,     ##-- printf score formatting (default="%.4f")

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Profile::Diff: Compilation
=pod

=head2 Compilation

=over 4

=item populate

 $dprf = $dprf->populate();
 $dprf = $dprf->populate($prf1,$prf2);

populates diff-profile by subtracting $prf2 scores from $prf1.

=item compile

 $dprf = $dprf->compile($func,%opts);

compile for score-function $func, one of qw(f fm mi ld); default='f'.

=item uncompile

 $dprf = $dprf->uncompile();

un-compiles all scores for $dprf

=item diffop

 $opname = $dprf->diffop();
 $opname = $CLASS_OR_OBJECT->diffop($opNameOrAlias);

Returns canonical diff operation-name for C<$opNameOrAlias>.

=item diffsub

 \&FUNC = $dprf->diffsub();
 \&FUNC = $CLASS_OR_OBJECT->diffsub($opNameOrAlias);

Returns low-level binary diff operation for diff-operation C<$opNameOrAlias> (default=C<$dprf-E<gt>{diff}>).

=item diffpretrim

 $how = $dprf->diffpretrim()
 $how = $CLASS_OR_OBJECT->diffpretrim($opNameOrAlias)

Returns whether and how a diff operation C<$opNameOrAlias> should pre-trim operand profiles.
Returned value is one of:

 'restrict' # intersect defined collocates (min,avg,havg,gavg)
 'kbest'    # union of k-best collocates (diff,adiff,max)
 0          # don't pre-trim at all (everythiing else)

=item diffkbest

 $selector = $dprf->diffkbest();
 $selector = $CLASS_OR_OBJECT->diffkbest($opNameOrAlias);

Returns 'kbest' selector appropriate for L<which()|/which> or L<trim()|/trim> methods.

=item diffop_diff

=item diffop_sum

=item diffop_min

=item diffop_max

=item diffop_avg

=item diffop_havg

=item diffop_gavg

=item diffop_lavg

  $diff = diffop_diff($ascore,$bscore)

Low-level diff-operation subs.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Profile::Diff: Trimming
=pod

=head2 Trimming

=over 4

=item trim

 $dprf = $dprf->trim(%opts);

trims profile and operands; %opts:

 kbest => $kbest,    ##-- retain only $kbest items (by score value)
 kbesta => $kbesta,  ##-- retain only $kbest items (by score absolute value)
 cutoff => $cutoff,  ##-- retain only items with $prf->{$prf->{score}}{$item} >= $cutoff
 keep => $keep,      ##-- retain keys @$keep (ARRAY) or keys(%$keep) (HASH)
 drop => $drop,      ##-- drop keys @$drop (ARRAY) or keys(%$drop) (HASH)

=item pretrim

 ($pa,$pb) = $CLASS_OR_OBJECT->pretrim($pa,$pb,%opts);

Perform pre-trimming on aligned profile pair ($pa,$pb)
in the manner indicated by L<$CLASS_OR_OBJECT-E<gt>diffpretrim($opts{diff})>.


=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Profile::Diff: Stringification
=pod

=head2 Stringification

=over 4

=item stringify

 $dprf = $dprf->stringify( $obj);
 $dprf = $dprf->stringify(\@key2str)
 $dprf = $dprf->stringify(\&key2str)
 $dprf = $dprf->stringify(\%key2str)

stringifies profile and operands (destructive) via $obj-E<gt>i2s($key2), $key2str-E<gt>($i2) or $key2str-E<gt>{$i2}.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Profile::Diff: Binary operations
=pod

=head2 Binary operations

=over 4

=item _add

 $dprf = $dprf->_add($dprf2,%opts);

adds $dprf2 operatnd frequency data to $dprf operands (destructive);
implicitly un-compiles $dprf.
%opts:

 N  => $bool, ##-- whether to add N values (default:true)
 f1 => $bool, ##-- whether to add f1 values (default:true)

=back

=cut

##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2015-2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.14.2 or,
at your option, any later version of Perl 5 you may have available.

=head1 SEE ALSO

L<DiaColloDB::Profile::MultiDiff(3pm)|DiaColloDB::Profile::MultiDiff>,
L<DiaColloDB::Profile(3pm)|DiaColloDB::Profile>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
