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

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

=head1 NAME

DiaColloDB::Profile::MultiDiff - diachronic collocation db, (co-)frequency profile diffs, by date

=cut

##========================================================================
## ALIASES
=pod

=head1 ALIASES

=over 4

=item DiaColloDB::Profile::MultiDiff

=item DiaColloDB::Profile::Multi::Diff

=item DiaColloDB::Profile::Diff::Multi

=back

=cut

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

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Profile::MultiDiff;
 
 ##========================================================================
 ## Constructors etc.
 
 $mpd = CLASS_OR_OBJECT->new(%args);
 
 ##========================================================================
 ## I/O: JSON
 
 $obj = $CLASS_OR_OBJECT->loadJsonData( $data,%opts);
 
 ##========================================================================
 ## I/O: Text
 
 undef = $CLASS_OR_OBJECT->saveTextHeader($fh, hlabel=>$hlabel, titles=>\@titles);
 
 ##========================================================================
 ## I/O: HTML
 
 $bool = $mp->saveHtmlFile($filename_or_handle, %opts);
 
 ##========================================================================
 ## Compilation
 
 @ppairs = $CLASS_OR_OBJECT->align($mp1,$mp2);
 $mpd = $mpd->populate($mp1,$mp2);
 $class = $CLASS_OR_OBJECT->pclass();
 $mp_or_undef = $CLASS_OR_OBJECT->trimPairs(\@pairs, %opts);
 

=cut

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

=head1 DESCRIPTION

DiaColloDB::Profile::MultiDiff is the top-level class
for representing diachronic collocate frequency comparison-profile data
over multiple date-slices
as arising from the comparison of two
L<DiaColloDB::Profile::Multi|DiaColloDB::Profile::Multi> objects.
The API closely mirrors that of the
L<DiaColloDB::Profile::Diff|DiaColloDB::Profile::Diff> class
used to represent slice-wise sub-profiles.

=cut

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

=head2 Globals & Constants

=over 4

=item Variable: @ISA

DiaColloDB::Profile::MultiDiff inherits from
L<DiaColloDB::Profile::Multi|DiaColloDB::Profile::Multi>.

=back

=cut

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

=head3 Constructors etc.

=over 4

=item new

 $mpd = CLASS_OR_OBJECT->new(%args);
 $mpd = CLASS_OR_OBJECT->new($mp1,$mp2,%args);

%args, object structure:

 profiles => \@profiles,   ##-- ($profile, ...) : sub-diffs, with {label} key
 titles   => \@titles,     ##-- item group titles (default:undef: unknown)
 qinfo    => \%qinfo,      ##-- query info (optional; keys prefixed with 'a' or 'b'): see DiaColloDB::Profile::Multi
 populate => $bool,        ##-- auto-populate() if $mp1 and $mp2 are specified? (default=1)

=back

=cut

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

=head3 I/O: JSON

=over 4

=item loadJsonData

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

guts for loadJsonString(), loadJsonFile()

=back

=cut

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

=head3 I/O: Text

=over 4

=item saveTextHeader

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

print column title header for text output.

=back

=cut

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

=head3 I/O: HTML

=over 4

=item saveHtmlFile

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

Save flat HTML table data with rows of the form

 SCOREa SCOREb DIFF LABEL 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)
 qinfo   => $varname,  ##-- include <script> for qinfo data? (default='qinfo')
 verbose => $bool,     ##-- include verbose output? (default=0)
 header  => $bool,     ##-- include header-row? (default=1)
 format  => $fmt,      ##-- printf score formatting (default="%.2f")

=back

=cut

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

=head3 Compilation

=over 4

=item align

  @ppairs = $CLASS_OR_OBJECT->align($mp1,$mp2);
 \@ppairs = $CLASS_OR_OBJECT->align($mp1,$mp2);

=over 4

=item *

aligns subprofile-pairs from $mp1 and $mp2

=item *

$mp1, $mp2 are either:

=over 4

=item HASH-refs

with a 'profiles' key (e.g. DiaColloDB::Profile::Multi objects)

=item ARRAY-refs

of DiaColloDB::Profile-like objects to align

=back

=item *

subprofiles are aligned in stored order

=item *

arguments must be B<EITHER> singletons (1 subprofile) B<OR> of same size;
this lets you compare e.g. a global profile with a sliced one by
something like L<PDL|PDL>'s "implicit threading".

=back

=item populate

 $mpd = $mpd->populate($mp1,$mp2);

populates multi-diff by subtracting $mp2 sub-profile scores from $mp1;
uses $mpd-E<gt>align() to align sub-profiles.

=item pclass

 $class = $CLASS_OR_OBJECT->pclass();

subprofile class for psum().

=item trimPairs

 $mp_or_undef = $CLASS_OR_OBJECT->trimPairs(\@pairs, %opts);

%opts: as for DiaColloDB::Profile::Multi::trim(), including 'global' option

=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::Diff(3pm)|DiaColloDB::Profile::Diff>,
L<DiaColloDB::Profile::Multi(3pm)|DiaColloDB::Profile::Multi>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
