43.28 Key

コマンド set key は描画された曲線の説明や表題を表示することを可能に します。

説明 (key) の内容、すなわち描画される個々のデータ集合や関数につける名 前、およびそれらグラフの曲線とグラフ上の点を表す記号からなるサンプルは、 plot (または splot) コマンドの title, with オプションにより決 定されます。より詳しい情報については、以下参照: plot title (p. ),plot with (p. )。

書式:

     set key {on|off} {default}
             {{inside | outside} | {lmargin | rmargin | tmargin | bmargin}
               | {at <position>}}
             {left | right | center} {top | bottom | center}
             {vertical | horizontal} {Left | Right}
             {{no}reverse} {{no}invert}
             {samplen <sample_length>} {spacing <vertical_spacing>}
             {width <width_increment>}
             {height <height_increment>}
             {{no}autotitles {columnheader}}
             {title "<text>"} {{no}enhanced}
             {{no}box { {linestyle | ls <line_style>}
                        | {linetype | lt <line_type>}
                          {linewidth | lw <line_width>}}}
     unset key
     show key

set key off か unset key によって説明表示なしに描画することができ ます。

キー内の各要素は vertical (縦) または horizontal (横) に従って重ね られます。vertical の場合、key は可能ならば 2,3 個の縦の列を使います。 すなわち、各要素は垂直スペースがなくなるまでは 1 つの列に整列されます が、そこから新しい列が開始されます。horizontal の場合は、key は可能 ならば 2,3 個の横の行を使用します。

デフォルトでは、key はグラフ領域の内側の右上の角に置かれます。キーワー ド left, right, top, bottom, center, inside, outside, lmargin, rmargin, tmargin, bmargin (, above, over, below, under) は、グラフ領域の他の場所への自動的な配置のために使用します。 key の描画をどこに置くかをより詳しく指示するための at < position> も あります。この場合、キーワード left, right, top, bottom, center が同様の基準点合わせの設定の目的で使われます。

配置の仕組みを理解ための最も重要な概念は、グラフ領域、すなわち内か外か ということと、グラフ領域の境界との間の余白 (margin) を考えることです。 グラフ領域に沿って、キーワード left/center/right (l/c/r) と top/center/bottom (t/c/b) は、key をその領域の内側のどこに置くかを制 御します。

モード inside では、key はキーワード left (l), right (r), top (t), bottom (b), center (c) によって以下の図のように描画領域の境界に向かって出力されます:

    t/l   t/c   t/r

    c/l    c    c/r

    b/l   b/c   b/r

モード outside でも上と同様に自動的に配置されますが、グラフ領域の境 界に対して、というよりもむしろ見た目に対して、というべきでしょう。すな わち、グラフの境界は、グラフ領域の外の key の場所を作るために、内側に 移動することになります。しかし、これは他のラベルの邪魔をしますし、もし かしたら出力デバイスによってはエラーを引き起こすかもしれません。key の 出力に合わせてどの描画境界が移動するかは、上に述べた key の位置、およ び重ね上げの方向に依存します。4 方向の中心揃えのオプション (center) に関しては、どの境界が動くのかに関するあいまいさはありませんが、角への 出力のオプションについては、重ね上げ方向が vertical の場合は左または 右の境界が、horizontal の場合は上または下の境界が、それぞれ内側に適 切に移動します。

余白 (margin) の書き方は、重ね上げの方向にかかわない自動的な配置を可能 にしています。lmargin (lm), rmargin (rm), tmargin (tm), bmargin (bm) のうちの一つを、矛盾しない 1 方向のキーワードと組み合わ せて使用した場合、以下の図に示した場所に key が配置されます:

         l/tm  c/tm  r/tm

    t/lm                  t/rm

    c/lm                  c/rm

    b/lm                  b/rm

         l/bm  c/bm  r/bm

キーワード above と over は tmargin と同じ意味です。以前のバージョンとの互換性のために、above と over は l/c/r や重ね上げ方向のキーワードなしで使用すると、center で horizontal を使います。キーワ ード below と under は bmargin と同じ意味です。互換性のために、 below と under は l/c/r や重ね上げ方向のキーワードなしで使用すると center で horizontal を使います。さらに、outside も互換性のため に t/b/c や重ね上げ方向のキーワードがなければ、top, right, vertical (つまり上の t/rm と同じ) を使用します。

説明の位置 (< position> ) は、以前のバージョンと同様単に x,y,z を指定してもいいですが、その最初のサンプル行の座標の座表系を選択するための 5つのキーワード (first, second, graph, screen, character) を 頭につけることもできます。詳細は、以下参照: coordinates (p. )。 < position> が与えられた場合の left, right, top, bottom, center の効果は、label コマンドで配置される文字列の場合と同じように 基準位置の位置合わせに使用されます。すなわち、left は key が < position> の右に置かれて左合わせで出力されます。他の場合も同様です。

説明中のラベル (名前) の行揃えは Left, Right (デフォルト) で指示し ます。ラベル文字列と曲線のサンプルは左右入れ替えることができます (reverse) し、 全体を枠で囲むこともできます (box {...})。その枠の 線は、線種 (linetype), 線幅 (linewidth)、あるいは定義済のラインス タイル (linestyle) を指定することもできます。ただ、全ての出力装置が 線幅の選択をサポートしているとは限らないことに注意してください。

デフォルトでは最初の描画のラベルが説明の一番上に現われ、それに続くラベ ルがその下に並んで行きます。オプション invert は、最初のラベルを説明 の一番下に置き、それに続くラベルをその上に並べて行きます。このオプショ ンは、説明のラベルの縦の並びの順番を、積み上げ形式のヒストグラム (histograms) の箱の順番に合わせるときに便利でしょう。

グラフ曲線のサンプルの線分の長さは samplen で指定できます。その長さ は目盛りの長さと、< sample_length> *(文字幅) の和として計算されます。 sapmlen は、グラフ上の点のサンプルの位置にも (もしサンプル線分自身が 書かれなくても) 影響を与えています。それは、点の記号はサンプル線分の中 央に書かれるためです。

行間の垂直スペースは、spacing で指定できます。その幅は、点のサイズ (pointsize) と垂直な目盛りのサイズと < vertical_spacing> の積になります。 この垂直スペースは、文字の高さよりも小さくはならないことが保証されてい ます。

< width_increment> は、文字列の長さに加えたり減らしたりする幅 (何文字分 か) を表す数値です。これは、説明に外枠を書き、文字列に制御文字を使う場 合にだけ有用でしょう。gnuplot は外枠の幅を計算するときは、ラベル文字 列の文字数を単純に数えるだけなので、それを修正するのに使えます。

< height_increment> は、説明の箱の高さに加えたり減らしたりする高さ (何 文字分か) を表す数値です。これは主に、説明の回りに箱を描く場合のための ものですが、他に、自動的に設定される説明の位置を < height_increment> /2 だけ垂直方向にずらすのにも使えます。

plot や splot で描画される全ての曲線は、デフォルトのオプション autotitles に従って表題 (title) がつけられます。表題の自動生成は、 noautotaitle で抑制できますがその場合、(s)plot ... title ... で明 示的に指定された表題のみが描かれることになります。

set key autotitles columnheader オプションは、gnuplot が configure オプション -enable-datastrings 付きでインストールされた場合に有効です。 このコマンドは各描画データの先頭行の各列のエントリをテキスト文字列と解 釈し、対応する描画グラフのタイトルとして使用します。描画される量が、複 数の列データの関数である場合は、gnuplot はどの列をタイトルの描画に使え ばいいのかわからなくなりますので、そのような場合、plot コマンド上で、 例えば plot "datafile" using (($2+$3)/$4) title 3 with lines のよう に明示的にタイトルの列を指定する必要があります。

表題は説明の上につけることもできます (title "< text> ") - 単一引用符 (') と二重引用符 (") の違いについては、以下参照: syntax (p. )。説明の表題 の行揃えは、グラフの表題の行揃えと同じものが使われます。

明示的に与えられた表題は、出力形式がサポートする拡張文字列属性を使って 出力されます。詳細は、以下参照: enhanced text (p. )。そのデフォルトの挙動 は noenhanced オプションで無効にできます。

set key のデフォルトは、on, right, top, vertical, Right, noreverse, noinvert, samplen 4, spacing 1.25, title "", nobox です。説明の枠の線種はデフォルトではグラフ描画の外枠と同じもの が使われます。set key default とするとデフォルトの設定に戻ります。

説明は、1 行に 1 曲線分ずつの数行のまとまりとして書かれます。各行の右 側には (reverse を使っていれば左側には) その曲線と同じ種類の直線のサ ンプルが引かれ、他の側には plot コマンドから得られる文字列 (title) が置かれます。これらの行は、架空の直線が説明の左側と右側を分けるかのよ うに垂直に整列されます。コマンド set key で指定する座標はこの架空の 線分の上の端の座標です。plot では直線の位置を指定するために x と y だけが使われ、splot では、x, y, z の値全てを使い、グラフを 2 次元面 へ投影するのと同じ方法を使って、架空の直線の 2 次元画面での位置を生成 します。

TeX, PostScript, またはこれらと同等の、整形情報が文字列に埋め込まれる 出力を使う場合は、gnuplot は説明の位置合わせのための文字列の幅を 正しく計算できません。よって説明を左に置く場合は set key left Left reverse という組合せを使うのがいいでしょう。そうす れば説明の枠と枠内のすき間は文字列そのままの幅に合わせられます。

splot で等高線を書く場合、説明には等高線のラベルも表示されます。 これらのラベルの並び具合がうまくいかない、または別な位置に小数点を 置きたい場合はそのラベルの書式を指定できます。詳細は、以下参照:set clabel (p. )。

例:

以下はデフォルトの位置に説明を表示します:

     set key default

以下は説明を表示しなくします:

     unset key

以下はデフォルトの (第一の) 座標系での (2,3.5,2) の位置に説明を表示 します:

     set key at 2,3.5,2

以下は説明をグラフの下に表示します:

     set key below

以下は説明を左下角に表示し、テキストは左に行揃えで、タイトルをつけ、線種 3 の外枠を書きます:

     set key left bottom Left title 'Legend' box 3