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

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

=head1 NAME

DiaColloDB::Relation - diachronic collocation db, relation API (abstract & utilities)

=cut

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

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Relation;
 
 ##========================================================================
 ## Constructors etc.
 
 $rel = $CLASS_OR_OBJECT->new(%args);
 
 ##========================================================================
 ## Relation API: create
 
 $rel = $CLASS_OR_OBJECT->create($coldb, $tokdat_file, %opts);
 
 ##========================================================================
 ## Relation API: union
 
 $rel = $CLASS_OR_OBJECT->union($coldb, \@pairs, %opts);
 
 ##========================================================================
 ## Relation API: profile
 
 $mprf = $rel->profile($coldb, %opts);
 
 ##========================================================================
 ## Relation API: comparison (diff)
 
 $mpdiff = $rel->compare($coldb, %opts);
 $mpdiff = $rel->diff($coldb, %opts);
 
 ##========================================================================
 ## Relation API: default
 
 \%slice2prf = $rel->subprofile1(\@tids, \%opts);
 \%slice2prf = $rel->subprofile2(\%slice2prf, %opts)
 
 ##========================================================================
 ## Relation API: default: qinfo()
 
 \%qinfo = $rel->qinfo($coldb, %opts);
 (\@q1strs,\@q2strs,\@qxstrs,\@fstrs) = $rel->qinfoData($coldb,%opts);

=cut

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

=head1 DESCRIPTION

DiaColloDB::Relation
is a base class for low-level indices capable of returning
raw frequency data suitable for constructing
L<DiaColloDB::Profile::Multi|DiaColloDB::Profile::Multi> objects.
In addition to the API specification,
the DiaColloDB::Relation package also provides several common utility
methods used by native DiaColloDB index types.

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation: Globals & Constants
=pod

=head2 Globals & Constants

=over 4

=item Variable: @ISA

DiaColloDB::Relation inherits from
L<DiaColloDB::Persistent|DiaColloDB::Persistent>.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation: Constructors etc.
=pod

=head2 Constructors etc.

=over 4

=item new

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

%args, object structure: nothing here, see subclass documentation for details.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation: Relation API: create
=pod

=head2 Relation API: create

=over 4

=item create

 $rel = $CLASS_OR_OBJECT->create($coldb, $tokdat_file, %opts);

populates relation database from $tokdat_file,
a tt-style text file with lines of the form:

 TID DATE	##-- single token
 "\n"		##-- blank line ~ EOS (hard co-occurrence boundary)

%opts: clobber %$rel

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation: Relation API: union
=pod

=head2 Relation API: union

=over 4

=item union

 $rel = $CLASS_OR_OBJECT->union($coldb, \@pairs, %opts);

=over 4

=item *

merge multiple co-frequency indices into new object

=item *

C<@pairs> : array of pairs C<([$argrel,\@ti2u],...)>
of relation-objects C<$argrel> and tuple-id maps C<\@ti2u> for C<$argrel>

=item *

%opts: clobber %$rel

=item *

should implicitly flush the new relation index

=back

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation: Relation API: profile
=pod

=head2 Relation API: profile

=over 4

=item profile

 $mprf = $rel->profile($coldb, %opts);

Get a relation-specific profile for selected items as a L<DiaColloDB::Profile::Multi|DiaColloDB::Profile::Multi>
object; called by L<DiaColloDB::profile()|DiaColloDB/profile>.

%opts:

 ##-- selection parameters
 query => $query,           ##-- target request ATTR:REQ...
 date  => $date1,           ##-- string or array or range "MIN-MAX" (inclusive) : default=all
 ##
 ##-- aggregation parameters
 slice   => $slice,         ##-- date slice (default=1, 0 for global profile)
 groupby => $groupby,       ##-- string or array "ATTR1[:HAVING1] ...": default=$coldb->attrs; see groupby() method
 ##
 ##-- scoring and trimming parameters
 eps     => $eps,           ##-- smoothing constant (default=0)
 score   => $func,          ##-- scoring function (f|fm|lf|lfm|mi|ld) : default="f"
 kbest   => $k,             ##-- return only $k best collocates per date (slice) : default=-1:all
 cutoff  => $cutoff,        ##-- minimum score
 global  => $bool,          ##-- trim profiles globally (vs. locally for each date-slice?) (default=0)
 ##
 ##-- profiling and debugging parameters
 strings => $bool,          ##-- do/don't stringify (default=do)
 fill    => $bool,          ##-- if true, returned multi-profile will have null profiles inserted for missing slices
 onepass => $bool,          ##-- if true, use fast but incorrect 1-pass method (default=0; Cofreqs subclass only)

The default implementation

=over 4

=item *

parses the request and extracts target tuple-ids,

=item *

calls $rel-E<gt>L<subprofile1|/subprofile1>() to compute slice-wise joint frequency profiles (f12),

=item *

calls $rel-E<gt>L<subprofile2|/subprofile2>() to compute independent collocate frequencies (f2), and finally

=item *

collects the result in a L<DiaColloDB::Profile::Multi|DiaColloDB::Profile::Multi> object.

=back

Default values for C<%opts> should be set by a higher-level call, e.g. L<DiaColloDB::profile|DiaColloDB/profile>().

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation: Relation API: comparison (diff)
=pod

=head2 Relation API: comparison (diff)

=over 4

=item compare

 $mpdiff = $rel->compare($coldb, %opts);

Get a relation-specific comparison profile for selected items as a
L<DiaColloDB::Profile::MultiDiff|DiaColloDB::Profile::MultiDiff>
object.

%opts:

 ##-- selection parameters
 (a|b)?query => $query,       ##-- target query as for parseRequest()
 (a|b)?date  => $date1,       ##-- string or array or range "MIN-MAX" (inclusive) : default=all
 ##
 ##-- aggregation parameters
 groupby      => $groupby,    ##-- string or array "ATTR1[:HAVING1] ...": default=$coldb->attrs; see groupby() method
 (a|b)?slice  => $slice,      ##-- date slice (default=1, 0 for global profile)
 ##
 ##-- scoring and trimming parameters
 eps     => $eps,           ##-- smoothing constant (default=0)
 score   => $func,          ##-- scoring function (f|fm|lf|lfm|mi|ld) : default="f"
 kbest   => $k,             ##-- return only $k best collocates per date (slice) : default=-1:all
 cutoff  => $cutoff,        ##-- minimum score
 global  => $bool,          ##-- trim profiles globally (vs. locally for each date-slice?) (default=0)
 diff    => $diff,          ##-- low-level score-diff operation (diff|adiff|sum|min|max|avg|havg); default='adiff'
 ##
 ##-- profiling and debugging parameters
 strings => $bool,          ##-- do/don't stringify (default=do)
 onepass => $bool,          ##-- if true, use fast but incorrect 1-pass profiling method (default=0)
 ##
 ##-- sublcass abstraction parameters
 _gbparse => $bool,         ##-- if true (default), 'groupby' clause will be parsed only once, using $coldb->groupby() method
 _abkeys  => \@abkeys,      ##-- additional key-suffixes KEY s.t. (KEY=>VAL) gets passed to profile() calls if e.g. (aKEY=>VAL) is in %opts

The default implementation just wraps the L<profile|/profile>() method;
default values for C<%opts> should be set by higher-level call, e.g. L<DiaColloDB::compare()|DiaColloDB/compare>.

=item diff

 $mpdiff = $rel->diff($coldb, %opts);

alias for L<compare|/compare>()

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation: Relation API: default
=pod

=head2 Relation API: default

=over 4

=item subprofile1

 \%slice2prf = $rel->subprofile1(\@tids,\%opts);

Native index API low-level first-pass profiling function for joint frequency acquisition (f12);
default implementation just throws an error.

=item subprofile2

 \%slice2prf = $rel->subprofile2(\%slice2prf, %opts)

Native index API low-level second-pass profiling function for independent frequency acquisition (f2);
default implementation just returns C<\%slice2prf>, which is appropriate for relations which
use a single-pass strategy to populate C<$prf-E<gt>{f2}> in their implementation of
L<subprofile1|/subprofile1>().

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Relation: Relation API: default: qinfo()
=pod

=head2 Relation API: default: qinfo()

=over 4

=item qinfo

 \%qinfo = $rel->qinfo($coldb, %opts);

get query-info hash for profile administrivia (ddc kwic links).
%opts: as for profile(), additionally:

 qreqs => \@areqs,      ##-- as returned by $coldb->parseRequest($opts{query})
 gbreq => \%groupby,    ##-- as returned by $coldb->groupby($opts{groupby})

=item qinfoData

 (\@q1strs,\@q2strs,\@qxstrs,\@fstrs) = $rel->qinfoData($coldb,%opts);

parses @opts{qw(qreqs gbreq)} into conditions on w1, w2 and metadata filters (for ddc linkup).
call this from subclass qinfo() methods.

=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::Persistent(3pm)|DiaColloDB::Persistent>,
L<DiaColloDB::Relation::Cofreqs(3pm)|DiaColloDB::Relation::Cofreqs>,
L<DiaColloDB::Relation::Unigrams(3pm)|DiaColloDB::Relation::Unigrams>,
L<DiaColloDB::Relation::TDF(3pm)|DiaColloDB::Relation::TDF>,
L<DiaColloDB::Relation::DDC(3pm)|DiaColloDB::Relation::DDC>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
