view release on metacpan or  search on metacpan

share/htdocs/help.ttk  view on Meta::CPAN

	      <dt>#FCOEF[<i>C</i>]</dt>
	      <dd>Override the relation-specific frequency scaling coefficient for this query.
	      For formal reasons, the independent frequencies $f1, $f2, and $N are scaled up
	      by a query-specific factor when computing <a href="#scores">score-functions</a> from <a href="#faq-ddc">DDC</a> count data,
	      in order to ensure that the quantities involved can be interpreted as probabilities.
	      The scaling coefficient is usually automatically guessed from the DDC query
	      (e.g. <i>C=2(N+1)</i> for a query of the form <tt class="math">NEAR(* =2,<i>X</i>,<i>N</i>)</tt>,
	      <i>C=N+1</i> for a query of the form <tt class="math">&quot;* =2 #&lt;<i>N</i> <i>X</i>&quot;</tt>,
	      and <i>C=1</i> for <tt class="math">&quot;* =2 #=<i>N</i> <i>X</i>&quot;</tt>).
	      </dd>

	      [% SET l_countkeys = "<i><a href=\"" _ help_url _ "#rule_l_countkeys\">l_countkeys</a></i>"; %]	      
	      <dt>"[" $l_countkeys "]"</dt>
	      <dd>A <a href="#groupby">groupby</a> request can be explicitly wrapped in square brackets
	      to force its interpretation as a <a href="#faq-ddc">DDC</a> $l_countkeys
	      count-key list as opposed to a <a href="#qnative">native groupby request</a>.
	      Potentially useful if you want/need to use alternative target offsets,
	      biliographic metadata fields, or regex transformations on the result tuple attributes.
	      </dd>
	    </dl>
	    <p/>
	  </div>
	  <!--/div.subsection#qddc-->

	  <div class="subsection" id="#qgroupby">
	    <h3><a name="qgroupby">Grouping</a></h3>
	      The <a href="#groupby">groupby</a> parameter can be used to specify which indexed attributes
	      of the candidate collocates are to be projected and to impose optional restrictions on the values
	      of those attributes.  It can be informally understood as a combination of
	      <a href="https://en.wikipedia.org/wiki/SQL#Queries">SQL's</a>
	      <span class="math">GROUP BY</span> and <span class="math">HAVING</span> clauses.
	    <p>
	      The value of the <a href="#groupby">groupby</a> parameter is a comma-separated list of
	      grouping expressions <i>gb_expr</i>:
	      <table class="qsyn"><tbody>
		<tr><td><i>q_groupby</i></td><td>::=</td><td><i>gb_expr</i> ([\s,]+ <i>gb_expr</i>)*</td></tr>
		<tr><td><i>gb_expr</i></td><td>::=</td><td>"\$"? <i>qnc_attr</i></td></tr>
		<tr><td/><td>|</td><td>"\$"? <i>qnc_attr</i> &quot;=&quot; <i>qnc_value</i></td></tr>
	      </tbody></table>
	    </p>
	    <p>
	      Only the attributes <i>qnc_attr</i> explicty specified in the groupby clause are projected from
	      candidate collocates, so that if you request for example <span class="math"><b>groupby:</b> Lemma</span>,
	      then a result-set will include at most one entry for the lemma "flood", even if that lemma occurs in your corpus
	      with multiple part-of-speech tags (e.g. as both a noun and a verb).  If instead you request
	      <span class="math"><b>groupby:</b> Lemma, Pos</span>, then the result-set will treat
	      distinct <i>(Lemma,Pos)</i> pairs as distinct collocate items.
	    </p>
	    <p>
	      If the groupby expression is of the form <span class="math"><i>ATTR</i>=<i>HAVING</i></span>, the <i>HAVING</i>
	      expression (<i>qnc_value</i>) is interpreted as a restriction on the candidate collocates&apos; values for the
	      associated projected attribute <i>ATTR</i> (<i>qnc_attr</i>).
	      For example, <span class="math"><b>groupby:</b> Lemma, Pos=NN</span> will return only those collocates with the
	      PoS-tag "NN" (common noun), and <span class="math"><b>groupby:</b> Lemma, Pos=/^ADJ/</span> will return only
	      collocates whose PoS-tag begins with "ADJ".
	    </p>
	    <p>
	      Note that the <a href="#fmt-bubble">bubble</a> and <a href="#fmt-cloud">cloud</a>
	      formats only display the first projected collocate attribute by default, although the entire
	      projected collocate n-tuple should be available through the "details" popup window
	      display after (double-)clicking on a collocate item in the main display canvas.
	    </p>
	  </div>
	  <!--/div.subsection#qgroupy-->
	  
	  <p/>
	</div>

	<!--=================================================-->
	<div class="section" id="scores">
	  <a name="scores"><h2>Score Functions</h2></a>
          <p>
	    DiaCollo assigns each collocate in a unary profile a real-valued score by means of a user-specified
	    <i>score function</i>. Currently, DiaCollo supports the following score functions:

	    <table class="funcHelp">
	      <tr>
		<th><a name="score-f">f</a></th>
		<td>
		  Raw collocation frequency,
		  <span class="math">$score$subf = $f12</span>.
		  Despite its immediate and intuitive interpretability, ranking by raw frequency alone does not usually provide a very
		  good picture of collocations' &quot;significance&quot;, since high-frequency items
		  such as <a href="//en.wikipedia.org/wiki/Determiner">determiners</a>
		  tend to get ranked highest simply by virtue of their (uninteresting) high overall likelihood,
		  rather than any particular (and potentially interesting) affinity for the search term(s) in question.
		  While the native DiaCollo <a href="#profiles">profile types</a> filter out determiners (and all other function words) by default,
		  the basic problem of uninteresting high-frequency collocates (e.g. &quot;Herr&quot;) remains for raw frequency
		  rankings.
		</td>
		<td><a href="[% root_dir %]images/diacollo-plots/score-f.png"><img class="funcPlot" src="[% root_dir %]images/diacollo-plots/score-f.png"/></a></td>
	      </tr>

	      <tr>
		<th><a name="score-fm">fm</a></th>
		<td>
		  Collocation frequency per million tokens,
		  <span class="math">$score$subfm = 1000000 * $f12 / $N</span>.
		  This is just a linear normalized variant of <a href="#score-f">raw collocation frequency</a>.
		</td>
		<td><a href="[% root_dir %]images/diacollo-plots/score-fm.png"><img class="funcPlot" src="[% root_dir %]images/diacollo-plots/score-fm.png"/></a></td>
	      </tr>

	      <tr>
		<th><a name="score-lf">lf</a></th>
		<td>
		  Collocation log-frequency,
		  <span class="math">$score$sublf = $log2($f12 + $eps)</span>.
		  This is just a logarithmic variant of <a href="#score-f">raw collocation frequency</a>.
		</td>
		<td><a href="[% root_dir %]images/diacollo-plots/score-lf.png"><img class="funcPlot" src="[% root_dir %]images/diacollo-plots/score-lf.png"/></a></td>
	      </tr>

	      <tr>
		<th><a name="score-lfm">lfm</a></th>
		<td>
		  Collocation log-frequency per million,
		  <span class="math">$score$sublfm = $log2(1000000 * ($f12+$eps) / ($N+$eps))</span>.
		  This is just a logarithmic variant of the <a href="#score-fm">normalized collocation frequency</a>.
		</td>

share/htdocs/help.ttk  view on Meta::CPAN

	<!--=================================================-->
	<div class="section" id="formats">
	  <a name="formats"><h2>Output Formats</h2></a>

	  DiaCollo currently supports the following output formats:
	  <dl>
           <dt><a name="fmt-txt">txt</a></dt>
	   <dd>(aliases: text txt t tsv csv)<br/>
	   TAB-separated UTF-8 plain text output,
	   suitable for importing into the spreadsheet application of your choice,
	   e.g. <a href="http://www.gnumeric.org/">Gnumeric</a>
	   or <a href="http://www.libreoffice.org/discover/calc/">LibreOffice Calc</a>.
	   </dd>

           <dt><a name="fmt-json">json</a></dt>
	   <dd>(aliases: json js j)<br/>
	   Native <a href="http://json.org/">JSON</a> format suitable for further automated
	   processing, web-services, etc.
	   </dd>

           <dt><a name="fmt-html">html</a></dt>
	   <dd>(aliases: html htm)<br/>
	   Simple <a href="http://www.w3.org/html/">HTML</a> table format, used for live display in the demo interface.
	   In addition to a tabular display of the <a href="#profiles">profile</a> data,
	   the web front-end HTML display uses <a href="//en.wikipedia.org/wiki/JavaScript">JavaScript</a>
	   to generate hyperlinks to (close approximations of) underlying corpus hits (&quot;KWIC-links&quot;)
	   as well as a color-coded representation
	   of the <a href="#scores">association score</a> (rsp. score-difference for <a href="#prf-diff">diff profiles</a>)
	   associated with each row.
	   Due to the implicit compile-time filtering of <a href="#intro_attrs">native index data</a>
	   by content words and the index parameters $dmax and $cfmin,
	   the number of hits returned by the KWIC-links
	   for native <a href="#prf-collocations">collocation</a> profiles
	   may differ somewhat from the $f12 pair frequency reported in the table.
	   <a href="#prf-ddc">DDC</a> profiles however should report $f12 values identical
	   to the number of corpus hits returned by the associated KWIC-links.
	   </dd>

           <dt><a name="fmt-storable">storable</a></dt>
	   <dd>(aliases: storable sto bin)<br/>
	   Binary format using the Perl <a href="//metacpan.org/pod/Storable">Storable</a> module,
	   suitable for further automated processing with <a href="http://www.perl.org/">Perl</a>.
	   </dd>

           <dt><a name="fmt-gmotion">gmotion</a></dt>
	   <dd>(aliases: gmotion gm)<br/>
	   Online visualization using <a href="http://developers.google.com/chart/interactive/docs/gallery/motionchart">Google Motion Chart</a>.
	   Requires flash player<!--, e.g. <a href="http://get.adobe.com/flashplayer/">Adobe Flash Player</a>-->.
	   For best results, it is recommended that you set the <a href="#global">global</a> parameter to a true value (e.g. 1 (one))
	   when using this output format.
	   See also <a href="http://members.unine.ch/martin.hilpert/motion.html">Martin Hilpert's motion chart resource page</a>
	   for some examples, use cases, and discussion.
	   </dd>

           <dt><a name="fmt-hichart">hichart</a></dt>
	   <dd>(aliases: hc hi chart hichart highchart highcharts)<br/>
	   Online visualization using the <a href="http://www.highcharts.com">Highcharts</a> JavaScript library.
	   For best results, it is recommended that you set the <a href="#global">global</a> parameter to a true value (e.g. 1 (one))
	   when using this output format.
	   Clicking on any data point causes a popup window to be displayed containing
	   hyperlinks to corpus hits for the corresponding collocation pairs as for the <a href="#fmt-html">HTML format</a>,
	   which see with respect to caveats.
	   </dd>

           <dt><a name="fmt-bubble">bubble</a></dt>
	   <dd>(aliases: b bub bubble bubbles)<br/>
	   Online interactive visualization using the <a href="//d3js.org/">D3.js</a> JavaScript library
	   <a href="https://github.com/mbostock/d3/wiki/Force-Layout">force-layout</a>.
	   Collocates are displayed as labelled circles whose radii and color represent the
	   correspondig <a href="#scores">association score</a>.
	   Node colors are the same hues as those used in the <a href="fmt-html">HTML table format</a>,
	   but may appear &quot;washed-out&quot; or &quot;pastel-ized&quot; due to their (partial) transparency.
	   For best results, it is recommended that you set the <a href="#global">global</a> parameter to a true value (e.g. 1 (one))
	   when using this output format.
	   </dd>

           <dt><a name="fmt-cloud">cloud</a></dt>
	   <dd>(aliases: c cl cld cloud)<br/>
	   Online interactive visualization using Jason Davies'
	   <a href="https://github.com/jasondavies/d3-cloud">d3-cloud</a>
	   layout for the
	   <a href="//d3js.org/">D3.js</a> JavaScript visualization library.
	   Collocates are displayed as text labels whose size and color represent the
	   correspondig <a href="#scores">association score</a>.
	   Node colors are the same hues as those used in the <a href="fmt-html">HTML table format</a>,
	   but will appear somewhat darker (&quot;dirty&quot; or &quot;shadowed&quot;) for better
	   legibility on a white background.
	   For best results, it is recommended that you set the <a href="#global">global</a> parameter to a true value (e.g. 1 (one))
	   when using this output format.
	   </dd>

	  </dl>
	  <p/>
	</div>

	<!--=================================================-->
	<div class="section" id="keys">
	  <a name="keys"><h2>Keyboard Bindings</h2></a>
	  The online visualizations based on the <a href="//d3js.org/">D3.js</a> JavaScript library
	  (<a href="#fmt-bubble">bubble</a>, <a href="#fmt-cloud">cloud</a>)
	  support the following keyboard shortcuts whenever the display canvas has the keyboard focus
	  (as indicated by a drop-shadow around the canvas itself as well as the
	  <img src="[% root_dir %]images/keyboard-24px.png" style="height:1em" alt="keyboard icon"/> icon in the header area):
	  <p/>
	  <center>
	    <table class="dbViewTable keysTable">
	      <tr><th>Key(s)</th><th>Action</th></tr>
	      <tr><td>space</td><td>toggle playback animation</td></tr>
	      <tr><td>up-arrow</td><td>increase playback speed (coarse)</td></tr>
	      <tr><td>down-arrow</td><td>decrease playback speed (coarse)</td></tr>
	      <tr><td>shift+up-arrow</td><td>increate playback speed (fine)</td></tr>
	      <tr><td>shift+down-arrow</td><td>decrease playback speed (fine)</td></tr>
	      <tr><td>number 1 or 0</td><td>reset playback speed to default (1&times;)</td></tr>
	      <tr><td>number 2-9</td><td>set playback speed to N &times; default</td></tr>
	      <tr><td>shift+number 2-9</td><td>set playback speed to 1/N &times; default</td></tr>
	      <tr><td>Home</td><td>snap to first epoch</td></tr>
	      <tr><td>End</td><td>snap to final epoch</td></tr>
	      <tr><td>left-arrow</td><td>snap to previous whole epoch</td></tr>
	      <tr><td>right-arrow</td><td>snap to next whole epoch</td></tr>
	      <tr><td>shift+left-arrow</td><td>interpolate backward by one quarter epoch</td></tr>