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

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

=head1 NAME

DiaColloDB::Profile::Multi - diachronic collocation db, (co-)frequency profile, by date-slice

=cut

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

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Profile::Multi;
 
 ##========================================================================
 ## Constructors etc.
 
 $mp = CLASS_OR_OBJECT->new(%args);
 $mp2 = $mp->clone();
 
 ##========================================================================
 ## I/O: JSON
 
 $obj = $CLASS_OR_OBJECT->loadJsonData( $data,%opts);
 
 ##========================================================================
 ## I/O: Text
 
 undef = $CLASS_OR_OBJECT->saveTextHeader($fh, hlabel=>$hlabel, titles=>\@titles);
 $bool = $mp->saveTextFh($fh,%opts);
 
 ##========================================================================
 ## I/O: HTML
 
 $bool = $mp->saveHtmlFile($filename_or_handle, %opts);
 
 ##========================================================================
 ## Compilation and Trimming
 
 $mp_or_undef = $mp->compile($func,%opts);
 $mp = $mp->uncompile();
 $class = $CLASS_OR_OBJECT->pclass();
 $prf = $mp->sumover();
 $mp_or_undef = $mp->trim(%opts);
 $mp = $mp->stringify( $obj);
 
 ##========================================================================
 ## Binary operations
 
 $mp = $mp->_add($mp2,%opts);
 $mp3 = $mp1->add($mp2,%opts);
 $diff = $mp1->diff($mp2);

=cut

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

=head1 DESCRIPTION

DiaColloDB::Profile::Multi is the top-level class
for representing diachronic collocate frequency profile data
over multiple date-slices
as retrieved
e.g. from a native index or DDC back-end.
The API closely mirrors that of the
L<DiaColloDB::Profile|DiaColloDB::Profile> class
used to represent slice-wise sub-profiles.

=cut

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

=head2 Globals & Constants

=over 4

=item Variable: @ISA

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

=back

=cut

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

=head2 Constructors etc.

=over 4

=item new

 $mp = CLASS_OR_OBJECT->new(%args);

%args, object structure:

 profiles => \@profiles,   ##-- ($profile, ...) : sub-profiles, with {label} key
 titles   => \@titles,     ##-- item group titles (default:undef: unknown)
 qinfo    => \%qinfo,      ##-- query info (optional)

%qinfo structure:

 q12 => $q12,              ##-- collocation-pair (w1,w2) count-query string (DDC)
 q1  => $q1,               ##-- collocation-item (w1) count-query string (DDC)
 q2  => $q2,               ##-- collocation-item (w2) count-query string (DDC)
 qN  => $qN,               ##-- total frequency count-query string (DDC)
 fcoef => $fcoef,          ##-- item count coefficient (DDC)
 qtemplate => $qtemplate,  ##-- template query string (replace '__W2.i__' with w2 item property #i (e.g. 0:date, 1:lemma, ...))

=item clone

 $mp2 = $mp->clone();
 $mp2 = $mp->clone($keep_compiled)

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

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Profile::Multi: 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::Multi: I/O: Text
=pod

=head2 I/O: Text

=over 4

=item saveTextHeader

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

wraps DiaColloDB::Profile::saveTextHeader().

=item saveTextFh

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

save flat text representation to a filehandle. %opts:

 header => $bool,     ##-- include header-row? (default=1)
 ...                  ##-- other options are passed to DiaColloDB::Profile::saveTextFh()

=back

=cut

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

=head2 I/O: HTML

=over 4

=item saveHtmlFile

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

save flat HTML table representation to a file.
%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')
 header => $bool,     ##-- include header-row? (default=1)
 format => $fmt,      ##-- printf score formatting (default="%.2f")

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Profile::Multi: Compilation and Trimming
=pod

=head2 Compilation and Trimming

=over 4

=item compile

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

compile all sub-profiles for score-function $func;
just calls C<$prf-E<gt>L<compile|DiaColloDB::Profile/compile>($func,%opts)> for each sub-profile C<$prf>.

=item uncompile

 $mp = $mp->uncompile();

un-compiles all scores for $mp.

=item pclass

 $class = $CLASS_OR_OBJECT->pclass();

sub-profile class for use by psum()

=item sumover

 $prf = $mp->sumover();
 $prf = $CLASS_OR_OBJECT->sumover(\@profiles);

sum of sub-profiles, compiled as for $profiles[0].
used for global trimming.

=item trim

 $mp_or_undef = $mp->trim(%opts);

trim sub-profiles;
calls $prf-E<gt>trim(%opts) for each sub-profile $prf.
%opts: as for DiaColloDB::Profile::trim(), also:

 empty => $bool,   ##-- remove empty sub-profiles? (default=true)
 global => $bool,  ##-- trim sub-profiles globally (default=false)

=item stringify

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

stringifies multi-profile (destructive) via $obj-E<gt>i2s($key2), $key2str-E<gt>($i2) or $key2str-E<gt>{$i2};
calls $prf-E<gt>stringify(...) for each sub-profile $prf.

=back

=cut

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

=head2 Binary operations

=over 4

=item _add

 $mp = $mp->_add($mp2,%opts);

adds $mp2 frequency data to $mp (destructive);
implicitly un-compiles sub-profiles.
%opts: passed to DiaColloDB::Profile::_add().

=item add

 $mp3 = $mp1->add($mp2,%opts);

returns new multi-profile representing sum of $mp1 and $mp2 frequency data.
%opts: passed to Profile::_add().

=item diff

 $diff = $mp1->diff($mp2);

returns score-diff of multi-profiles $mp1 and $mp2; wraps DiaColloDB::Profile::MultiDiff-E<gt>new($mp1,$mp2)

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



=cut
