.. _chapter-draw-basic-stimuli:

刺激の位置や提示時間の指定方法を覚えよう
=======================================================================

まずは表示してみよう
------------------------------

本章では、Builderを使って画面に視覚刺激を描画する際に知っておくべき位置や大きさ、色などの指定方法を学びます。
最初の一歩として、三角形と長方形をPCの画面に表示してみましょう。Builderを起動するとウィンドウ内が三つに分割されています。この分割されたひとつひとつの部分をペイン(pane: 窓枠の一区画のこと)と呼びます。左のペインをルーチンペイン、右のペインをコンポーネントペイン、下のペインをフローペインと呼びます(:numref:`fig-pane-layouts`)。コンポーネントとは実験を作るための部品のようなもので、コンポーネントペインにはBuilderで使用できるコンポーネントを表すアイコンが並んでいます。ここから刺激を表示するためのコンポーネントなどを選んでルーチンペインに配置し、フローペインで実験の流れを指定するという手順で実験を作成します。

.. _fig-pane-layouts:

.. figure:: fig02/pane-layouts.png
    :width: 80%

    Builderの3つのペイン。コンポーネントペインから刺激等を選んでルーチンペインに配置し、フローペインでルーチンの実行順序を指定します。

この章では、コンポーネントペインとルーチンペインの使い方を覚えましょう。まず、コンポーネントペインの「刺激」と書いてある部分を何度かクリックしてみてください。コンポーネントのアイコンが現れたり消えたりするはずです。コンポーネントはよく使う「お気に入り」、刺激描画に使う「刺激」、反応計測に使う「反応」、高度な処理を行うための「カスタム」、脳波測定のための「EEG」、視線測定のための「アイトラッキング」、外部機器との入出力に使う「I/O」のカテゴリに分類されており、それぞれカテゴリ名をクリックするとそのカテゴリに含まれるコンポーネントのアイコンが表示されたり隠されたりします。

.. _fig-put-component:

.. figure:: fig02/put-component.png
    :width: 80%

    「刺激」カテゴリを開いてPolygonコンポーネントのアイコン(円、三角、十字が描かれたアイコン)をクリックします。

それでは「刺激」カテゴリに含まれているPolygonコンポーネントを使って実際に刺激をPCの画面に表示してみましょう。Polygonコンポーネントはの右下に示されている楕円、三角、十字が描かれたアイコンです(:numref:`fig-put-component`)。このアイコンをクリックすると、描画する刺激の大きさや色といった特性（プロパティと呼びます）を設定するダイアログが表示されます(:numref:`fig-property-window`)。ダイアログの左上の辺りに「基本」、「レイアウト」、「外観」、…と書かれている点に注目してください。これは「タブ」と呼ばれて、タブをクリックすることによって表示される内容が切り替わります。タブをクリックして表示内容を変更することを「ページを切り替える」などということもあります。

.. _fig-property-window:

.. figure:: fig02/property-window.png
    :width: 80%

    Polygonコンポーネントのプロパティを設定するダイアログ。左上のタブをクリックすることでページを切り替えられます。

まず一切プロパティを変更せずに右下のOKをクリックしてみましょう。すると、ルーチンペインにpolygonコンポーネントのアイコンが表示され、その右側に青い棒が表示されます。これで「コンポーネントをルーチンに配置する」という作業ができました。Builderでは、このようにルーチンにコンポーネントを配置していくことによって刺激を作成します。

.. _fig-component-placed:

.. figure:: fig02/component-placed.png
    :width: 80%

    コンポーネントをルーチンに配置した状態。

では、このPolygonコンポーネントがひとつ配置されただけのシンプルな「実験」を実行してみましょう。
「 :numref:`{number}:{name} <section-how-psychopy-works>` 」で述べた通り、実験を実行するのはBuilderではなくRunnerの役割ですが、実際の実験の作成時には「Builderで少し作業してRunnerで動作を確認する」という作業を繰り返すので、Builderから直接Runnerを呼び出せるようになっています。
Builderのウィンドウ上部に「ファイル(F)」、「編集(E)」といった項目が並んでいる部分を **メニュー** 、そのすぐ下にアイコンが横に並んでいる部分を **リボン** と呼びますが、リボンの中に「実験」、「デスクトップ」と書かれている区画があります。
PsychoPyの初期設定では、 :numref:`fig-run-mode` 上段のように、「実験」の区画の「Pilot」、「実行」と書かれているスイッチが「Pilot」側になっています。本書では以後このスイッチを **Runモードスイッチ** と呼びます。
Runモードスイッチの右側、「デスクトップ」の区画にオーディオアプリの再生ボタンのような、オレンジ色の円の中に三角形がボタンがあります。以後このボタンを **Runボタン** と呼びます。
RunモードスイッチがPilotだとRunボタンはオレンジ色ですが、Runモードスイッチを実行にすると :numref:`fig-run-mode` 下段のようにRunボタンが緑色になることを確認してください。
これらのRunモードの違いを :numref:`tbl-run-modes` に示します。実験を作っている最中にあれこれ試行錯誤するときはPilotモード、実験が問題なく動作する自信がある場合や実験本番の時は実行モードを選択します。

.. _fig-run-mode:

.. figure:: fig02/run-mode.png
    :width: 60%

    RunモードスイッチとRunボタン。上段はRunモードスイッチがPilotになっている状態、下段はRunモードスイッチが実行になっている状態を示しています。Runボタンの色がPilotモードではオレンジ色、実行モードでは緑色となる点に注意してください。

.. tabularcolumns:: |p{8zw}|p{34zw}|

.. _tbl-run-modes:

.. csv-table:: Runモード
    :header: 単位, 説明
    :widths: 36,64

    Pilot, 実験作成中に動作確認のために実行するときに便利なモード。PsychoPyの初期設定では、実験画面がモニター中央にオレンジ色の枠付きで小さく表示されるほか、Runnerに実験の動作に関する情報が詳しく表示される。実験実行中にRunnerのウィンドウを操作することができるので、実験の動作に問題があったときにRunnerから中断することが容易である。
    実行, 実験本番向けのモード。一般的には実験画面がモニター全体に大きく表示され(**フルスクリーン** モードと呼ぶ)、画面描画や音声再生のタイミングができる限り正確になるように動作する。その代わりに、実験実行中にRunnerのウィンドウから中断する操作ができなくなる。

今回は初めての実行ですので、BuilderからRunnerへの連携がわかりやすいようにステップを踏んでいきましょう。Runモードスイッチの右側の、 :numref:`tbl-run-modes` で「Runnerに登録」と示されているボタンをクリックしてください。
このボタンは、BuilderからRunnerへの引継ぎだけをおこなって実行まではおこないません。
クリックすると、ここまで実験を一度も保存していないので、まず実験保存ダイアログが表示されます。ここではchapter2.psyexpという名前で保存しておきます。
拡張子が.psyexpのファイルには、Builderで作成した実験の情報が保存されています。以後、このファイルのことを **psyexpファイル** と呼びます。
psyexpファイルの他にもBuilderが作成するファイルがありますが、それらについては「 :numref:`{number}:{name} <section-builder-output-files>` 」で解説します。

実験を保存すると、自動的にRunnerのウィンドウ( :numref:`fig-runner-basic` )が表示されます。Runnerのウィンドウは大きく左右に分割されていて、左側にはBuilderから引き継いだ実験が登録されます(Coderや他のエディタを使って自分で作成したスクリプトも登録できますがここでは省略します)。先ほど保存したchapter2.psyexpが登録されていることを確認してください。
左側は実験が適切に動作しているかを知るための様々な情報( **ログ** と呼びます)が表示されます。
ウィンドウ上部のリボンには、BuilderにもあったRunモードスイッチやRunボタンがありますが、注目していただきたいのはRunボタンの隣のボタンです。これは実験実行中に何か問題が生じた時に強制的に終了させるためのボタン(中断ボタン)です。
それでは、Runnerウィンドウ左側の実験一覧に登録されているchapter2.psyexpを選択(マウスでクリックすれば選択できます)した状態でRunボタンをクリックしてください。

.. _fig-runner-basic:

.. figure:: fig02/runner-basic.png
    :width: 80%

    Runnerのウィンドウ。左側は登録済みの実験のリスト、右側は実験実行時のログが表示されます。ウィンドウ上部のリボンにはBuilderと同じRunモードスイッチ、Runボタンに加えて中断ボタンがあります。

Runボタンをクリックしてしばらく待つと、 :numref:`fig-run-expinfo` のような小さなダイアログが表示されます。これを **実験情報ダイアログ** と呼びます。少し古めのPCやノートPCを電源につながず実行している場合などには実験ダイアログが表示されるまで少し時間がかかりますのでご注意ください。同時に、Runnerの中断ボタンが有効になります。中断ボタンをクリックすると実行が中断されます。

.. _fig-run-expinfo:

.. figure:: fig02/run-expinfo.png
    :width: 80%

    実行ボタンをクリックした後、少し待つと実験情報ダイアログが表示されます。同時に実験中断ボタンが有効になります。


実験情報ダイアログは、実験参加者の氏名や実験の条件など、実験の実行に必要な情報や、データと一緒に保存しておきたい情報などを入力するためのものです。どのような情報を入力できるようにするかはもちろん設定できるのですが、ここではまだ何も設定していないので標準で設定されているsessionとparticipantという項目が表示されています。この章では実験情報ダイアログを利用するところまで進みませんので、とりあえず変更せずにOKをクリックしてください。
すると :numref:`fig-white-triangle` 左のように画面中央に灰色の長方形が表示され、その中に白い文字で Attempting to measure frame rate of screen, please wait... と表示されます。
数秒後、 :numref:`fig-white-triangle` 右のように画面中央に白い三角形が1秒間表示されます。時間が短くてわかりにくいですが、灰色の領域の縁にオレンジ色の枠線がつき、左下に PILOTING: Switch to run mode before testing. と書かれていることにも注目してください。
三角形が出現してから1秒後に、元のRunnerのウィンドウが表示されている画面に戻ります。
なお、環境によっては白い三角形が表示される瞬間に、Runnerのウィンドウが手前に表示されてしまって白い三角形が描画されたのがわからないことがあります(筆者が動作確認した限り、「 :numref:`{number}:{name} <subsection-input>` 」で触れる **[キーボードバックエンド]** でioHubを選択していると起こりやすい)。その場合はRunnerのウィンドウを左右にすこし避けておいてもう一度Runボタンをクリックして実行してみてください。

.. _fig-white-triangle:

.. figure:: fig02/white-triangle.png
    :width: 80%

    実験情報ダイアログのOKボタンをクリックすると、左図のように灰色の領域が表示されその中に白いメッセージが表示されます。数秒後、右図のように灰色の領域の中央に白い三角形が表示されます。

Pilotモードできちんと動作することが確認できたら、RunnerのRunモードスイッチを実行に切り替えて(Runボタンが緑色になるのを確認してください)、Runボタンをクリックして実行してみましょう。
同じように実験情報ダイアログが表示され、OKボタンをクリックしたら今度は画面全体が灰色になり、 Attempting to measure frame rate of screen, please wait... のメッセージの後に白い三角形が表示されるはずです。これがフルスクリーンモードです。
フルスクリーンモード担っている間はRunnerのウィンドウが見えないため、Runnerの中断ボタンをクリックできないということがおわかりいただけるかと思います。
あとは、Builderのウィンドウに戻って、BuilderのRunボタンからも同様に実験を実行できることを確認しておいてください。
これで私たちが作った「最初の実験」が無事に終了しました。

チェックリスト
   - ルーチンペインにコンポーネントを配置できる。
   - Pilotモードと実行モードを切り替えできる。Runボタンの色の違いから現在どちらのモードなのか判断できる。
   - Builderの実験ファイルの拡張子を答えられる。
   - 作成した実験を実行できる。


コンポーネントの設定変更と削除の操作を覚えよう
----------------------------------------------------

続いて、コンポーネントの設定を変更してみましょう。
Builderのウィンドウに戻って、ルーチンペインに表示されているコンポーネントのアイコンにマウスカーソルを動かして左ボタンをクリックしてみてください。すると先ほどコンポーネントを配置した時に表示されたプロパティ設定ダイアログが再び表示されます。ここで :numref:`fig-edit-properties` のようにダイアログの「基本」タブにある「形状」を長方形に変更し、「外観」タブの「塗りつぶしの色」という項目にblackと入力して、ダイアログ右下のOKをクリックしてみましょう(blackと入力する時には **日本語入力をOFF** にしてください)。これで形状が長方形、刺激の塗りつぶし色が黒色に設定されました。もう一度実験を実行すると、今度はのように黒色に塗りつぶされた正方形が表示されるはずです。

.. _fig-edit-properties:

.. figure:: fig02/edit-properties.png
    :width: 80%

    「形状」を長方形、「塗りつぶしの色」をblackに設定して実行してみましょう。


このように、配置済みコンポーネントのプロパティは何度も設定し直すことができます。この操作は今後繰り返しおこなうことになるので覚えておきましょう。本書ではこれ以後、プロパティ名を **[塗りつぶしの色]** のように **[ ]** で囲って表記します。

次の話題に進む前にもうひとつ覚えておきたい基本操作は、ルーチンペインに設置したコンポーネントの削除です。ルーチンペインに配置されたPolygonコンポーネントの上にマウスカーソルを動かして今度は右クリックしてみてください。:numref:`fig-remove-component` のようにポップアップメニューが表示されますので、「削除」を選択してください。コンポーネントがルーチンペインから取り除かれます。「削除」の項目に「(polygon)」とついているのは、削除しようとしているコンポーネントの名前を表しています。次節以降、ひとつのルーチンに複数のコンポーネントを配置しますが、そのような場合にどのコンポーネントを削除しようとしているのか一目でわかるように表示されています。

.. _fig-remove-component:

.. figure:: fig02/remove-component.png
    :width: 60%

    ルーチンペインのコンポーネントのアイコン上でマウスを右クリックするとメニューが表示されます。「削除」を選択するとコンポーネントを削除できます。

さて、これでコンポーネントをルーチンペインに配置し、プロパティを編集し、不必要なコンポーネントを削除し、実験を実行することができるようになりました。続いてコンポーネントのプロパティを編集して刺激の色や大きさを調節する方法を学びましょう。

チェックリスト
   - Polygonコンポーネントを用いて三角形と長方形を表示できる。
   - コンポーネントをルーチンから削除することができる。
   - 本書で項目名を [ ] で囲んだ表記が何を表しているかを説明できる。


.. _section-position-size:

位置と大きさを指定しよう
------------------------------------

再びPolygonコンポーネントを用いて、PsychoPyにおける視覚刺激の位置と大きさ、向きを指定する方法を習得しましょう。ルーチンペインにPolygonコンポーネントをひとつ配置して、 **[形状]** を長方形にしてください。

Polygonコンポーネントのプロパティ設定ダイアログの「レイアウト」タブを表示すると、 **[位置 [x, y] $]** 、 **[サイズ [w, h] $]** という項目があります。それぞれ刺激の位置と大きさの指定に対応しています。これらの項目に1.0とか150とかいった値を入力することによって位置や大きさを指定するのですが、実際にこういった値を入力した時にどのような結果が得られるかを理解するためには、PsychoPyにおける位置と大きさの単位を理解する必要があります。

.. _fig-basic-units:

.. figure:: fig02/basic-units.png
    :width: 80%
    
    PsychoPyで使用できる単位。

位置や大きさの単位は、同じタブにある **[空間の単位]** という項目で指定します。 :numref:`tbl-psychopy-units` にPsychoPyで使用できる単位を示します。スクリーン上の画素(ピクセル)で指定するpix、センチメートルで指定するcm、スクリーンの大きさに対する比で指定するnormとheight、視角で指定するdeg, degFlat, degFlatPosがあります。これらの単位の関係を、スクリーンの解像度が横1920ピクセル、縦1080ピクセル、寸法が幅51.0cm、高さ28.6cmのモニターを例として示したのが :numref:`fig-basic-units` です。いずれの単位でもスクリーンの中心は常に原点(0, 0)で、水平方向は右、垂直方向は上が正の方向です。スクリーンの右上の位置をpixで示す場合、スクリーンの横方向に1920ピクセルあるのですからスクリーン中心を基準にすればスクリーンの左端は960ピクセル(1920ピクセルの半分)進まなければいけません。同様に垂直方向に1080ピクセルありますからスクリーンの上端は中心から540ピクセル進まなければいけません。ですから、スクリーン右上の座標は(960, 540)です。スクリーン左下の座標は水平垂直共に負の方向に進まないといけないので、(-960, -540)です(厳密にな議論は「 :numref:`{number}:{name} <topic-coordinate-range>` 」参照)。単位がcmの場合は同様の計算でスクリーン右上が(25.5, 14.3)、左下が(-25.5, -14.3)です。

normとheightは、Builderで実験を作成するときの（設定変更してい場合の）単位の初期値として使われる重要な単位です。これらの単位はスクリーンの解像度に対する比で位置や長さを指定します。normではスクリーンの解像度に関わらず必ず右上の座標は(1.0, 1.0)、左下の座標は(-1.0, -1.0)になります。一般的にPCのモニターは水平方向の方が解像度は高いので、垂直方向の1.0よりも水平方向の1.0の方が画面上の長さは長くなります。そのため、正方形や円を表示したり図形を回転したりするときに注意が必要です（「 :numref:`{number}:{name} <section-rotate-stimulus>` 」参照）。前節で「設定によっては三角形が横長になる」、「正方形ではなく長方形が描かれる」と書いたのは、単位がnormの場合に起こる現象です。PsychoPy 3.0.3より前のバージョンでは、このnormが単位の初期値でした。

一方、PsychoPy 3.0.3から単位の初期値となったheightは、スクリーンの高さが1.0になるように水平方向の幅を決めます。 :numref:`fig-basic-units` の例の場合、垂直方向1080ピクセルに対して水平方向に1920ピクセルありますので、スクリーンの幅は1920÷1080≒1.78です。スクリーンの幅が1.78、高さが1.0なのですから、スクリーンの右上と左下の座標は(0.89, 0.5)と(-0.89, -0.5)になることに注意してください。normと比べて正方形を表示したり図形を回転させたりするのが容易なのが特徴ですが、縦横比の異なるモニター間で右上や左下の座標が異なる点が面倒です。normやheightには、実験用と学会発表用で異なる解像度のモニターを使っている時に、学会発表用に実験プログラムを書きなおさなくてもモニターの解像度に合わせて刺激を調整できるというメリットがあります。

残るはdeg, degFlat, degFlatPosですが、まずdegから説明します。 :numref:`fig-basic-units` 下の図のように被験者が60cm離れた位置にあるスクリーンの中心に真っ直ぐ視線を向けているとします。眼から視線を向けている対象に引いた直線を視軸と呼びます。さて、スクリーン中心から右へ15.4cmの位置に刺激があるとして、眼からこの刺激の位置まで引いた直線と視軸が成す角度を考えましょう。三角関数を思い出していただければ15.4cmを観察距離60cmで割った値の正接(tan)を求めれば角度が得られます。この角度の単位はラジアンなので分かりやすいように180/πを掛けて単位を度(deg)にすると15.0degです。この角度を視角と呼びます。視覚を研究する時には、刺激がスクリーン上で中心から何cm離れていたかよりも、網膜の中心から何deg離れていたかの方が重要な意味を持つことがよくあるので、単位として視角が頻繁に用いられます。PsychoPyでは、あらかじめスクリーンの寸法と観察距離を登録しておくことで、degを単位として刺激の位置や大きさを指定できます。寸法と観察距離の登録方法はこの章の「 :numref:`{number}:{name} <section-change-experiment-settings>` 」で触れますので、ひとまずは「degという単位が使える」ということを覚えておいてください。なお、PsychoPyのdegの計算は恐らく実行速度を速めるために近似的な方法を用いています。より正確な値を必要とする人のために用意されているのがdegFlat, degFlatPosという単位です。詳しくは「 :numref:`{number}:{name} <topic-visual-angle>` 」をご覧ください。

.. tabularcolumns:: |p{8zw}|p{34zw}|

.. _tbl-psychopy-units:

.. csv-table:: PsychoPyで使用できる位置と大きさの単位
    :header: 単位, 説明
    :widths: 36,64

    pix,              モニター上の画素に対応します。例えば100pixであればモニターの100画素分に対応します。
    cm,               モニター上での1cmに対応します。使用しているモニターの画面の寸法と縦横の画素数をMonitor Centerに登録しておく必要があります。
    deg,              視角1度に対応します。例えば2.5degであれば視角2.5度に対応します。使用しているモニターの画面の寸法と縦横の画素数、モニターと参加者の距離をMonitor Centerに登録しておく必要があります。
    norm,             モニターの中心から上下左右の端までの距離が1.0となるように正規化された単位です。一般的にPC用のモニターは縦方向より横方向の方が長いので、normの単位で幅と高さに同じ値を指定すると横長の長方形になります。
    height,           モニターの上端から下端の距離が1.0になるように正規化された単位です。normと異なり、一般的なPC用モニターで幅と高さに同じ値を指定するとほぼ正方形となります。「ほぼ」というのはモニターによっては画素の縦横の長さがわずかに異なる場合があり、そのようなモニターでは正確に正方形にならないからです。
    degFlat,          degと同様ですが、degよりも正確に計算します(「:numref:`{number}:{name} <topic-visual-angle>` 」参照)。
    degFlatPos,       degと同様ですが、degよりも正確に計算します(「:numref:`{number}:{name} <topic-visual-angle>` 」参照)。
    実験の設定に従う, 実験設定ダイアログで指定された単位に従います。実験設定ダイアログで「PsychoPyの設定に従う」に設定されている場合はPsychoPy設定ダイアログの **[単位]** に従います。

では、実際に刺激の大きさを変化させてみましょう。Polygonコンポーネントをひとつルーチンペインに置いて、 :numref:`fig-edit-size` 上のように **[サイズ [w, h] $]** の値を(0.2, 0.1)にしてください。数値の両脇の括弧やカンマを忘れずに入力してください（ **括弧は丸括弧でも角括弧でも前後で一致していれば構いません** ）。 **[サイズ [w, h] $]** のwとhはそれぞれwidthとheightですから、(0.2, 0.1)と入力すれば、スクリーンの高さを基準として幅0.2、高さ0.1の長方形を表示するように指定したことになります。入力を終えたら実験を実行すると、 :numref:`fig-edit-size` 下のようにスクリーン中央に横幅が高さの2倍の長方形が表示されるはずです。三角形が表示された人は **[形状]** を長方形にし忘れているので変更してください。ものすごく大きな長方形が表示されたり、何も表示されなかったりした場合は、標準の単位の設定が何らかの理由でheightになっていない可能性が考えられます(研究室の共用コンピュータを使用していて設定が変更されている場合など)。その場合は **[空間の単位]** をheightに変更してみてください。毎回手作業で変更するのが面倒な場合は「 :numref:`{number}:{name} <subsection-screen-settings>` 」を参考にPsychoPyの設定を変更してください。

.. _fig-edit-size:

.. figure:: fig02/edit-size.png
    :width: 80%
    
    サイズの設定。Polygonコンポーネントの形状を長方形にして、横幅0.2、高さ0.1に設定しています。

使用している環境によっては、 **[サイズ [w, h] $]** や **[位置 [x, y] $]** などに入力されたカンマ( , )と小数点( . )が非常に区別しにくい場合があります。フォントの設定を変更すると改善される場合がありますので、気になる方は「 :numref:`{number}:{name} <topic-change-font>` 」をご覧ください。

また、使用しているPCのグラフィック機能によっては長方形の対角線上の灰色の線が見える事があります(:numref:`fig-polygon-interpolate` )。PsychoPyでは長方形を表示する時に実際には二つの直角三角形を並べているのですが、うまく並べられずに隙間ができてしまった時に生じる現象です。灰色の線は隙間から灰色の背景が見えてしまっているために生じています。多くの場合、Polygonコンポーネントのプロパティ設定ダイアログの「テクスチャ」タブにある **[補間]** というプロパティを変更するとこの問題は解消されます。

.. _fig-polygon-interpolate:

.. figure:: fig02/polygon-interpolate.png
    :width: 80%
    
    Polygonコンポーネントで長方形を表示すると細い線が見える事があります。「テクスチャ」タブの **[補間]** を変更すると多くの場合問題が解消されます。

続いて刺激の位置を変更してみましょう。Builderの画面に戻ったら、先ほどのPolygonコンポーネントのプロパティ設定ダイアログを開いて、 :numref:`fig-set-position` 上のように **[位置 [x, y] $]** に(0.1, 0)と入力して実行してみましょう。 **[位置 [x, y] $]** のxとyはそれぞれ水平(X軸)方向、垂直(Y軸)方向を表していますので、右と上が正の方向であることに注意すれば、(0.1, 0)はスクリーン中央から右へ0.1移動した位置を示しているはずです。実際に実行して確認すると、 :numref:`fig-set-position` 下のように確かにスクリーン中央より右寄りに長方形が表示されます。

.. _fig-set-position:

.. figure:: fig02/set-position.png
    :width: 80%
    
    **[位置 [x, y] $]** に(0.1, 0)を設定すると長方形が右寄りに表示されます。

でも、 :numref:`fig-set-position` を見ただけでは長方形が右寄りに表示されていることがわかりますが、目視しただけでは本当に0.1右に寄っているのかの判断は困難です。そもそも、この(0.1, 0)という位置指定は長方形のどこを指しているのでしょうか？ 答えは「レイアウト」タブの **[位置揃え]** にあります。標準では **位置揃え** が「中央」に設定されているので、(0.1, 0)は長方形の中央の座標に対応します。そうすると、長方形の左下の頂点は中央の座標(0.1, 0)から左へ横幅の半分、下へ高さの半分だけ移動した位置にあるはずです。確認するために、ルーチンペインにもうひとつPolygonコンポーネントを配置してみましょう。

.. _fig-put-multiple-components:

.. figure:: fig02/put-multiple-components.png
    :width: 80%
    
    Polygonコンポーネントを追加して位置と大きさを設定します。コンポーネントが追加されると下の図のようにルーチンペイン上に複数のアイコンが並びます。

ルーチンにもうひとつPolygonコンポーネントを配置するには、最初にPolygonコンポーネントを配置した時と同様に、コンポーネントペインのPolygonコンポーネントのアイコンをクリックします。そうするとやはり最初のコンポーネントを配置した時と同様にプロパティ設定ダイアログが表示されます。今回は、Polygonコンポーネントを使用する練習も兼ねて三角形を描画させてみましょう。まず「基本」タブの **形状** が三角形になっていることを確認し、「レイアウト」タブへ移動して :numref:`fig-put-multiple-components` のように **[サイズ [w, h] $]** に(0.2, 0.2)、 **[位置 [x, y] $]** に(0, -0.05)と同じ値を入力してください。そして、 **[位置揃え]** を「中央上」にしましょう。入力ができたら実験を実行してください。 :numref:`fig-put-multiple-components` 左のように、三角形の上側の頂点が長方形の左下の頂点と一致するはずです。

なぜこのようになるのかを解説したのが :numref:`fig-put-multiple-components` の右です。先ほど述べたように、長方形の左下の頂点の座標は(0, -0.05)になるはずです。一方、三角形は :numref:`fig-put-multiple-components` 左の結果からおわかりのように底辺が水平な二等辺三角形として描かれます。三角形の **[位置 [x, y] $]** を(0.-0.05)にしたうえで **[位置揃え]** を中央上にしましたので、三角形の上の頂点が(0.-0.05)の位置になるように描かれます。この座標は長方形の左下の頂点の座標と一致しているので、 :numref:`fig-put-multiple-components` 左のような出力が得られるというわけです。

.. _fig-position-triangle-rectangle:

.. figure:: fig02/position-triangle-rectangle.png
    :width: 80%
    
    三角形と長方形のPolygonを描画した結果。長方形の左下の頂点と三角形の上の頂点の座標が一致することがわかります。

ここで :numref:`fig-put-multiple-components` 右に示されてる三角形が正三角形よりやや縦長である点に注意してください。高さ0.2の正三角形の幅は :math:`0.2/\sqrt{3} \times 2` = 約0.2309ですから、正三角形を表示するには **[サイズ [w, h] $]** を(0.2309, 0.2)としなければいけません。 **[位置揃え]** を中央にした時に **[位置 [x, y] $]** が指し示す位置が三角形の重心と一致しない事にも注意する必要があります。

なお、「 **[位置揃え]** が中央の時に **[位置 [x, y] $]** は 図形の左右端の中点、上下端の中点に対応する」という原則は本書で取り上げる他の視覚刺激に対しても成り立つのですが、Polygonコンポーネントで五角形以上の正多角形を描画した時のみは例外的に、 **[位置 [x, y] $]** が図形の左右端の中点、上下端の中点ではなく、外接する楕円の中心の座標に一致します。

.. _fig-regular-polygon-position:

.. figure:: fig02/regular-polygon-position.png
    :width: 80%
    
    正五角形を描くための設定(左)と正五角形を描いた結果(右)。 比較のために同じ **[サイズ [w, h] $]** で描いた三角形を並べて描画しています。

試しに :numref:`fig-regular-polygon-position` 左のようにPolygonコンポーネントの **[形状]** を正多角形にしてください。すると **[頂点数]** の値が変更できるようになりますので5を指定してみましょう。指定を終えて実行すると画面上に正五角形が描かれますが、三角形や長方形を描いた時よりやや小さく描かれるはずです。 :numref:`fig-regular-polygon-position` 右には **[サイズ [w, h] $]** が(0.1, 0.1)の五角形と三角形を描画した結果を示していますが、底辺の位置が揃っていないことがわかります。

本節ではPsychoPyの標準の単位であるheightの場合を例に解説してきましたが、他の単位でも考え方は同じです。単位はそれぞれのコンポーネントで独立して設定できるので、ひとつのポリゴンはheight、もうひとつのポリゴンはdegを使うといったことも可能です。位置と大きさの指定についての解説はこのくらいにしておいて、次は図形を回転させてみましょう。

チェックリスト
   - PsychoPyにおける座標系の原点と水平、垂直軸の正の方向を答えられる。
   - heightが単位の状態で **[位置 [x, y] $]** 、 **[サイズ [w, h] $]** 、 **[位置揃え]** を使って任意の大きさの多角形を任意の位置に表示させることができる。
   - Polygonコンポーネントで正五角形以上の正多角形を描画できる。
   - Polygonコンポーネントで **[頂点数]** が5以上の時に **[位置 [x, y] $]** が例外的に図形のどの位置に対応するかを答えることができる。
   - cm、deg、norm、heightという単位を説明できる。
   - 複数のコンポーネントをルーチンペインに配置できる。
   - **[位置揃え]** の働きを説明できる。

.. _section-rotate-stimulus:

刺激を回転させよう
--------------------------------

再びPolygonコンポーネントのプロパティ設定ダイアログを開いてください。 **[位置 [x, y] $]** の上に **[回転角度 $]** という項目があります。この項目に回転量を数値で入力することによって、刺激を回転させることができます。入力する数値の単位は「度」で、時計回りが正の回転方向です。つまり、 **[回転角度 $]** を30に設定すると時計回りに45度、90に設定すると90度回転します。回転の中心は **[位置 [x, y] $]** によって指定されている位置ですが、 **[位置揃え]** の設定によって結果が異なることに注意してください。 :numref:`fig-set-orientation` に縦長の三角形を **[位置揃え]** 「中央」と「中央上」に設定して45度、90度回転した結果を示します。なお、回転角度として負の値を設定すると反時計回りに回転します。

.. _fig-set-orientation:

.. figure:: fig02/set-orientation.png
    :width: 80%

    **[回転角度 $]** の指定による図形の回転。 **[位置揃え]** による違いに注意。

刺激の回転について学んだついでに、先ほど「normを単位にすると図形の回転が難しい」と述べた点について確認しておきましょう。Polygonコンポーネントをルーチンペインにひとつ配置して、 **[空間の単位]** をnormに、 **[サイズ [w, h] $]** を[0.5, 0.5]にしてください。そして、 **[回転角度 $]** に0を入力した場合と30した場合の結果を比較してみてください。他のコンポーネントを置いていても構いませんが、他のコンポーネントと重なるとわかりにくいので削除しておいた方がよいと思います。実行すると、 :numref:`fig-norm-orientation` 左のように **[回転角度 $]** が0であれば長方形が表示され、30であれば傾いた平行四辺形が表示されたはずです。これは、normを単位に使用した時に、スクリーンの右上の座標が(1, 1)、左下の座標が(-1, -1)になるように変換を行うために生じる現象です。通常、PCに接続されているモニターのスクリーンは横に長いので、変換の際に横方向に引き伸ばされてしまうのです。そのため、水平軸や垂直軸に平行な辺しか含まない図形はnormを使用しても単に横長に見えるだけですが、平行ではない辺を含む図形では辺が交わる角度が変わってしまうのです。横長のスクリーンを使用時にnormを使う限り、この問題は回避できません。heightを使った方が良いでしょう。

さて、以上で図形の大きさ、位置、回転方向の指定方法の解説が終わりました。これらの設定に用いるプロパティ、 **[サイズ [w, h] $]** 、  **[位置 [x, y] $]**、**[回転角度 $]** 、 **[空間の単位]** の使い方は、視覚刺激を表示するコンポーネントでほぼ共通していますので、使い方をしっかりマスターしておきましょう。

.. _fig-norm-orientation:

.. figure:: fig02/norm-orientation.png
    :width: 80%

    **[空間の単位]** にnormを指定した場合の回転。回転してからスクリーンの縦横比を反映させるため図形が歪みます。

チェックリスト
    - **[回転角度 $]** に適切な値を設定して図形を回転させて表示させることができる。
    - 図形の正の回転方向を答えられる。
    - 単位がnormの時に図形を回転させた時に生じる図形のひずみを説明できる。

.. _section-color-representation:

色の指定方法を理解しよう
--------------------------------

今度はTextコンポーネントを使う練習をしながら、色の指定方法をマスターしましょう。ルーチンにTextコンポーネント( :numref:`fig-text-icon` のアイコン)をひとつ配置してください。Polygonコンポーネントなど他のコンポーネントを配置している人は削除しておいてください。

配置したTextコンポーネントのプロパティ設定ダイアログを開いてください。 **[位置 [x, y] $]** 、 **[回転角度 $]** 、 **[回転角度 $]** 、 **[空間の単位]** はPolygonコンポーネントの同名のプロパティと同じ働きをします。ここではこれらに加えて「基本」タブの **[文字列]** と「書式」タブの **[文字の高さ $]** 、「レイアウト」タブの **[反転]** 、 **[折り返し幅 $]** を使ってみましょう。

.. _fig-text-icon:

.. figure:: fig02/text-icon.png
    :width: 60%

    Textコンポーネントのアイコン

まず、**[文字列]** に適当な文字列を入力してください。日本語でも英語でも構いませんし、改行しても構いません。そして「書式」タブの **[文字の高さ $]** に0.02や0.04といった数値を指定して実行してみましょう。スクリーン上に **[文字列]** に入力した文字列が表示されるはずです。 **[文字の高さ $]** を変更して実行し、文字の大きさが変わることを確認してください(MacOSで日本語の文字が欠けてしまう場合は「 :numref:`{number}:{name} <topic-mac-font>` 」をご覧ください)。

**[空間の単位]** をpixにして **[文字の高さ $]** を0.1などにして実行すると、文字が1ピクセルより小さくなって何も表示されません。同様に **[空間の単位]** にheightが設定されている時に **[文字の高さ $]** を24などにしてしまうとスクリーンよりも文字がはるかに大きくなってしまい正常に表示されません。特に数値が大きすぎる場合はエラーダイアログが出て実験自体が実行できない場合があります。ありがちなミスなので注意してください。

なお、「書式」タブの **[言語スタイル]** は文字の書き方を指定します。左から右(LTR: left to right)、右から左(RTL: right to left)、Arabicのいずれかです。初期値はLTRで、通常は変更する必要はないでしょう。


.. _fig-text-height-flip-wrap:

.. figure:: fig02/text-height-flip-wrap.png
    :width: 80%

    Textコンポーネントにおける文字の高さ、反転、折り返し幅の設定例。

続いて「レイアウト」タブの **[反転]** と **[折り返し幅 $]** です。 **[反転]** はNone(または空白)にしておくと通常の文字列が表示されますが、vertと入力すると上下反転、horizと入力すると左右反転して文字列が表示されます(:numref:`fig-text-height-flip-wrap`)。 **[折り返し幅 $]** は、 **[文字列]** に改行を含まない長い文字列が入力されたときに自動的に折り返す幅を指定します。折り返し幅の単位は **[空間の単位]** プロパティに従います。 :numref:`fig-text-height-flip-wrap` では **[折り返し幅 $]** を指定しなかった場合、0.5を指定した場合、0.3を指定した場合を示しています。いずれも **[文字列]** には改行を含めずに文を入力してあるのですが、適切に折り返しが行われていることがわかります。ただし残念なことに、文字列の自動折り返しは日本語ではうまく機能しません。  :numref:`fig-text-height-flip-wrap` の一番下の日本語の文字列は **[折り返し幅 $]** に上の英文と同じ0.3を指定しているのですが、折り返されずに画面からはみ出してしまっています。

Textコンポーネントに慣れたところで、次は色の指定をしてみましょう。色を指定するには「外観」タブの **[前景色]** に値を設定します。 **[前景色]** の入力欄の右側に小さなボタンがありますが( :numref:`fig-color-picker-button` )、これをクリックすると「カラーピッカー」という色選択ツールを開くことができます。カラーピッカーは便利なのですが、PsychoPyにおける色指定の仕組みを理解していないとわかりにくい内容もありますので、まずは色指定の仕組みを学びましょう。

.. _fig-color-picker-button:

.. figure:: fig02/color-picker-button.png
    :width: 80%
    
    色を指定する項目には右側に「カラーピッカー」を開くボタンがあります

PsychoPyでは、色を表す値としてweb/X11 Color nameと呼ばれる色名と、16進数表記のwebカラーと、色空間における座標値を利用することができます。:numref:`fig-color-names` はweb/X11 Color nameの一覧を示しています。先ほどのPolygonコンポーネントの表示で **[塗りつぶしの色]** にblackと書くことで黒く塗りつぶすことができたのは、このweb/X11 Color nameによる指定が利用できるからです。:numref:`fig-color-names` を見ながら、Textコンポーネントのプロパティ選定ダイアログの **[前景色]** に色名を入力して実行してみましょう。

.. _fig-color-names:

.. figure:: fig02/color-names.png
    :width: 80%
    
    PsychoPyで使用できる色名 (web/x11 color name)

16進数表記のwebカラーというのは、0xFD087Aや#FAFのように、「0xまたは#」+「0から9の数字およびAからFのアルファベット文字を3文字または6文字」で色を表す方法です。webページを作成するときによく用いられる色指定なので、そちらですでにこの指定方法をご存じの方には使いやすいでしょう。しかし、ご存じでない方は次に紹介する色空間における座標値を指定する方法を覚えた方が良いと思います。webカラーによる色指定については「 :numref:`{number}:{name} <topic-hexadecimal-color-value>` 」で解説していますので詳しくはそちらをご覧ください。

さて、色空間における座標値を指定する方法ですが、これは人間が知覚できる色が三次元空間の点として表現できることを利用しています。ちょっと数学的な話になりますが、空間の位置を表現する方法は何通りもあります。例えば二次元平面の水平方向にX軸、垂直方向にY軸を引いて「原点からX軸の方向に10、Y軸の方向に10進む」といった具合に平面上の位置を表現することができますが、同じ位置を「原点から45度の方向に :math:`10 \sqrt{2}` 進む」と表現することもできます。前者を直交座標、後者を極座標と呼びますが、同じ位置でも直交座標と極座標では異なる数値で表されるわけです。これと同様に、色の表現も座標軸の取り方によって同一の色に対して複数の方法で表現することができます。PsychoPyでは、RGB、HSV、LMS、DKLという4種類の表現をサポートしています。しかし、HSVはBuilderからは使用できず、LMSとDKLは専用の装置を用いて実験に使用するモニターをキャリブレーション(調整)しないと使えませんので、本書ではRGBによる表現を使用します。この色表現を切り替えるのがプロパティ設定ダイアログの **[色空間]** です。 **[色空間]** の値がrgbに設定されていることを確認しておきましょう。なお、 **[色空間]** の値はweb/X11 color nameやwebカラーで色を指定する時には無視されます。

ようやく色空間における座標値で色を指定する方法を説明する準備ができました。 **[色空間]** をrgbに設定している場合、赤(R)、緑(G)、青(B)の三種類の光の強度の組み合わせで色を指定することができます。RGBのそれぞれの成分の強度は-1.0から1.0の実数で指定します。Textコンポーネントのプロパティ設定ダイアログを開いて **[前景色]** に

::

    -1, -1, -1

と記入してください。半角文字(日本語入力モードはOFF)で、カンマを忘れないでください。カンマの後ろの空白文字はあってもなくても構いません。
実行すると黒色で文字が表示されるはずです。続いて以下の三つを順番に試してみましょう。

::

     1, -1, -1
    -1,  1, -1
    -1, -1,  1

上から順番に赤色、緑色、青色で文字が表示されたはずです。三つの数字が左から順番にR、G、Bに対応しているのが理解していただけたでしょうか。さらに以下の値も試してみましょう。これらがどのような色になるかは実際に皆さんが確認してみてください。

::

     -0.3,  -0.3, -0.3
      0.2,   0.2,  0.2
    -0.92, -0.46, 0.05
     0.09,  0.63, 0.13

なお、一般的なグラフィックソフトウェアではRGBそれぞれ256段階の整数で指定する表現方法が用いられていますが、この256段階表現の色をPsychoPyで使用するには-1.0から1.0の実数に換算する必要があります。256段階表現の場合、RGB各成分の最小値は0で最大値は255ですから、値を255.0で割れば0.0から1.0の値が得られます。これを-1.0から1.0に変換すればいいのですから、2倍して1.0を引けば目的が達成されます。式で書けば以下の通りです。

::

    2×(256段階表現の値÷255.0)-1.0

慣れないうちは狙った色を指定するのは難しいですが、 :numref:`fig-color-picker-button` で触れたカラーピッカーがここで役に立ちます。 :numref:`fig-color-picker-button` のボタンをクリックすると、 :numref:`fig-color-picker` に示すカラーピッカーダイアログが表示されます。ダイアログ中央のRGB Channelsという枠内にある **[R]** 、 **[G]** 、 **[B]** のスライダーを調整すると、それに対応する色でダイアログ左側の領域が塗りつぶされます。文章で説明するより触ってみた方が早いと思いますので、ぜひ自分で操作してみてください。

.. _fig-color-picker:

.. figure:: fig02/color-picker.png
    :width: 80%
    
    カラーピッカーダイアログ

ダイアログ右側に並んでいる色見本をクリックすると、その色のRGB値がスライダーに反映されます。色名とRGB値がどのように対応しているかを確認したり、色名で表される色をほんの少し変更した色を指定したりするときに便利です。「この色を使いたい！」という色ができあがったら、ダイアログ左下の **[出力空間]** がPsychoPy RGB (rgb)になっていることを確認したうえで、右下にあるOKボタンをクリックしましょう。するとダイアログが閉じると同時に、 **[前景色]** の欄に作成した色のRGB値が自動的に挿入されます。色見本の色名を自動挿入することはできませんので、色名で指定したい場合は色名を覚えるかメモしたうえでダイアログを閉じ、手作業で色名を入力する必要があります。

最後に、Polygonコンポーネントの色指定について補足しておきます。Polygonコンポーネントには色指定に関して **[塗りつぶしの色]** と **[枠線の色]** という2つのプロパティがあり、それぞれ塗りつぶしと枠線の色に対応しています。これらの色にNoneという値を指定することによって、内部が塗りつぶされていない枠線だけの図形や、枠線がない図形を描画することができます。 **[塗りつぶしの色]** をNoneにすると内部が塗りつぶされていない枠線だけ、**[枠線の色]** をNoneにすると枠線がない図形になります。ぜひ覚えておいてください。

チェックリスト
    - Textコンポーネントを用いて文字列を表示できる。
    - 文字列を指定された位置に表示できる。
    - 文字列を指定された大きさで表示できる。
    - 文字列を上下反転、左右反転表示することができる。
    - 文字列の自動折り返し幅を設定できる。どのような文字列では自動折り返しが起きないか説明できる。
    - web/X11 color nameによる色指定で文字列の色を白、灰色、黒、赤、オレンジ色、黄色、黄緑色、緑、水色、青、ピンク、紫にすることができる。
    - **[色空間]** をrgbに設定して、数値指定によって文字列の色を白、灰色、黒、赤、黄色、緑色、青色にすることができる。
    - Polygonコンポーネントを用いて内部が塗りつぶされていない枠線だけの多角形を描画することができる。
    - Polygonコンポーネントを用いて枠線がない多角形を描画することができる。


.. _section-component-oder-opacity:

刺激の重ね順と透明度を理解しよう
---------------------------------------

刺激を色分けできるようになりましたので、刺激が重なってしまった時にどのような結果が得られるのかを解説できるようになりました。さっそく、刺激の重ねあわせについて解説しましょう。

PolygonコンポーネントひとつとTextコンポーネントひとつをルーチンペインに配置して、以下のように設定します。

- Polygonコンポーネント

    - 「基本」タブ
        - **[形状]** を長方形にする
    - 「レイアウト」タブ
        - **[サイズ [w, h] $]** を ``(0.2, 0.2)`` にする
    - 「外観」タブ
        - **[塗りつぶしの色]** を ``red`` にする
    - 他のプロパティは初期値のままにする

- Textコンポーネント

    - 「基本」タブ
        - **[文字列]** を ``PsychoPy Builderによる心理学実験`` にする
    - 「書式」タブ
        - **[文字の高さ $]** を ``0.02`` にする
    - 他のプロパティは初期値のままにする
    
どちらのコンポーネントを先にルーチンペインに配置したかによって、各コンポーネントのアイコンが並ぶ順番が異なります。先に配置したコンポーネントが上にあって、その下に配置した順番にアイコンが並びます。今までルーチンペイン上におけるアイコンの順番については触れませんでしたが、実はこの順番には大きな意味があります。 :numref:`fig-change-components-order` をご覧ください。Builderでは、ルーチンペインで上に配置されているコンポーネントから順にスクリーン上に表示します。ですから、ルーチンペイン上で下に配置されているコンポーネントほど重ね順は上になります。重ね順で上にあることを「手前にある」、下にあることを「奥にある」という言い方をすることもあります。

ルーチンペイン上での配置順を変更するには、変更したいコンポーネントのアイコン上へマウスカーソルを動かして、右クリックをしてメニューを表示させます。ここまではコンポーネントを削除する時の操作と同じです。削除する時にはメニューの「削除」という項目を選択しましたが、配置順を変更する時には「ひとつ上へ」、「ひとつ下へ」、「一番上へ」、「一番下へ」を選択します。

.. _fig-change-components-order:

.. figure:: fig02/change-components-order.png
    :width: 80%

    ルーチンペインにおける順序と刺激の重ねあわせの関係。ルーチンペインで上の方に配置されている刺激から順に表示されますので、スクリーン上での刺激の重ね順では上に配置されている刺激ほど下になります。

刺激の重ね順を解説したついでに、 **[位置 [x, y] $]** などと同様に多くの視覚刺激用コンポーネントで使用できる **[不透明度 $]** を紹介します。 **[不透明度 $]** は刺激の透明度を指定するプロパティで、0.0から1.0の値をとります。0.0は完全な透明で、スクリーン上では見えなくなってしまいます。1.0は完全な不透明で、重ね順で下にある刺激は見えません。 :numref:`fig-set-opacity` では、文字列の上に赤い正方形を重ねて、正方形の透明度を1.0、0.75、0.5、0.25、0.0と変化させています。簡単に試すことができると思いますので、ぜひ各自でいろいろな値を試してみてください。

.. _fig-set-opacity:

.. figure:: fig02/set-opacity.png
    :width: 50%
    
    **[不透明度 $]** による透明度の指定。赤い正方形が文字列の上に重ねて、その赤い正方形の **[不透明度 $]** を段階的に変化させています

チェックリスト
    - ルーチンペイン上における視覚刺激コンポーネントの順番とスクリーン上での重ね順の関係を説明できる。
    - ルーチンペイン上におけるコンポーネントの順番を変更できる。
    - 視覚刺激コンポーネントの透明度を設定して完全な透明、完全な不透明とその中間の透明度で刺激を表示させることができる。

.. _section-set-start-stop:

刺激の提示開始と終了時刻の指定方法を理解しよう
-----------------------------------------------------------

この節では、刺激がいつ画面上に表示されて、いつ消えるかという時間的な側面を設定する方法について解説します。ここまで使用してきたPolygonコンポーネントとTextコンポーネントのプロパティ設定ダイアログの「基本」タブを見比べてみると、どちらにも **[開始]** と **[終了]** というプロパティが存在しているのがわかります(:numref:`fig-start-stop`)。これらが刺激の提示開始および終了を決めるプロパティです。解説に入る前に、ちょっと **[開始]** の上にある **[名前]** プロパティの使い方にも触れておきましょう（ **[名前]** については次章で詳しく解説する予定です）。

.. _fig-start-stop:

.. figure:: fig02/start-stop.png
    :width: 80%
    
    コンポーネントの開始、終了時刻を指定するプロパティ。「条件式」の使い方については :numref:`第%s章 <chapter-gui>` で触れます。

まず、Polygonコンポーネントを二つルーチンペイン上に配置して、二つの正方形が左右に隙間なく並ぶようにしてみましょう。ここでは以下のように設定したとします。

- Polygonコンポーネントその1 (赤)

    - 「基本」タブ
        - **[名前]** に ``red`` と入力
    - 「レイアウト」タブ
        - **[サイズ [w, h] $]** を ``(0.2, 0.2)`` 、 **[位置 [x, y] $]** を ``(-0.1, 0)`` にする
    - 「外観」タブ
        - **[塗りつぶしの色]** を ``red`` にする
    - 他のプロパティは初期値のままにする

- Polygonコンポーネントその2 (緑)

    - 「基本」タブ
        - **[名前]** に ``green`` と入力
    - 「レイアウト」タブ
        - **[サイズ [w, h] $]** を ``(0.2, 0.2)`` 、 **[位置 [x, y] $]** を ``(0.1, 0)`` にする
    - 「外観」タブ
        - **[塗りつぶしの色]** を ``green`` にする
    - 他のプロパティは初期値のままにする

- 緑色の長方形が上に描画されるようにルーチンペイン上でのアイコンの順番を並べる。
    
**[名前]** を設定すると、 :numref:`fig-component-name` のようにルーチンペイン上で **[名前]** に設定した文字列が各コンポーネントのアイコンの左側に表示されます。同じ種類のコンポーネントが複数配置されている場合に区別しやすくてとても便利です。

.. _fig-component-name:

.. figure:: fig02/component-name.png
    :width: 60%
    
    **[名前]** プロパティに文字列を入力すると、ルーチンペイン上でコンポーネントのアイコンの左側に入力した文字列が表示されます。

さて、この状態で実験を実行すると、赤と緑の正方形がスクリーンに1秒間表示されて終了するはずです。Builderの画面に戻ったら、ルーチンペイン上に配置した赤い正方形のプロパティ設定ダイアログを開き、 :numref:`fig-set-start-stop-time` 左のように **[開始]** を「時刻 (秒)」にして0.5と入力し、 **[終了]** を「実行時間 (秒)」にして2と入力してください。 **[開始]** と **[終了]** はそれぞれ初期状態で「時刻 (秒)」、「実行時間 (秒)」になっているはずですので、変更していないのであればそれぞれ0.5と2を入力すれば大丈夫です。プロパティ設定ダイアログのOKをクリックしてダイアログを閉じると、ルーチンペイン上の表示が :numref:`fig-set-start-stop-time` 右のように変化しているはずです。アイコンの横の青い横棒はコンポーネントが有効になる時間帯、視覚刺激の場合は画面上に表示されている時間帯を示しています。開始時刻に0.5秒を指定したので、青棒の左端は0.5の位置にあります。青棒の右端は終了時刻に対応していますが、こちらは少し説明が必要でしょう。 **[終了]** は「実行時間 (秒)」を指定して2と入力してありますので、刺激が画面上に表示されている時間は2秒です。刺激の表示開始時刻が0.5秒なのですから、終了時刻は0.5秒から2秒後の2.5秒でなければいけません。ルーチンペインの青棒の右端を確認すると、確かに右端は2.5秒の位置にあります。実験を実行してみると、最初に緑色の正方形のみが表示された後、一瞬(0.5秒)遅れて赤い正方形が出現し、さらにすぐ後に緑色の正方形がスクリーンから消えます。赤い正方形は2秒間スクリーンに表示された後に消えて、その直後に実験が終了します。

.. _fig-set-start-stop-time:

.. figure:: fig02/set-start-stop-time.png
    :width: 80%
    
    **[開始]** と **[終了]** の値を変更すると、ルーチンペイン上で青いバーの長さが変更されます。青いバーは実験実行時に、そのコンポーネントが有効となる(視覚刺激の場合は表示される)時間帯を示しています。

基本的にこれだけで刺激の表示開始時刻と終了時刻を制御できますが、Builderでは他の方法も提供されています。まず、 **[終了]** で「実行時間 (秒)」の他に「時刻 (秒)」を選択することができます。こちらを選択すると、終了時刻を直接入力して指定することができます。 :numref:`fig-set-start-stop-time` の例で **[終了]** を「時刻 (秒)」に変更し、値に2.5を入力してみてください。ルーチンペインの青棒は :numref:`fig-set-start-stop-time` と同じになり、実行結果も同じになるはずです。ぜひ皆さん自身で手を動かして確認してみてください。

他には、刺激の表示開始、終了時刻を秒ではなくフレーム数で指定する方法があります。フレーム数で指定する場合も秒と同様に **[終了]** の項目で表示する時間の長さを指定するか、終了する時刻を直接指定するかを選択できます。「『フレーム数で指定』と言われてもよくわからない」という方は、「 :numref:`{number}:{name} <topic-start-stop-by-frame>` 」をご覧ください。 :numref:`fig-start-stop` で灰色の文字で描かれている **[予想開始時刻 (s)]** 、 **[予想実行時間 (s)]** という項目はフレーム数で指定する際に使う項目なので、そちらで合わせて説明してあります。

**[開始]** 、 **[終了]** ともに、秒による指定、フレーム数による指定に加えて「条件式」という選択肢がありますが、これはPythonの条件式を直接記入する方法です。使いこなすにはPythonの文法を知っていなければいけませんので、ここでは一旦無視して :numref:`第%s章 <chapter-gui>` であらためて取り上げます。

最後に、非常に重要なテクニックをひとつ紹介しておきましょう。 **[終了]** の項目の数値を入力する欄を空白(入力済みの数値を削除)してみてください。ルーチンペイン上でコンポーネントの有効時間帯を示す青い横棒が右側へ突き抜けてしまったはずです( :numref:`fig-set-endless` )。この状態になると、何らかの方法でルーチンが強制終了されない限り、この刺激は画面上に表示され続けます。この章で今まで製作してきたシンプルな「実験」では、すべてのコンポーネントの終了時刻が決められていました(1.0秒)。Builderの実験を実行した時には、ルーチン内に含まれるすべてのコンポーネントの終了時刻を経過したらルーチンが自動的に終了し、すべてのルーチンを実行すれば実験は自動的に終了します。 :numref:`fig-set-endless` のように終了時刻が定められていないコンポーネントが存在すると、ルーチンが「永遠に」終了しません。現実にはOSが再起動したりPCの電源が切れたりしていずれは終了してしまうでしょうが、そういう事態でもない限り刺激が表示され続けます。誤ってルーチンが終了しない状態に陥ってしまった時には、焦らずにキーボードのESCキーを押してください。Builderの標準設定では、ESCキーが押されると直ちに処理中のルーチンを中断して実験を終了します。

終了時刻を定めないコンポーネントが定義できるようになっているのは、「実験参加者が反応するまで刺激を提示し続ける」といった実験手続を実現する為です。次章ではキーボードからの反応を取得する方法を学びますが、「キーボードが押されたらルーチンを終了する」という設定と、「ルーチンが終了するまで刺激を提示し続ける」という設定を組み合わせれば「実験参加者が反応するまで刺激を提示し続ける」ことが実現できるのです。詳しくは :numref:`第%s章 <chapter-basic-experiment>` で説明します。

.. _fig-set-endless:

.. figure:: fig02/set-endless.png
    :width: 80%
    
    **[終了]** を空白にしておくと、ルーチンの終了までコンポーネントが有効になります。何らかの方法でルーチンを終了させない限り刺激は表示され続けます。標準設定ではESCキーを押すと強制的に実験を終了させることができます(ルーチンも強制終了されます)。

チェックリスト
    - 刺激の表示開始時刻と表示時間を指定して表示させることができる。
    - 刺激の表示開始時刻と表示終了時刻を指定して表示させることができる。
    - 刺激の表示終了時刻を定めずに表示させることができる。
    - 実行中の実験を強制的に終了させることができる。

.. _section-builder-output-files:

Builderが作成するファイルを確認しよう
-----------------------------------------

「刺激の位置や提示時間を指定する方法を覚える」というこの章の内容はほぼ終わりました。最後に実験の基本設定を行う方法を解説したいのですが、その前にBuilderが作成するファイルとフォルダについて簡単に触れておきます。

ここまで作業の作業を進めた後でchapter2.psyexpを保存したフォルダを確認すると、dataというフォルダとchapter2_lastrun.pyというファイルができているはず。もしpsyexpファイルをchapter2以外の名前で保存したのでしたら、_lastlan.pyの前の部分が保存したファイル名に対応した文字列になっているはずです。

chapter2_lastrun.pyはBuilderがpsyexpファイルを「翻訳」して作成したPythonのスクリプトです。メモ帳などのテキストエディタで開いてみると内容を確認することができます。Pythonを用いて実験をするとは元々このようなファイルを自分で書くということであり、その作業を人の代わりに行ってくれるのがPsychoPy Builderだというわけです。ただし、Builderが生成するスクリプトは人が書く場合に比べて少々冗長ですので、人が書けばもっと短いスクリプトで実現することも可能です。このファイルは実験を実行する度に自動的に作成されるので、実験終了後に削除してしまっても問題ありません。

dataフォルダは、実験結果を記録したファイルが保存されるフォルダです。実験を一回実行する度に複数のファイルが作成されるので、もしここまで一気に作業してこられたのでしたら非常にたくさんのファイルが作成されているはずです。このフォルダ内のファイルには実験結果が記録されています。この章で作業した内容は特に記録する必要はありませんので、dataフォルダごと削除してしまって構いません。ファイルの内容については :numref:`第%s章 <chapter-basic-experiment>` 以降で詳しく見ていきます。

最後に、psyexpファイルそのものについて少し補足しておきましょう。Builderで作成した実験の内容はすべてこのファイルに保存されていますので、実験が不要にならない限りこのファイルを削除してはいけません。psyexpファイルの他に、:numref:`第%s章 <chapter-basic-experiment>` で解説する条件ファイルもpsyexpファイルと一緒に保存しておく必要があります。刺激として画像ファイルや音声ファイルを使用する場合は、それらのファイルも忘れずに保存しておかなければいけません。なお、psyexpファイルはXML形式と呼ばれるデータ形式で保存されたファイルなので、メモ帳などのテキストエディタを使って開くと中身を見ることができます。

保存したpsyexpファイルは、 :numref:`fig-ribbon-icons` の「実験を開く」ボタンをクリックするとBuilderで開くことができます。作成途中で保存したpsyexpファイルを開いたり、完成したpsyexpファイルを使って実験したりする時に使います。OSによってはpsyexpファイルのアイコンをダブルクリックするだけで自動的にBuilderを起動してファイルを開くこともできます。作業を保存する時は「上書き保存」ボタン、別の名前で保存したいときには「名前を付けて保存」ボタンを使います。現在作成中の実験を置いておいて新たに実験を作成したい場合は「実験の新規作成」ボタンを使います。他にも「元に戻す」と「やり直す」ボタンも便利ですので一緒に覚えておくとよいでしょう。

.. _fig-ribbon-icons:

.. figure:: fig02/ribbon-icons.png
    :width: 70%
    
    ファイル操作に関するボタンと元に戻す・やり直すボタン。

チェックリスト
    - foo_lastrun.py (fooはpsyexp実験ファイル名)の役割を説明することができる。
    - dataフォルダの役割を説明することができる。
    - 実験結果を保存する必要がない場合、どのファイルを削除しても問題ないかを判断できる。
    - 作製済みのpsyexpファイルをBuilderで開くことができる。
    - psyexpファイルを別の名前で保存することができる。


.. _section-change-experiment-settings:

実験の設定を変更しよう
--------------------------------------

これで刺激の描画方法の基礎を一通り解説しました。本格的な実験の作成に入る前に、実験の設定について解説しておきます。
Builderウィンドウ上部のツールバーの :numref:`fig-open-experiment-setting` に示したアイコンをクリックすると、実験設定ダイアログが開きます。このダイアログには「基本」、「データ」、「スクリーン」の三つのページがあり、非常に多くの項目が含まれています。「基本」から順番に見ていきましょう。

.. _fig-open-experiment-setting:

.. figure:: fig02/open-experiment-setting.png
    :width: 80%
    
    Builderウィンドウ上部のリボンにある歯車のアイコンのボタンから実験設定ダイアログを開くことができます。

「基本」タブ
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

このタブでは **[実験の名前]** と **[実験情報ダイアログ]** が非常に重要です。
**[実験情報ダイアログ]** は :numref:`第%s章 <chapter-loop-tips>` 以降で詳しく取り上げます。


**[実験の名前]**
    実験の名前を入力します。実験結果の記録ファイルに反映されるため、データ整理の際に便利でしょう。ファイル名として使用できる文字列でなければいけません。日本語の文字の使用は避けた方が無難です。

**[実行モード]**
    BuilderのリボンのRunモードスイッチと同じです。実験設定ダイアログ上で変更してBuilderに戻れば変更が反映されています。

**[使用するPsychoPyのバージョン]**
    旧バージョンのPsychoPyで作成した実験が現在使用中のバージョンで動かないときに、旧バージョンで実行するように指定することができます。この機能を利用するためには、gitというコマンドが使用できるように設定しておく必要があります。利用のためには他にもいろいろと条件があるので、初心者の方には利用をお勧めしません。

**[ESCキーによる中断]**
   「 :numref:`{number}:{name} <section-set-start-stop>` 」で触れた、ESCキーによる実験の強制終了を有効にするか無効にするかを指定します。実験中に実験参加者が誤ってESCキーを押してしまう恐れがある場合はチェックを外しておくべきですが、チェックを外してしまうと強制終了ができなくなりますので注意してください。実験が完成して、十分に動作確認をして問題がないことを確認してからチェックをはずすとよいでしょう。なお、フルスクリーンモードを使用していない場合は、実験実行中にRunnerのウィンドウを選択して実験中断ボタンをクリックしても強制終了することができます。

**[Rushモード]**
    この項目にチェックを入れると、実験を可能な限り高い優先度で実行しようとします。WindowsにせよMacOSにせよ、現代のOSでは何も操作していなくてもいくつものプログラムが並行して動作しており、実験実行中に別のプログラムが時間を要する作業を始めると、実験の時間精度に影響する恐れがあります。並行して動作しているプログラムの間には優先順位があり、優先順位が高いものは低いものの割り込みを受けにくくなります。RushモードをONにすると、可能な限り実験プログラムの優先度を高めようとします。初期値ではOFFになっていますが、実験の時間精度が安定しない場合は試してみる価値があります。

**[実験情報ダイアログを表示]**
    実験実行時に表示される実験情報ダイアログの表示、非表示を指定します。チェックを外しておくと実験情報ダイアログが表示されません。

**[実験情報ダイアログ]**
    実験情報ダイアログに表示する項目を設定します。詳しくは :numref:`第%s章 <chapter-loop-tips>` を参照してください。

.. _subsection-screen-settings:

「スクリーン」タブ
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

このタブには **[フルスクリーンウィンドウ]** 、 **[ウィンドウの大きさ (pix) $]** 、 **[マウスカーソルを表示]** 、 **[単位]**  、 **[背景色]** など、画面に関する重要な設定項目がたくさんあります。

**[モニター]**
    使用するモニターを指定します。PsychoPyではモニターの設定に名前をつけて保存しておくことができますが、ここでは使用するモニター設定の名前を入力します。モニター設定の作成方法はこの章の「 :numref:`{number}:{name} <section-monitor-settings>` 」触れます。

**[ウィンドウバックエンド]**
    実験を実行すると灰色の画面に切り替わりましたが、その画面の描画に使用するライブラリを指定します。初期値はpygletで、通常は変更する必要ありません。

**[スクリーン]**
    複数台のモニターが接続されたPCを使用する場合、どのモニターを視覚刺激提示に使用するかを番号で指定します。モニター番号がわからない場合は、「スクリーン番号の表示」をクリックして各モニター上に番号を表示させて調べることができます。

**[フルスクリーンウィンドウ]**
    刺激提示にモニターのスクリーンいっぱいに広がったウィンドウを用いるか否かを指定します。チェックが入っていると、スクリーン全体がBuilderの実験ウィンドウで覆われて、他のアプリケーションやデスクトップは見えなくなります。この状態をフルスクリーンモードと呼びます。チェックを外すと、視覚刺激提示用に通常のアプリケーションのようなウィンドウが開いて、そのウィンドウ内に刺激が提示されます。
    一般論として、フルスクリーンモードの方が実験実行時の時間的な精度が高い傾向にあります。何らかの理由があって通常のアプリケーションウィンドウで実行したい場合を除いて、この項目はチェックしておくべきです。

**[マウスカーソルを表示]**
    この項目をチェックしておくと、フルスクリーンモードでの実験実行時にもマウスカーソルが表示されます。標準ではチェックされていません。マウスを用いて参加者の反応を記録する実験を実施する場合などに使います。 **「入力」タブでioHubを選択していると、この項目のチェックを外しているにも関わらずマウスカーソルが表示されてしまう場合があります。**

**[ウィンドウの大きさ (pix) $]**
    フルスクリーンウィンドウを使用しない時に、刺激提示用ウィンドウの幅と高さを指定します。書き方は視覚刺激の大きさの指定と同様[1920, 1080]といった具合に幅と高さの値をカンマで区切って書き、角括弧で囲みます。単位はpixです。フルスクリーンウィンドウ使用時にはこの項目は灰色に表示されていて編集できません。フルスクリーンウィンドウ使用時のスクリーンの解像度はOSによる解像度の設定に従います。Pilotモード時のウィンドウの大きさは、「 :numref:`{number}:{name} <section-pilot-window-size-setting>` 」で示す方法で設定した大きさに従います。    

**[単位]** 
    視覚刺激コンポーネントで用いられる標準の単位を指定します。具体的には、 :numref:`tbl-psychopy-units` に示した単位のうち「実験の設定に従う」を選択した際に使用される単位を指定します。個々のコンポーネントで「実験の設定に従う」以外の単位を選択した場合は、そちらが優先されます。
    単位の選択肢の中に「PsychoPyの設定に従う」という項目がありますが、これはPsychoPy設定ダイアログ(「 :numref:`{number}:{name} <section-pilot-window-size-setting>` 」で触れます)で定義されている標準の単位に従うことを意味しています。
    筆者の率直な考えを述べると、「PsychoPyの設定に従う」を使う場面は(heightが単位として導入された以降は特に)ほぼありません。しいて言えば、実験によって自分でコードを書く方法とBuilderを使う方法を併用している人で、両方の方法で使用する単位を一括して変更する可能性がある場合は「PsychoPyの設定に従う」が役に立つかもしれませんが、特殊なケースだと思います。

**[背景色]**
    視覚刺激提示画面の背景色を指定します。視覚刺激の色の指定方法と同様に、web/X11 color nameやwebカラー、色空間を指定した数値表現を使用することができます。

**[ブレンドモード]**
    刺激を重ね書きした時の挙動を指定します。標準値は「平均」で、「 :numref:`{number}:{name} <section-component-oder-opacity>` 」で解説した通りに描画されます。「加算」にすると色が足し合わされます。「足し合わされる」といってもわかりにくいと思いますので、 **[不透明度 $]** 0.3の赤、緑、青の円をブレンドモード「平均」と「加算」で重ね合わせた出力を :numref:`fig-blendmode` に示します。
    
    「加算」の重ね合わせのほうが光の加法混色に近いですが、重ね合わせの結果、色がPsychoPy(正確にはPsychoPyが描画に使用しているOpenGLというライブラリ)が表現できる範囲を超えてしまった時には描画が破綻してしまいますので、実験製作者がよく考えて刺激の色を決定する必要があります。「平均」ではそのような破綻が起きることはありません。

.. _fig-blendmode:

.. figure:: fig02/blendmode.png
    :width: 80%
    
    ブレンドモードの比較。

**[色空間]**
    背景色の指定に使用する色空間を指定します。

**[背景画像]**
    画像ファイルを背景として使用したい場合、ここにそのファイルを指定します。画像ファイルの指定方法については :numref:`第%s章 <chapter-code-if>` で詳しく解説します。
    画像ファイルのサイズと次の **[背景画像の伸縮]** の設定の組み合わせによってはスクリーンより画像が小さく表示されますが、その場合画像の周囲の領域は **[背景色]** で設定した色になります。

**[背景画像の伸縮]**
    **[背景画像]** に画像ファイルが指定された場合に、画像のサイズをどのように調整するかを指定します。「なし」にすると画像ファイルのサイズそのまま、「cover」にすると画像がスクリーンに外接、「contain」にすると画像がスクリーンに内接するように拡大縮小されます。これらはいずれも元画像の縦横比を変更しません。「fill」にすると、スクリーンにぴったり一致するように必要に応じて縦横比を変更しながら画像を拡大縮小します。「scale-down」にすると、画像がスクリーンより大きい場合のみ画像がスクリーンに内接するように(つまりcontainsと同じ)縮小されます。

**[フレームレートの測定]**
    この項目がチェックされていると、実験開始時にフレームレートの測定(1秒間に何回画面を書き換えているか)をおこないます。実験を実行したときに Attempting to measure frame rate of screen, please wait... と表示されているのはこのフレームレートの測定をおこなっていることを示すメッセージです。フレームレートについては「 :numref:`{number}:{name} <topic-start-stop-by-frame>` 」で詳しく解説しています。実験が始まる前に少し待たされるのを不満に思う方もいるかもしれませんが、 **この項目はチェックしたままにしておくことを強く勧めます。**

    この項目のチェックの有無で次の項目の名称が変化します。

**[フレームレート測定時のメッセージ]** / **[フレームレート]**
    **[フレームレートの測定]** がチェックされていれば **[フレームレート測定時のメッセージ]** 、チェックされていなければ **[フレームレート]** という項目になります。
    **[フレームレート測定時のメッセージ]** はフレームレートの測定中に画面に表示される文で、初期値は Attempting to measure frame rate of screen, please wait... です。文面を変更したい場合はここを編集してください。ただし、日本語の文字などはフォントによっては正しく表示されませんので、編集する場合でも英語のままにしておくことをお勧めします。

    フレームレートの測定をおこなわない場合は **[フレームレート]** に適切なフレームレートを入力しなければいけません。たとえばモニターのスペック表で60Hzと記されているなら60と入力します。ただし、実際にはさまざまな理由でスペック表のとおりに描画がおこなわれていない場合があり(だからこそBuilderの実験では最初に実測しようとする)、こちらで入力した値と実際の値がずれていたら時間精度に悪影響があることは覚悟しておいてください。

「オーディオ」タブ
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

音声関連の設定をします。すでにPsychoPyを長く使用していて、過去に使用していたライブラリと同じものを使い続けたい場合などには設定を変更する必要があるかもしれませんが、新たに使い始める人はまず変更せずに使用してみることをお勧めします。

オーディオの再生に関する設定を行います。詳しくは :numref:`第%s章 <chapter-sound-movie>` を参照してください。

**[オーディオライブラリ]**
    オーディオの再生に使用するライブラリを選択します。ptbはMatlabのパッケージとして有名なPsychToolboxを移植したもので、2025年2月現在で標準のオーディオライブラリとされています。pyo、sounddevice、pygameは過去に使用されていたライブラリで互換性のために残されています。

**[オーディオ遅延の優先度]**
    PsychToolboxのオーディオを使用する場合の再生遅延の設定をおこないます。0から4まで5段階あり、数字が小さいほど幅広いハードウェアで再生できますが遅延が長くなります。

**[ステレオを強制]**
    Soundコンポーネント( :numref:`第%s章 <chapter-sound-movie>` )でステレオ再生するように設定します。とりあえずそのままにしておいて問題ないでしょう。


「オンライン」タブ
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

インターネット上でオンライン実験を行うための設定を行います。
ローカルで実験を行う場合は関係ありません。

**[出力パス]**
    サーバーへアップロードするHTML形式の実験ファイルを出力するフォルダ名を指定します。 **通常、ここは空欄にしておいてください。**

**[HTML形式でエクスポート]**
    HTML形式の実験ファイルを出力するタイミングを指定します。「同期時」ならサーバーと同期するとき、「保存時」なら保存するとき、「手作業で」なら手動で出力します。

**[正常終了時のURL]**
    実験が正常に終了した時に表示するページのURLを指定します。

**[中断時のURL]**
    実験が中断された時に表示するページのURLを指定します。

**[終了メッセージ]**
    実験が正常に終了した時に表示するメッセージを指定します。

**[追加リソース]**
    実験で使用する画像ファイルや音声ファイルのうち、Builderが自動で見つけられないものをここに追加しておくとBuilderが認識してくれます( :numref:`第%s章 <chapter-loop-tips>` のテクニックで実行時に読み込むファイルを決定する場合などに便利です)。

「アイトラッキング」タブ
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Builderに組み込みの各種市販アイトラッカーとの連携機能に関する設定をおこないます。使用するには対応するアイトラッカーが必要です。

**[アイトラッカーデバイス]**
    使用するアイトラッカーを選択します。デフォルトはNone(使用しない)です。選択したアイトラッカーに応じて必要な設定項目が表示されます。ここではマウスによってアイトラッカーの動作をシミュレートするMouseGazeを選択した場合の項目を解説します。

**[Moveボタン]**
    マウスカーソルの動きをどのように視線の動きに変換するかを指定します。CONTINUOUSならマウスカーソルの位置がそのまま視線位置となります。LEFT_BUTTON、MID_BUTTON、RIGHT_BUTTONのいずれかを選択すると、選択したボタンをクリックしたときにその位置へ視線が移動します。

**[Blinkボタン]**
    瞬目をシミュレートするボタンを選択します。

**[サッカード閾値]**
    サッカード検出のための閾値を視線の移動量(単位:deg)で指定します。deg単位が有効になるためにはモニターの設定でモニターの幅と観察距離が設定されていないといけない点に注意してください。

.. _subsection-input:

「入力」タブ
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**[キーボードバックエンド]**
    キーボードのキー押し検出に使うライブラリを選択します。PsychToolboxは時間精度の高さが特徴です。ioHubはPsychToolboxと比べると機能的にやや劣りますが、キーボードやマウス以外の入出力デバイスを用いるのならioHubの方がよいかもしれません。PygletはPsychToolbox、iohubには劣りますがこれらのライブラリを利用できない環境でも使うことができます。
    
    なお、この項目をioHubに設定している場合、「 :numref:`{number}:{name} <section-mouse-cursor-control>` 」で紹介する方法でマウスカーソルを非表示にできない場合があります(2022.2.4/Win11で確認)。

「データ」タブ
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

データの保存形式やログに関する設定をおこないます。データファイルについては :numref:`第%s章 <chapter-basic-experiment>` で解説します。
通常は変更する必要はありません。

**[データファイル名 $]**
    実験結果を記録したファイルの名前を決定する規則をPythonの式で入力します。通常の用途では変更する必要はないはずです。

**[データファイルの区切り文字]**
    データファイルで列を区切る文字を指定します。autoにするとファイル名から自動的に区切り文字を決定します。他にはコンマ、セミコロン、タブを指定できます。

**[列の並び替え...]**
    データファイルで各パラメータが出力される列の順序を選択します。「追加順」は実験実行時に当該パラメータが最初に記録されるタイミング順、「アルファベット順」は文字通りパラメータ名の順、「優先度」は次の **[列の優先度]** の設定に従って順序を決定します。

**[列の優先度]**
    「列」にパラメータ名、「優先度」に数値を設定することによって列の並び替え順を制御することができます。priority.CRITICAL, priority.HIGH, priority.MEDIUM, priority.LOW, priority.EXCLUDEといった定数があらかじめ用意されています(それぞれ30, 20, 10,0, -10に対応していますが将来的に変更されるかもしれません)。筆者が確認した範囲では、同一の優先度を持つパラメータはアルファベット順に出力されます。

**[xlsx形式のデータを保存]**
    Excelのxlsx形式で実験結果を記録します。詳しくは :numref:`第%s章 <chapter-basic-experiment>` を参照してください。

**[ログの保存]**
    PsychoPyの動作状況をログファイルに記録します。

**[CSV形式のデータを保存(summaries)]**
    CSV形式で実験結果の要約を記録します。詳しくは :numref:`第%s章 <chapter-basic-experiment>` を参照してください。

**[CSV形式のデータを保存(trial-by-trial)]**
    CSV形式で実験の全試行の結果を記録します。詳しくは :numref:`第%s章 <chapter-basic-experiment>` を参照してください。

**[pydat形式のデータを保存]**
    Pythonのpydat形式で実験結果を記録します。チェックを外すことはできません。

**[hdf5形式のデータを保存]**
    アイトラッカーなどの、iohubを介して連携する一部の装置の測定データはhdf5形式で記録されます。ここでは詳しい解説を省略します。

**[ログレベル (ファイル)]**
    ログファイルに出力される内容を指定します。レベルにはerrorからdebugまで6段階あり、errorが最も簡潔、debugが最も詳細です。初期値はinfoです。

**[ログレベル (コンソール/アプリ)]**
    Runnerの「標準出力」などに出力される内容を指定します。レベルの段階は **[ログレベル (ファイル)]** と同一で、初期値はwarningです。

**[時刻のフォーマット]**
    ログファイルに出力される時刻の表記方法を指定します。初期値は「実験開始時から」で、実験開始時刻を0.0とした経過時間で表記します。 ストップウォッチのようなものを想像してください。「実時間」を選択すると、PCの時計にしたがって 年月日 時分秒 の形式で表記します。


以上で実験設定ダイアログの概要の説明は終了です。
とりあえず設定は変更せず初期値のまま使ってみることをお勧めしますが、

- 「スクリーン」タブの **[フルスクリーンウィンドウ]** のチェックを外してPilotモード、実行モードの両方のモードで実験を実行してみる。
- 「スクリーン」タブの **[背景色]** を指定して背景色を変える。
- 「スクリーン」タブの **[マウスカーソルを表示]** のチェックを外した状態で「入力」タブの **[キーボードバックエンド]** をioHubにして実行し、皆さんの実行環境でマウスカーソルが表示されないか確認する。表示されてしまう場合は **[キーボードバックエンド]** をPsychToolboxにして確認する。面倒だが **[マウスカーソルを表示]** をチェックした状態でioHub、PsychToolboxでの実行した場合も確認しておくとよい。

の3つは各自で実際に試してみてみるとよいでしょう。

チェックリスト
    - 実験設定ダイアログを開くことができる。
    - 実験開始時に実験情報ダイアログを表示させるか否かを設定することができる。
    - 登録済みのモニターのうちどれを実験に使用するかを実験設定ダイアログで設定できる。
    - 実験をフルスクリーンモードで実行するか否かを設定することができる。
    - フルスクリーンモードを使用しない時に、視覚刺激提示ウィンドウの幅と高さを指定できる。
    - 視覚提示ウィンドウの背景色を指定できる。
    - 「実験の設定に従う」で参照される単位を指定することができる。
    - ESCキーによる実験の強制終了を有効にするか無効にするかを指定することができる。
    - 実験記録のファイルを保存するフォルダ名を指定することができる。
    - フルスクリーンモード時にマウスカーソルを表示するか否かを指定することができる。

.. _section-pilot-window-size-setting:

Pilotモードのウィンドウサイズを設定しよう
------------------------------------------------------

前節で確認したBuilderの実験設定ダイアログに加え、PsychoPyにはPsychoPy設定ダイアログというものもあります。Builderの実験設定ダイアログはBuilder以外の方法で実験を作成する場合には無関係ですが、PsychoPy設定ダイアログの内容はPsychoPyの動作全体に関わってきます。
本書ではPsychoPy設定ダイアログの内容に触れませんが、Pilotモードのウィンドウサイズが標準では800×600しかなく、高解像度のモニターで見ると非常に小さくなってしまうので、この問題に関する項目だけ解説しておきます。

PsychoPy設定ダイアログは :numref:`fig-set-pilot-window-size` の左ようにBuilderのメニューの「ファイル」から開きます。
ダイアログの「Pilotモード」を開くと「ウィンドウサイズを強制」という項目がありますので、1280, 720のように幅、高さをカンマ区切りで入力してください。
実験本番の時と同じサイズにするもよいでしょうし、やや小さめにしておいて背後にあるウィンドウにアクセスしやすいようにするのもよいでしょう。
小さめにする場合、モニターの解像度が1920×1080 (縦横比16:9)なら1280×720にするなど、　**同じ縦横比にしておくと単位heightで実験を作成するときに視覚刺激がきちんと画面内におさまるか確認できる** のでお勧めです。
各自の環境に応じて値を設定してください。

.. _fig-set-pilot-window-size:

.. figure:: fig02/set-pilot-window-size.png
    :width: 80%
    
    Pilotモードのウィンドウサイズの設定。Builderのメニューの「ファイル」からPsychoPy設定ダイアログを開いて設定します。

なお、「 :numref:`{number}:{name} <section-install-standalone-psychopy>` 」で触れた通り、PsychoPy 2024系ではメニューなどが英語で表示される問題があり、「:numref:`{number}:{name} <topic-change-application-locale>` 」に修正方法を示しましたが、この修正を適用してもなおPsychoPy設定ダイアログの項目は英語で表示されてしまいます。
その場合、「ウィンドウサイズを強制」はforcedWindowSizeという名称で表示されます。「Pilotモード」のページには800, 600のように2つの数値を並べて記入する項目はこれひとつしかありませんので(バージョン2024.2.5現在)すぐにわかると思います。

チェックリスト
    - Pilotモード時のウィンドウサイズの設定を変更できる。

.. _section-monitor-settings:

モニターを設定しよう
------------------------------------------------------

長くなりましたが、本章の最後の話題です。degやcmを単位として使用できるように、あなたが使用しているモニターをPsychoPyに登録しておきましょう。

モニターを登録するには、ツールバーの :numref:`fig-open-monitor-center` に示したモニターセンターダイアログを開くボタンをクリックします。メニューの「ツール」の「モニターセンター」からも開くことができます。開いたダイアログの左上に登録されたモニターの一覧が表示されており、その横の「新規…」ボタンで新たなモニターを登録、「保存」ボタンで変更の保存、「削除」ボタンで登録の削除を行います。登録モニター一覧の下にある日付のようなリストは、選択中のモニターに対するキャリブレーションデータの一覧を示しています。簡単に言えばモニターのキャリブレーションとは、PC上では数値によって表されている色を、モニターが正確に表現できるように調整することです。キャリブレーションには専用のセンサーが必要なので、この本では扱いません。この本で作成する実験は、ブラウザでインターネット上のニュースの写真などを閲覧して、特に違和感を覚えない程度に色が表示できていれば問題なく実行できます。

.. _fig-open-monitor-center:

.. figure:: fig02/open-monitor-center.png
    :width: 80%
    
    モニターセンターのダイアログ。モニターの登録や削除、設定の変更などができます。右半分はセンサーを用いたキャリブレーション時に使用します。


モニターの寸法や観察距離を設定するには、モニターを選択して左下の「モニター情報」と書かれた枠内に数値を入力します。ここでは、新しいモニターを登録して設定を行うことにしましょう( :numref:`fig-set-monitor-info` )。登録モニター一覧の右の「新規…」をクリックしてください。モニターの名前を登録するダイアログが表示されるので、My Monitorと入力しておきます。OKをクリックすると、モニター一覧にMy Monitorという項目が追加されているはずです。My Monitorが選択されていることを確認して、左下の「モニター情報」という枠内の「スクリーンの観察距離 (cm)」、「解像度 (ピクセル; 水平, 垂直)」、「スクリーンの横幅 (cm)」に適切な値を入力します。 :numref:`fig-set-monitor-info` では :numref:`fig-basic-units` と同じ1920×1080pix、幅51.0cmのスクリーンを持つモニターを入力しています。皆さんは各自が使用しておられるモニターの数値を入力してください。PsychoPyでは画素の縦横の長さは同一として計算しているので、幅だけを入力すれば高さは解像度と幅から自動的に計算されます。観察距離は :numref:`fig-set-monitor-info` の例では57.3cmとしておきました。終了したら登録モニター一覧の「保存」をクリックして保存して、モニターセンターのダイアログを閉じてください。保存せずに閉じようとすると変更を保存するか尋ねられるので、保存しておきましょう。

.. _fig-set-monitor-info:

.. figure:: fig02/set-monitor-info.png
    :width: 80%
    
    モニターの登録手順。

モニターの登録が終わったら、実験設定ダイアログを開いて「スクリーン」のページの「モニター」にMy Monitorと入力しましょう。そして、ルーチンペインにPolygonコンポーネントを配置し、 **[サイズ [w, h] $]** を[5, 5]、 **[空間の単位]** をcmにして実行してみましょう。正しく設定されていれば、一辺の長さ5cmの正方形のスクリーン上に表示されます。ぜひ定規で測って確認してください。刺激がすぐ消えてしまって測れないという方は、刺激の表示時間を長くしましょう。

確認ができたら、Polygonコンポーネントのプロパティ設定ダイアログを開いて **[空間の単位]** をdegにして実行しましょう。観察距離57.3cm (≒180/π)の時には、1degがほぼ1cmとなりますので、画面上ではやはり一辺約5cmの正方形が表示されているはずです。それを確認したらモニターセンターへ戻って、My Monitorの観察距離を30cmに変更してから実験を実行してみましょう。そうするとスクリーンに表示される正方形の一辺は5cmより短くなったはずです。観察距離が短くなると刺激は網膜に大きく映るので、視角5degにするためには刺激を縮小しなければいけません。この縮小作業をPsychoPyが自動的に行ってくれたのです。さらに観察距離30cmのままでPolygonコンポーネントを編集して **[空間の単位]** をcmに戻してみましょう。単位がcmの場合には、観察距離に関わらず常に一辺5cmの正方形が表示されるはずです。

これで準備は完了です。次章ではいよいよ最初の実験を作成してみましょう。

チェックリスト
    - モニターセンターを開くことができる。
    - モニターセンターに新しいモニターを登録することができる。
    - モニターの観察距離、解像度、スクリーン幅を登録することができる。


この章のトピックス
--------------------

.. _topic-coordinate-range:

スクリーン左下の座標についての厳密な議論(上級)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

本文では、(1920, 1080)の解像度を持つモニターで右上の座標は(960, 540)、左下の座標は(-960, -540)と述べました。しかし、じっくり考えてみれば変です。水平方向の解像度が10しかない小さな小さなモニターを考えてみましょう。10を半分にすると5ですから左端の座標を-5として、-4、-3…と数えていくと、10ピクセル目は5ではなく4です。したがって、このモニターの左端のX座標が-5なら右端のX座標は4でなければいけません。同じように、水平解像度が1920のモニターで左端のX座標を-960にしたのなら、右端は960ではなく959でなければならないのです。

コンピュータ上で符号付きの整数を扱う場合、一般的には負の数の方が絶対値が1大きくなるように範囲を定めます。しかし、筆者の実行環境(Windows10, Python x64, PsychoPy 3.0.5)で画面上に1×1ピクセルの刺激を描いて確認したところ、右上が(960, 540)、左下が(-959, -539)となり、正の方向に絶対値が1大きくなっていました。ただし、この結果はすべての実行環境、すべてのバージョンで保証されるとは限りませんので、参考程度にとどめてください。一般的な実験ではこの1ピクセルの差が問題となることはないと思われますので、本文ではこれ以降もスクリーンの中心を(0, 0)、解像度を2で割った値をスクリーン端の座標として記します。


.. _topic-visual-angle:

PsychoPyにおける視角の計算について
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

視角による視覚刺激の位置や大きさの表現は、視知覚の実験などでは欠かせないものです。本文中で述べた通り、PsychoPyでは視角による表現のためにdegという単位が用意されていますが、その実装は近似計算です。PsychoPy Coderを使うとPsychoPyに刺激の位置などの単位をdeg、pix、cmの間で相互に変換することができるのですが、それを利用して観察距離55cmのモニターで1.0degをcmに変換すると0.96cmという結果が得られます。これは55cm×tan(π/180)の計算結果と等しいです。同様にPsychoPyに10.0degをcmに変換させると、9.60cmという結果が得られます。一方、55cm×tan(10π/180)の計算結果は9.70cmとなり、9.60cmと一致しません。

これは、PsychoPyがdegをcmに変換する時に毎回三角関数の計算を行わずに、スクリーン中央から1.0degの位置をcmに変換した時の値をCとして、X degをcmに変換する時にはC×Xで近似計算しているために起きる現象です。Xが小さいときはとてもよい近似値が得られるのですが、画面の中央から遠ざかるほど誤差が大きくなります( :numref:`fig-constant-visual-angle` )。先の例では画面中央から10deg離れた位置で0.1cmしか異なりませんので、多くの実験では問題になることはないと思われます。

.. _fig-constant-visual-angle:

.. figure:: fig02/constant-visual-angle.png
    :width: 50%
    
    平面モニターを使う場合、視角を一定のまま刺激を端に移動させるとモニター画面上では刺激を大きくする必要があります。

しかし、極めて正確な刺激の描写が必要な実験や、最近増えてきた大型モニターを両端いっぱいまで使って刺激を描画するような実験では、この誤差が問題となる可能性があります。この問題に対応するために、PsychoPy 1.80ではdegより厳密な計算を行うdegFlat、degFlatPosという単位が追加されました。degFlatでは、図形の頂点座標を視角の定義通りに計算します。先ほどの観察距離55cmで10.0degの例でも正しく9.70cmという換算値が得られます。

defFlatPosはdegとdegFlatの中間のような計算で、図形の頂点座標はdegと同様に計算し、刺激を配置するときの位置のみを正確に計算します。degFlatとdegFlatPosの違いを図で示したのが :numref:`fig-degflat-triangles1-trim` です。この例ではdeg, degFlat, degFlatPosを用いて傾いた正三角形を(0.0, 0.0)の位置から(1.0, 0.5)ずつ動かしながら(24.0, 12.0)の位置まで描画しています。白がdeg、赤がdegFlat、青がdegFlatPosで描いたものです。degで描いた白い三角形はすべて同じ形で等間隔に並んでいます。一方、degFlatで描いた赤い三角形は、右上に向かうにつれて間隔が広がり、三角形は大きくなり形が歪んでいます。三角形の頂点座標をすべて視角の定義に基づいて計算しているのでこのような結果となります。それに対して青で描かれたdegFlatPosでは、三角形の間隔こそdegFlatと同様に右上に向かうにつれて広がっていますが、三角形の大きさや形状は一定のままです。これが「頂点座標はdegと同様に計算し、配置するときの位置のみを正確に計算する」という意味です。

.. _fig-degflat-triangles1-trim:

.. figure:: fig02/degflat-triangles1-trim.png
    :width: 80%
    
    deg(白)、degFlat(赤)、degFlatPos(青)の違い。


.. _topic-change-font:

Builderの設定ダイアログで用いられるフォント
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

PsychoPy Builderの標準のフォント設定では、実行環境によっては **[位置 [x, y] $]** のような $ が付くプロパティ値の小数点とカンマが非常に見分けにくいです。例えば、かつてWindows10では :numref:`fig-change-code-font` のようにカンマが非常に小さく表示されてしまい、小数点と見間違えることがありました。PsychoPyのウィンドウ上部のメニュー「ファイル」の「設定」を選び、表示されるダイアログの「Coder」タブをクリックして、「コード用フォント」や「コード用フォントサイズ」を変更すると見やすくなります。見分けにくくて苦労している人はぜひ試してください。

.. _fig-change-code-font:

.. figure:: fig02/change-code-font.png
    :width: 70%
    
    コード用フォントの変更。

.. _topic-mac-font:

Mac上で日本語の文字が欠けてしまう場合の対策
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

MacOSでは日本語フォントの仕様がしばしば変更されるようで、Textコンポーネントでの日本語の表示が乱れてしまう現象が度々生じています。ほとんどの場合、「書式」タブの **[フォント]** に適切なフォント名を指定すると解決します。残念ながら「こう書いたら必ず解決する」という表記方法はないのですが、「游ゴシック体」のような日本語でのフォント名か、「Hiragino Sans」のような英語でのフォント名を指定すると解決するケースが多いです。

.. _topic-hexadecimal-color-value:

16進数と色表現
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

私たちが普段使い慣れている数は10進数でしょう。10進数では0、1、2、3、…と値が増加して、9の次の整数は桁がひとつ上がり1の位は0に戻って「10（イチゼロ）」と表記されます。同様に考えると、例えば8進数とは7の次の整数になるときに桁がひとつ上がって1の位が0に戻る表記だということになります。0から10までの整数を8進数で書くと0、1、2、3、4、5、6、7、10（イチゼロ）、11（イチイチ）、12（イチニ）…となります。最後の10（イチゼロ）、11（イチイチ）、12（イチニ）は10進数の8、9、10に対応しています。

頭がこんがらがってきますが、同様に16進数の表記を考えてみると困ったことが起きます。0、1、2、…、9と来て、その次の整数を示す文字がアラビア数字には無いのです。仕方がないので、多くのプログラミング言語では9の次の整数を示す文字としてアルファベットのA、さらにその次の整数を表す整数としてB、という具合にアルファベットを割り当てます。この調子でアルファベットを使っていくと、10進数の15がFとなり、10進数の16が10となって16進数表記が完成します。Pythonでは、「10」と書かれた時に10進数の10を表しているのか16進数の16を指しているのかを区別するために、16進数表記の数には先頭に「0x」を付けることになっています。つまり、ただ「10」と書いてあれば10進数の10であり、「0x10」と書いてあれば16進数の16というわけです。

さて、なぜwebカラーによる色の表現に16進数が用いられるかということですが、webカラーでは赤、緑、青(RGB: Red, Green, Blue)の光の強度をそれぞれ0から255の256段階で指定するからです。例えばRGBをそれぞれ100段階(0から99)で変化させられる機械があるとすると、6桁の10進数を用いて左から1桁目と2桁目をR、3桁目と4桁目をG、5桁目と6桁目にBを割り当てれば、この機械で使用できる色を6桁の10進数の数値としてわかりやすく表現することができます。この割り当て方法を6桁の16進数に適用すると、左側から2桁ずつ16進数の値をR、G、Bに割り当てる形になります。2桁の16進数というと0x00から0xFFですが、この範囲を10進数に換算すると0から255になりますので、RGBの各成分が256段階となる機械にとって16進数による表現は非常に相性がよいはずです。

具体的な数値で考えてみましょう。赤色は左の2桁の数値が10進数の255に対応する16進数0xFFで、残りの桁は0となります。すなわち、0xFF0000です。同様に、緑色は0x00FF00、青色は0x0000FFです。黄色の場合は、赤と緑の混色ですから赤に対応する桁と緑に対応する桁が0xFFで青に対応する桁が0である値、すなわち0xFFFF00です。これらの色に対応する値を10進数で表記すると、赤が16711680、緑は65280、青は255、黄色は16776960です。RGBの各成分を256段階で表現する機械においては、10進数表記より16進数表記の方がはるかに直感的にRGBの強度が把握しやすいことがお分かりいただけるのではないかと思います。

なお、Pythonでは数値が16進数表記であることを示すために0xを先頭に付けますが、webページを記述するのに用いられるHTMLという言語では#FF0088のように先頭に「#」を付けて16進数を示します。PsychoPyの色指定では「0x」も「#」も両方使用することができます。HTMLではRGBのそれぞれに2桁ではなく1桁の16進数を割り当てて、#7FAのように3桁の16進数で色を表現することもできます。PsychoPyはこの表現もサポートしています。3桁の16進数が与えられた場合、PsychoPyは内部で例えば#7FAを#70F0A0にするという具合に0を挿入することで6桁の表現に変換します。


.. _topic-start-stop-by-frame:

時刻指定におけるframeについて
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ご存知の方も多いと思いますが、PCのモニターは1秒間に数十回も静止画をスクリーンに表示することによって滑らかな動きを表現しています。モニターがスクリーンを1秒間に書き換える回数をリフレッシュレートと呼びます。リフレッシュレートの単位はHzです。一般的なPC用モニターのリフレッシュレートは60Hz前後です。60Hzのモニターであれば、1秒間に60回の書き換えを行います。高速に書き換えられる個々の静止画をフレームと呼びますが、このフレームという用語を用いると60Hzのモニターは1秒間に60フレームを表示するという事もできます。フレームの書き換え間隔は一定ですので、1フレームの表示時間は1秒÷60回=0.0166...秒、四捨五入して16.7ミリ秒です。

16.7ミリ秒に1度しか書き換えが行われないということは、例えばBuilderで刺激の表示時間を設定する際に **[終了]** で「実行時間 (秒)」を選択して0.04 (=40ミリ秒)を入力しても、40ミリ秒は16.7ミリ秒の整数倍ではないので、実際に刺激が表示されている時間は40ミリ秒にはならないということです。Builderと60Hzのモニターを用いて実際に動作確認してみると、「実行時間 (秒)」が0.04の時には33.3ミリ秒しか刺激は提示されていません(PsychoPy 1.79.01で確認)。33.3ミリ秒は2フレームに相当します。刺激提示開始時刻や終了時刻、提示時間は1ミリ秒(もしくはそれ以下の)単位で指定できますが、実質的にはフレーム単位でしか制御できていないのです( :numref:`fig-time-frame` )。言い換えると、刺激の提示時間としてフレームの表示時間の倍数を指定した時以外は、設定した時間と実際に表示されている時間の間には必ずズレが生じているのです。

.. _fig-time-frame:

.. figure:: fig02/time-frame.png
    :width: 80%
    
    提示時間がフレーム表示時間の倍数になっていなければ指定した時間と実際の提示時間の間にずれが生じます。

どうせフレーム表示時間の倍数でしか正確に刺激提示時間を指定できないのでしたら、いっそのこと秒単位ではなくフレーム数で刺激提示時間を指定した方がわかりやすいという考え方もあるでしょう。フレーム数による指定を可能にするのがプロパティ設定ダイアログの **[終了]** で選択できる「実行時間 (フレーム数)」という選択肢です。「実行時間 (フレーム数)」を選択すると、指定された数のフレームを表示する間刺激を提示します。当然、正の整数を指定しなければ意味がありません。同様に **[開始]** 、 **[終了]** でともに選択できる「フレーム数」を用いるとルーチンが開始されてから何フレーム目に刺激提示を開始、終了するかを指定することができます。100ミリ秒未満の短時間の刺激を提示する場合や、特に正確な提示時間の制御が必要な実験をする場合はフレームによる指定が有効です。

.. _fig-set-expected-time:

.. figure:: fig02/set-expected-time.png
    :width: 80%
    
    フレームで刺激の提示時間を指定するとルーチンペイン上で提示時間を示す青い棒が表示されません。  **[予想開始時刻 (s)]** 、 **[予想実行時間 (s)]** に見積もり値を入力することでルーチンペイン上に提示時間を表示することができます。

なお、フレームで刺激提示時間を指定すると、ルーチンペインの青い棒が表示されなくなってしまいます。Builderは実験に使用されるモニターのリフレッシュレートを知らないので、何秒から何秒まで刺激が提示されているかを計算することができないのです。このままではルーチンペインを見たときに刺激がどのような順番に提示されていくのか非常にわかりづらいので、Builderには「この時刻からこの時刻まで提示される」という目安を表示させる機能があります。PolygonコンポーネントやTextコンポーネントを配置してプロパティ設定ダイアログを確認してください。灰色の文字で **[開始]** の下に  **[予想開始時刻 (s)]** 、 **[終了]** の下に **[予想実行時間 (s)]** と書かれた項目があります。ここに開始時刻と提示時間の見積もりをそれぞれ入力すると、見積もりに従って青い棒が表示されます( :numref:`fig-set-expected-time` )。見積もり値は、各自で使用しているモニターのリフレッシュレートと指定したフレーム数から計算する必要があります。ちなみに「時刻 (秒)」や「実行時間 (秒)」を選択している時にもこれらの見積もりを入力することができますが、混乱を招くだけで意味はありません。

蛇足ですが、リフレッシュレートと非常によく似た用語でフレームレートというものがあります。フレームレートの単位はframes per secondの略でFPSです。「1秒あたりのフレーム数」という意味ですから、リフレッシュレートと同じ意味のように思えます。しかし、フレームレートという用語は通常「PCがモニターに対して1秒間に表示するように要求したフレーム数」を指します。フレームレートが100FPSに達しても、使用しているモニターのリフレッシュレートが60Hzであれば1秒間に実際に表示されるフレーム数は60枚です。間違えやすいのでご注意ください。