こんにちは、道家です。一週間の海外出張から帰ってきました。時差ボケが治ったタイミングでの帰国なのでちょっと辛いです。

さて、皆さん MATLAB を使っていて分からない事があったらどうしてますか？ MATLAB 使いの同僚やお友達に聞きますか？ドキュメンテーションにいきますか？ウェブのフォーラムで質問しますか？

私が MATLAB を使い始めたきっかけは大学院での指導教員が大の MATLAB ユーザーだったからです。お陰で周りには MATLAB の経験者が結構いたので気軽に質問できる環境でした。その中でも、MATLAB のスキルが急激に上達し始めたのは MATLAB のドキュメンテーションの使い方・読み方のコツをつかんだ頃からでした。

MathWorksにはドキュメンテーションを担当している部署があり、彼らは日ごろから開発部門と密に仕事をしています。

私がMATLABを使い始めた 20 年前もそうでしたが、MATLAB ドキュメンテーションはかなり充実していて大体のことはそれだけで解決できます。また、関数の使い方だけではなく、理論や概念的な情報も含まれているので読み物としても活用できます。

ただ、情報量が多いのでドキュメンテーションをうまく活用するためにはコツがあるかと思います。私の経験をもとに紹介したいと思います。

Contents

Help vs Doc

かなり昔から MATLAB を使われている方は >> help plot のように help コマンドで関数の使い方を知ることが多かったかと思います。これは R2010a のバージョンの出力です。

構文の説明や、ちょっとした例も載っています。では、最新バージョン（R2019b）ではどうでしょう。

help plot

plot - 線形 2 次元プロット

    この MATLAB 関数 は、X の値に対応する Y のデータの 2 次元ライン プロットを作成します。

    plot(X,Y)
    plot(X,Y,LineSpec)
    plot(X1,Y1,...,Xn,Yn)
    plot(X1,Y1,LineSpec1,...,Xn,Yn,LineSpecn)
    plot(Y)
    plot(Y,LineSpec)
    plot(___,Name,Value)
    plot(ax,___)
    h = plot(___)

    参考 gca, hold, legend, loglog, plot3, title, xlabel, xlim, ylabel, ylim, 
        yyaxis, Line のプロパティ

    plot のドキュメンテーション
       doc plot

    plot という名前のその他の関数

       alphaShape/plot         lassoblm/plot
       blm/plot                LinearModel/plot
       cfit/plot               localavfit/plot
       cgdatasetnode/plot      localmod/plot
       cgrules/plot            localmulti/plot
       channel/plot            mixconjugateblm/plot
       clustergram/plot        mixsemiconjugateblm/plot
       conjugateblm/plot       mpc/plot
       customblm/plot          ntree/plot
       diffuseblm/plot         phytree/plot
       digraph/plot            polyshape/plot
       drivingScenario/plot    rwvtree/plot
       dspdata/plot            semiconjugateblm/plot
       dtree/plot              sfit/plot
       edwttree/plot           sweepset/plot
       empiricalblm/plot       tall/plot
       fints/plot              timeseries/plot
       frd/plot                wdectree/plot
       graph/plot              wvtree/plot
       HeatMap/plot            xregmodel/plot
       iddata/plot             xregtransient/plot
       idnlarx/plot            xregtwostage/plot
       idnlhw/plot

あらまあ。かなり簡素化されていますね。

実は最近は help よりも doc を推奨しているのです。

doc plot

結構充実しているんです。今は、簡単な構文の確認以外はドキュメンテーションを参照するのをお勧めしています。

では、ドキュメンテーションの使い方のコツについていくつか紹介します。

構文＆説明＆引数の詳細

ドキュメンテーションの関数レファレンスページはほぼすべて同じ構成からなっています。関数名のすぐ下には簡単の説明文の後、構文リストがあります。

構文リストだけではなかなか分からないことがあると思いますので、その場合は気になる構文をクリックします。すると次の “説明” のセクションへ移動します。

さらに、具体的にそれぞれの引数がどのようなものなのかという詳細を知るには、引数のリンクをクリックします。例えば、上図で “LineSpec” をクリックすると、入力引数の詳細を確認できます。

ご覧の通り、各引数がどのようなデータ型を受け付けるかが一目で分かります。

豊富な例

これで、一通り構文の使い方などは分かったかと思います。私はどちらかというと人のコードを見て覚えるタイプです。つまり、構文の説明文を読むより、サンプルコードを見た方が覚えやすいのです。ドキュメンテーションにはたくさんのサンプルコードが含まれています。サンプル集はもちろん、関数レファレンスページにも豊富な例が含まれています。

例えば、構文の説明を読んでいたとしましょう。なんとなく分かったものの、実際に使われている例を見たいとしましょう。説明文の右端を見てみると、 “例” というリンクがあります。

そこをクリックすると、その構文を使った例に飛びます。

出力のグラフもあるので便利ですね！

因みに、右上にある “ライブスクリプトを開く” をクリックすると、例にあるサンプルコードがライブスクリプトとしてエディターで開きます。また、知っておくと便利な機能として、ドキュメンテーションにあるコードを選択して右クリック → “選択を実行” でコマンドウィンドウ上で実行することができます。

ページ概要＆ページ階層の情報

plot 関数は特にそうですが、関数レファレンスページはかなり情報量が多いです。そういう時に役立つのがページの左側にあるページ概要です。

今現在、ページのどこが表示されているかが一目でわかります。また別のセクションに飛ぶこともできます。上図を見ますと、10個以上の例があるのが分かります。

左上には現在のページがドキュメンテーション全体のどこに存在するかという階層情報が表示されています。

これが分かるとなにが嬉しいかというと、例えば、一つ上の階層 “ライン プロット” に移動すると、その他のライン プロットの情報を見ることができます。

関連情報

今回、最後に紹介したいのがページの一番下にある “参考” セクションです。そこには関連する関数やその他の情報が表示されています。

例えば、 plot 関数を使う人は、 title 関数や xlabel 関数のことも知っておくといいですよ、ということです。また、この関数がどのバージョンで出てきたかが分かります。R2006a 以前の情報はないので、それより前に出た関数はすべて “R2006a より前に導入” と表示されますが、最近出た関数はここを見るとわかるので、それ以前の MATLAB では使えない機能だという事が分かります。

まとめ

いかがでしたか。私なりのドキュメンテーションの使い方について紹介させて頂きました。もし、皆さんにもお勧めの使い方がありましたらコメントお願いします！

次回も、MATLAB の使い方（関数とかではなく、環境の使い方）について書いてみたいと思いますのでお楽しみに。