%表題  gtool3/src/sample/gt* の使用法
%
%履歴  92/09/21(numaguti)
%      95/05/29(takepiro)

\chapter{サンプルプログラム}

\section{一般的使用法}

  それぞれ
  \begin{verbatim}
             % gtxxxx [filename...] [options...] 
  \end{verbatim}
  のように実行する.

  各オプションは,  次の様に指定する.
  \begin{verbatim}
      文字型     :  title:Temperature または "title:Averaged Temp."
      文字型以外 :  z=1
      論理型     :  -mono (mono=Tと同じ), #clabel (clabel=Fと同じ)
  \end{verbatim}
  オプション指定は省略できる.

  また, 複数の引数をもつ配列型オプションでは,
  cont=10,50 のように指定する(カンマの前後に空白をいれないこと).
  2つめ以降は省略可である. cont(2)=50 あるいは cont=,50  のような指定も可.

  =, : を含まず, - もしくは \# で始まらないトークン文字列
  (空白もしくは改行にはさまれた文字列)はファイル名とみなされる. 
  ファイル名はオプション列のどこにあってもよい.

  以下, x,y,z軸とはデータの第1,2,3次元をさす.

  環境変数 GTTMPDIR を設定することにより,
  中間ファイル(gtool.out)をカレント以外のディレクトリに作ることができる.


\section{コマンド一覧}

  \subsection{表示・描画}
    \begin{description}
      \item[{\tt gtcont}] 等値線図, トーン
      \item[{\tt gtvect}] ベクトル図
      \item[{\tt gtcurv}] 折れ線図
      \item[{\tt gtmark}] 折れ線図
      \item[{\tt gtscat}] 散布図 
      \item[{\tt gtshow}] キャラクタ表示
    \end{description}

  \subsection{数学}
    \begin{description}
      \item[{\tt gtadd}] 和
      \item[{\tt gtsub}] 差
      \item[{\tt gtmlt}] 積
      \item[{\tt gtdiv}] 商
      \item[{\tt gtsqr}] 平方根
      \item[{\tt gtavr}]  系列平均
      \item[{\tt gtedy}] eddy
      \item[{\tt gtimis}] 欠損値補間
      \item[{\tt gtmask}] マスキング
      \item[{\tt gtfunc}] 関数化前処理
      \item[{\tt gtbpf}] band-pass filter
      \item[{\tt gtxpwspct}] x 軸パワースペクトル
      \item[{\tt gtdump}] 球面調和関数フィルタ
      \item[{\tt gtint1}] int 1 ->gtool3
      \item[{\tt gtint2}] int 2 ->gtool3
    \end{description}

  \subsection{gtool形式データ処理}
    \begin{description}
      \item[{\tt gtaxis}] 軸ファイル抽出
      \item[{\tt gtcrax}] 書式つき->gtool3軸ファイル
      \item[{\tt gtskelton}] gtcreate のskelton
      \item[{\tt gtcon}] スカラー値セット
      \item[{\tt gtset}] 値のセット
      \item[{\tt gtcreate}] 書式つき->gtool3
      \item[{\tt gthead}] ヘッダの変更
      \item[{\tt gtext}] サイズの変更, 次元の追加
      \item[{\tt gtinterp}] 格子変換
      \item[{\tt gtsel}] 選択, フィールド変更
      \item[{\tt gtseq}] 系列をまとめたデータの作成
      \item[{\tt gtcat}] gtool ファイルの結合
      \item[{\tt gthbin}] HITAC VBS 変換
    \end{description}

  \subsection{大気物理}
    \begin{description}
      \item[{\tt gthydro}]  T ->z hydrostatic
      \item[{\tt gtslp}]    海面更正気圧
      \item[{\tt gtstrm}]   質量流線関数
      \item[{\tt gtqsat}]   Qsat
      \item[{\tt gtrelh}]   相対湿度
      \item[{\tt gts2p}]    σ->p
      \item[{\tt gtthet}]   温位<->温度
      \item[{\tt gtthetae}] 相当温位
      \item[{\tt gttv}]     仮温度
    \end{description}


\section{主なコマンドの使用法}

  \subsection{gtcont : 2 次元等値線描画, トーン塗分け}
    \entry{gtcont}

      \begin{verbatim}
        &option
        x=  -1,                      切り出すx格子番号 0 なら, x平均
        y=  -1,                      切り出すy格子番号 0 なら, y平均
        z=  -1,                      切り出すz格子番号 0 なら, z平均
        cont=   -999.000   -999.000, コンター間隔, コンターラベル間隔
        ccycle=  5,                  udpackのicycleと同じ(cont(2)<0のとき)
        range=   -999.000  -999.000, コンターの最小, 最大 
        cidx=  1  3,                 コンターのラインインデックス 0 なら描かない
        clabel=  T,                  コンターラベルを付けるや否や
        tone=   21*-999.000,         トーンの境界値
        pat=  20*-1,                 トーン番号
        map=  0,                     海岸線のラインタイプ 0 なら描かない
        mapidx=  1,                  海岸線のラインインデックス
        lay=  1,                     レイアウト形式番号 ( gglay1 - gglay3 に対応 )
        wsn=  1,                     ワークステーション番号
        mono= F,                     -mono  とするとモノクロ(iws=1)
        print=F,                     -print とするとPS出力(iws=3)
        str=  1,                     (時)系列データの切り出しはじめ
        end=  9999999,               (時)系列データの切り出し終わり
        step= 1,                     (時)系列データの切り出し間隔
        exch=  F,                    X軸とY軸を入れ換える
        tlnum= 6,                    トーンスケールのラベルを打つ数
        softf=F,                     -softf でソフトフィル
        color=0,                     カラー塗りわけの色数
        cpat=18999,-99999,           カラー塗りわけの色の始め, 間隔(トーンパタン番号)
        pixel=-1,-1,                 sgtonf による分割数. 0のときはsgtongを使う.
        item='                ',     表示する item 文字列
        unit='                ',     表示する unit 文字列
        title= '                                ', 表示する title 文字列
        dset='                ',     表示する dset 文字列
        edit='                ',     表示に加える edit 文字列
        ettl='                ',     表示に加える ettl 文字列
        greset=  F                   データ内の描画情報設定(divsなど)を無視するや否や
        &end
      \end{verbatim}

      -999 は不定の意味で, 適当なスケーリングがおこなわれる.
      x=y=z=-1 のときは, z=0 として扱われる.
      ファイル名を指定しない場合は, 'gtool.out' が仮定される.

      例 : 
         \begin{verbatim}
             % gtcont rain cont=200 tone=200,400,800 pat=2999,3999 tilte:Rain
         \end{verbatim}

      以下, オプションの説明は, gtcont と違うもののみ示す. 

  \subsection{gtcurv : 折れ線描画}
    \entry{gtcurv}

      \begin{verbatim}
        &option
        x=  -1,
        y=  -1,
        z=  -1,
        div=   -999.000   -999.000,  値の軸の目盛間隔, ラベル間隔
        range=   -999.000 -999.000, 
        overlay=  1,                 折れ線を重ね合わせる数
        lidx=  2  23*-1,             各折れ線のラインインデックス
        ltype=  1  2  3  4 20*-1,    各折れ線のラインタイプ
        bitlen=   -1.00000,          点線の間隔
        ltitem='ITEM            ',   下部のラインタイトルのラベルとして何を使うか
        lint=  T,                    下部のラインタイトルを描くや否や
        lay=  1,
        wsn=  1,
        tick=  T,                    軸に格子の目盛を付けるやいなや
        attl=  T,                    軸にタイトルを付けるや否や
        str=  1,
        end=  9999999,
        step= 1,
        exch=  F,                    Tなら, 座標をY軸に, データをX軸にとる
        stype=  0,                   値の軸の描画タイプ(logか,上向きか?)
        item='                ',
        unit='                ',
        title='                                ',
        dset='                ',
        edit='                ',
        ettl='                ',
        greset=  F
        &end
      \end{verbatim}

      x=y=z=-1 のときは, x=0,z=0 が仮定される.
      overlay >1 のときは, 順次読み込まれたデータが
      overlay 本重ね合わされて描かれ, そのとき lidx, ltype が順次使われる.

      ファイルは複数(10まで)指定できる.
      そのときは, overlay >= ファイルの数となるよう, overlay が変更される.

      lidx,ltype が <0 の線は, サイクリックな指定として扱う.
      すなわち, ltype = 1,2,3,4 のときには,
      ltype(5)=1,ltype(6)=2,...とみなす.

      例 :
      \begin{verbatim}
          % gtcurv T.case1 T.case2  x=0 z=1 range=250,310 ltitem='DSET' -print
      \end{verbatim}


  \subsection{gtshow : データ・ヘッダのキャラクタ表示}
    \entry{gtshow}

      \begin{verbatim}
        &option
        xstr=  1,                      x軸の表示始め
        xend=  999999,                          終わり
        xstep=  1,                              間隔
        x=  -999,                      x軸の表示点(-999以外の時は上の3つの指定は無視)
        ystr=  1,                      y軸
        yend=  999999,
        ystep=  1,
        y=  -999,
        zstr=  1,                      z軸
        zend=  999999,
        zstep=  1,
        z=  -999,
        tstr=  1,                      時間(系列)軸
        tend=  999999,
        tstep=  1,
        t=  -999,
        head=  F,                      -head でヘッダだけ表示
        all=  F,                       -all  で値が空白のヘッダも表示
        &end
      \end{verbatim}

  \subsection{gtset : データの線形変換}
    \entry{gtset}

      \begin{verbatim}
        &option
        ofs=  0.,                       オフセット値
        fact=    1.00000,               ファクター値  出力は ofs+fact*data
        out='gtool.out'
        apend=F,                        ファイルへの付加出力
        item='                ',
        unit='                ',
        title='                                ',
        dset='                ',
        edit='SET             ',
        ettl='<gtset>         ',
        divs=   -999.,                  描画パラメータ divs
        divl=   -999.,                  描画パラメータ divl
        dmin=   -999.,                  描画パラメータ dmin
        -dmax=   -999.,                  描画パラメータ dmax
        dmiss=  -999.,                  欠損値
        styp=   -999,                   軸の書き方(1:通常, 2:log, 負は下(左)が正)
        time=   -999,                   時刻
        tdur=  -999,                    代表時間
        utim='NUL             ',        時刻単位
        date='NUL             ',        日付
        aitm1='NUL             ',       軸名称1
        aitm2='NUL             ',       軸名称2
        aitm3='NUL             ',       軸名称3
        roptn=  -999.,                  オプションパラメータ
        ioptn=  -999,                   オプションパラメータ
        coptn='                ',       オプションパラメータ
        greset=  F
        &end
      \end{verbatim}

      例 :
      \begin{verbatim}
            % gtset rain fact=0.03456 unit:'mm/day' out:rain.mm
      \end{verbatim}

  \subsection{gtcon : データに一定値をセット}
    \entry{gtcon}

      \begin{verbatim}
        &option
        val=  1.00000,                  値
        out='gtool.out'
        apend=F,
        item='                ',
        unit='                ',
        title='                                ',
        dset='                ',
        edit='CON             ',
        ettl='<gtcon>         ',
        greset=  T
        &end
      \end{verbatim}

      例 :
      \begin{verbatim}
           % gtcon T val=300. out:T.300 title:'reference temp.'
      \end{verbatim}

  \subsection{gtadd : 二つのデータの和}
    \entry{gtadd}

      \begin{verbatim}
        &option
        ofs1=  0.,                  オフセット値(1)
        ofs2=  0.,                  オフセット値(2)
        fact1=    1.00000,          ファクター値(1)
        fact2=    1.00000,          ファクター値(2)
        out='gtool.out          ',
        apend=F,
        item='                ',
        unit='                ',
        title='                                ',
        dset='                ',
        edit='ADD             ',
        ettl='<gtadd>         ',
        greset=  T
        &end
      \end{verbatim}

      出力は (ofs1+fact1*data1) + (ofs2+fact2*data2).
      ファイルが一つのみ指定された時は, もう一方として gtool.out を仮定.

      同様なものとして, gtsub(差), gtmlt(積), gtdiv(商) がある.

      例 :
      \begin{verbatim}
            % gtadd Qrads Qradl out:Qradt item:QRADT title:'Total Radiative Heating'
      \end{verbatim}

  \subsection{gtsel : データの切りだし}
    \entry{gtsel}

      \begin{verbatim}
        &option
        x=  -1,
        y=  -1,
        z=  -1,
        str=  1,
        end=  9999999,
        step= 1,
        sel= '                ',        選択するITEM
        out= 'gtool.out       '         出力ファイル名
        apend=F,
        item='                ',
        unit='                ',
        title='                                ',
        dset='                ',
        edit='                ',
        ettl='                ',
        divs=   -999.,
        divl=   -999.,
        dmin=   -999.,
        dmax=   -999.,
        dmiss=  -999.,
        styp=   -999, 
        roptn=  -999.,
        ioptn=  -999,
        coptn='                ',
        greset=  F, 
        &end
      \end{verbatim}

      x=y=z=-1 の場合はデータ本体には何も加工しない.

      例 :
      \begin{verbatim}
             % gtsel T z=1 str=50 end=100 out:Ta title:'Surface Air Temp.' item:Ta
      \end{verbatim}

  \subsection{gtext : データの範囲切り出し, 拡張}
    \entry{gtext}

      \begin{verbatim}
        &option
        x='                ',          新しいx軸の名称
        y='                ',          新しいy軸の名称
        z='                ',          新しいz軸の名称
        xstr=  0,                      x軸の範囲はじめ
        xend=  0,                      x軸の範囲終わり
        ystr=  0,                      y軸の範囲はじめ
        yend=  0,                      y軸の範囲終わり
        zstr=  0,                      z軸の範囲はじめ
        zend=  0,                      z軸の範囲終わり
        ref='              ',          軸の構成を指定したファイルと同じとする
        out='gtool.out     ',
        apend=F
        &end
      \end{verbatim}

      例 :
      \begin{verbatim}
          % gtsel T zstr=1 zend=5 out:T.bl
          % gtsel Ps z:GSIG16.P out:Ps.3d
          % gtsel Ps ref:T out:Ps.3d  ( Ps を3次元データにする )
      \end{verbatim}

  \subsection{gtavr :  時間(系列)平均}
    \entry{gtavr}

      \begin{verbatim}
        &option
        wright=  F,                     TDUR の重みを付けるや否や
        str=  1,
        end=  9999999,
        step= 1,
        out='gtool.out     '
        apend=F,
        item='                ',
        unit='                ',
        title='                                ',
        dset='                ',
        edit='                ',
        ettl='                ',
        greset=  F
        &end
      \end{verbatim}

      連続するデータ(通常は時系列)の平均を作成する

      例: 
      \begin{verbatim}
            % gtavr rain out:rain.av
      \end{verbatim}

  \subsection{gtseq :  時系列の作成}
    \entry{gtseq}

      \begin{verbatim}
        &option
        out='gtool.out     '
        apend=F,
        axname='               ',             軸の名称
        axitem='               ',             軸目盛の値として使用する欄名
        item='                ',
        unit='                ',
        title='                                ',
        dset='                ',
        edit='                ',
        ettl='                ',
        greset=  F
        &end
      \end{verbatim}

      系列データから, 1次元大きい単一データを作成.
      デフォルトでは時刻が目盛として扱われ,
      時間軸の軸ファイルが出力される.
      領域あふれに注意.

      \begin{verbatim}
          % gtseq rain.y32 out:rain.y32.seq
      \end{verbatim}

\section{コマンドの組み合わせの例}
  
  \begin{itemize}
    \item 例 1 : x-t 図のプロット\\
      \begin{verbatim}
        % gtsel rain y=32 out:rain.y32
        % gtseq rain.y.32 out:rain.y32.seq
        % gtcont rain.y32.seq 
      \end{verbatim}
      これは, 以下のようにもできる.
      \begin{verbatim}
        % gtsel rain y=32 out:rain.y32
        % gtseq rain.y.32 && gtcont
      \end{verbatim}

    \item 例2: 可降水量の算出\\
      \begin{verbatim}
       % gtset Ps fact=10.20 && gtext ref:q out:Ps.3d unit:'kg/m**2'
       % gtmul Ps.3d q && gtsel z=0  out:PW title:'Preciptable Water' item:PW
      \end{verbatim}
  \end{itemize}

% Local Variables: 
% mode: japanese-latex
% TeX-master: "gtool"
% End: