/ 
DiaColloDB-0.12.020
River stage one • 1 direct dependent • 1 total dependent
/ DiaColloDB::Profile::Multi

NAME

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

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);

@ppairs = $CLASS_OR_OBJECT->align($mp1,$mp2);
@mps    = $CLASS_OR_OBJECT->xfill(\@mps,%opts)
@xkd    = $CLASS_OR_OBJECT->xkeys(\@mps,%opts)

##========================================================================
## Binary operations

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

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 DiaColloDB::Profile class used to represent slice-wise sub-profiles.

Globals & Constants

Variable: @ISA

DiaColloDB::Profile::Multi inherits from DiaColloDB::Persistent.

Constructors etc.

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, ...))
clone
$mp2 = $mp->clone();
$mp2 = $mp->clone($keep_compiled)

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

I/O: JSON

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

guts for loadJsonString(), loadJsonFile()

I/O: Text

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

wraps DiaColloDB::Profile::saveTextHeader().

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()

I/O: HTML

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")

Compilation and Trimming

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

compile all sub-profiles for score-function $func; just calls $prf->compile($func,%opts) for each sub-profile $prf.

uncompile
$mp = $mp->uncompile();

un-compiles all scores for $mp.

pclass
$class = $CLASS_OR_OBJECT->pclass();

sub-profile class for use by psum()

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

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

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

trim sub-profiles; calls $prf->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)
stringify
$mp = $mp->stringify( $obj);
$mp = $mp->stringify(\@key2str)
$mp = $mp->stringify(\&key2str)
$mp = $mp->stringify(\%key2str)

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

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

  • aligns subprofile-pairs from $mp1 and $mp2

  • $mp1, $mp2 are either:

    HASH-refs

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

    ARRAY-refs

    of DiaColloDB::Profile-like objects to align

  • subprofiles are aligned in stored order

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

xfill
 @mps = $CLASS_OR_OBJECT->xfill(\@mps, %opts);
\@mps = $CLASS_OR_OBJECT->xfill(\@mps, %opts);

Ensure sub-profile labels for all MultiProfiles in \@mps are identical by inserting dummy objects for every sub-profile label (slice) represented by any MultiProfile object in the argument array \@mps. After calling this method, any pair of profiles from the array \@mps can safely be passed to align().

Options %opts:

class => $class,  ##-- null profile class; default='DiaColloDB::Profile'
xkeys

Binary operations

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

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

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

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

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

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

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2015-2020 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.

SEE ALSO

DiaColloDB::Profile(3pm), DiaColloDB::Profile::MultiDiff(3pm), DiaColloDB(3pm), perl(1), ...