RatingScale

class psychopy.visual.RatingScale(win, scale='<default>',
    choices=None,low=1, high=7, precision=1, labels=(), tickMarks=None,
    tickHeight=1.0, marker='triangle', markerStart=None, markerColor=None,
    markerExpansion=1, singleClick=False, disappear=False, textSize=1.0,
    textColor='LightGray', textFont='Helvetica Bold', showValue=True,
    showAccept=True, acceptKeys='return', acceptPreText='key, click',
    acceptText='accept?', acceptSize=1.0, leftKeys='left',
    rightKeys='right', respKeys=(), lineColor='White', skipKeys='tab',
    mouseOnly=False, noMouse=False, size=1.0, stretch=1.0, pos=None,
    minTime=0.4, maxTime=0.0, flipVert=False, depth=0, name=None,
    autoLog=True, **kwargs)

画面上に尺度を設置し、反応を記録するクラウである。例えば1から7までの7段階の尺度やカテゴリカルな尺度などを作成できる。

RatingScaleのインスタンはdraw()メソッドを持つ視覚刺激オブジェクトであり、外見のカスタマイズや反応計測についてのオプションを有している。draw()は尺度の描画のみならず、マウスまたはキーボードを用いた実験参加者の反応の計測、および尺度の状態に応じた外見の更新も行う。参加者が選択肢を決定(訳注：原文はaccept)すると、データ属性noResponseの値がFalseとなる。

getRating()を利用すると現在選択されている項目を取得することが出来る。getRT()で反応時間、getHistory()で参加者の操作履歴を(項目, 反応時間)のタプルのリストととして得ることが出来る。

RatingScaleには5つの主要な要素がある。

• 説明文(訳注：原文ではscale)：線の上部に表示するテキスト。反応時の注意事項のリマインダ等を表示する。
• 線：目盛り付きの線。
• マーカー：線上を動かすことが出来る指標。
• ラベル：線の下部に書かれるテキスト。項目のラベル。
• 決定ボタン(訳注：原文ではaccept button)：決定時にクリックするボタン。

これらの要素の見た目と機能はカスタマイズ可能だが、垂直方向にすることは出来ない。複数の尺度を同時に画面上に配置し、履歴を使って評定値の変化をリアルタイムに追跡することが可能である。

PsychoPy BuilderのRatingScaleコンポーネントでカスタマイズできるパラメータは限られているが、’customize_everything’(訳注：Builderで言語を日本語に設定している場合は「全てをカスタマイズ」)という項目を利用するとすべてのパラメータをカスタマイズできる。 RatingScaleは画面上に表示している尺度そのもの以外については何も関与しない。従って、評定される刺激を描画したり、反応を中断して次の試行へ進んだり実験を終了したりする処理は実験者がコーディングしなければならない。実験参加者はマウス又はキーボードを用いて反応することが出来る。矢印キー(左, 右)でマーカーが最小ステップ(例えばprecision=10ならば目盛の1/10)動く。

# 例1：基本的な7段階尺度:

ratingScale = visual.RatingScale(win) # デフォルト値は7段階尺度
item = visua.ImageStim(win, file='stim.jpg') # 評定する刺激
while ratingScale.noResponse:
    item.draw()
    ratingScale.draw()
    win.flip()
rating = ratingScale.getRating()
decisionTime = ratingScale.getRT()
choiceHistory = ratingScale.getHistory()

# 例2：fMRI実験などで、使用しているキーボックスが1-4のキー押し
#      しか送信できないとする。これらの4つのキーにマーカーの
#      左移動(1)、右移動(2)、決定(4)を割り当てる。

ratingScale = visual.RatingScale(
    win, low=1, high=5, markerStart=4,
    leftKeys='1', rightKeys = '2', acceptKeys='4')

# 例3：カテゴリカルな尺度

ratingScale = visual.RatingScale(
    win, choices=['agree', 'disagree'],
    markerStart=0.5, singleClick=True)

その他の例はCoderのデモのratingScale.py参照。

パラメータ	解説
win	刺激を描画するウィンドウオブジェクト(必須)
choices	選択肢のリスト。このパラメーターはlow, high, precision, scale, labels, tickMarksより優先される。
low	尺度の最低値(整数)。デフォルト値は1。
high	尺度の最高値(整数)。デフォルト値は7。
precision	1, 10, 60または100。デフォルト値は1。マーカーを左右に動かすキーを1回押すたびに評定値が変化する大きさを 決定する。1ならば1目盛ずつ、10ならば1目盛の1/10ずつである。precision=60は時間を評定する場合を想定して 用意されたもので、1目盛を1分として秒単位(あるいは1目盛1時間で分単位)でマーカーを移動させる。画面上では 「分：秒」「時：分」のようにコロンを用いて表示される。getRating()の戻り値は1:30ならば1.5, 0:59ならば 0.98333 (=59/60)のように小数となる。(訳注：目盛の間隔が1でprecision=10ならば小数点1桁まで、precision=100 なら小数点2桁まで記録できるという事である。整数以外の値または10未満の整数を指定すると1、100未満で60以外の 値を指定すると10、100以上の値を指定すると100に強制的に設定される。1.85.0のソースコードにて確認。)
scale	尺度の上部に表示する文字列。デフォルト値は’<low>=not at all, <high>=extremely’。何も表示したくない場合は Noneにする。
labels	目盛の下に表示させたいラベルを指定する。要素数2のシーケンスの場合は両端、要素数3のシーケンスの場合は 両端と中央、目盛数と同じ場合は全ての目盛にラベルを付ける。
tickMarks	(lowとhighの間で)目盛を置く位置を指定する。デフォルトでは範囲内の全ての整数の位置に目盛が置かれる。
tickHeight	目盛線の高さを指定する。デフォルト値は1.0である。-1.0ならばデフォルトと同じ高さで下向き、0.0ならば 目盛線が表示されない。このパラメータは純粋に見かけを調節するものである。
marker	現在選択している項目を示すマーカーを指定する。’triangle’, ‘circle’, ‘glow’, ‘slider’, ‘hover’, 視覚刺激 オブジェクトのいずれかである。選択できる値を十分に多くすれば、滑らかに動くマーカーを実現することが出来る (例えばlow=0, high=100)。’hover’は引数choiceを用いてカテゴリカルな尺度を作成し、個々の選択肢を直接 クリックできる場合にのみ使用できる。’hover’でカーソルを選択肢に重ねている時間帯は記録されない。 draw()メソッドと属性posを持つ視覚刺激オブジェクトを指定すると、マーカーとして使用できる。
markerStart	マーカーの初期位置を数値または選択肢で指定する。小数を指定して二つの選択肢の中央にマーカーを置くことも 可能である。
markderColor	マーカーの色を指定する。
markerExpansion	markerで’glow’を選択した場合のみ有効なパラメータである。右側へマーカーを動かすにつれてマーカーが大きくなる 量を指定する。0ならばマーカーを動かしても変化しない。負の値ならば右側へ動かすにつれてマーカーは小さくなる。
singleClick	Trueにすると一度項目をクリックすると反応が確定される。デフォルト値はFalseである。キー押しでの反応も直ちに 確定される。決定ボタンは表示されているが、クリックしても何も起こらない。
pos	X座標、Y座標を組にしたシーケンスで、尺度のスクリーン上の位置を指定する。単位はnormである。デフォルト値は (0.0, -0.4)である。
size	尺度の大きさを指定する。他の視覚刺激オブジェクトのsizeと異なり、相対的な大きさで指定する。デフォルト値は 1.0で、大きくしたい時には1.0より大きな、小さくしたい時には1.0より小さな値にする。
stretch	sizeと同様だが、水平方向の広がりを調整する。
textSize	文字の大きさを指定する。sizeと同様に相対値で指定する。
textColor	labelsとscaleの文字色を指定する。デフォルト値は’LightGray’である。
textFont	使用するフォント名を指定する。デフォルト値は’Helvetica Bold’である。
showValue	現在選択している値を表示する。デフォルト値はTrueである。singleClickがTrueの場合はこの設定は無視される。
showAccept	マウスでクリックするための決定ボタンを表示する。デフォルト値はTrueである。
acceptPreText	決定ボタンに最初に表示する文字列を指定する。
acceptText	選択肢を決定した後に決定ボタンに表示する文字列を指定する。
acceptSize	決定ボタンの横幅を相対値で指定する。例えば2.0ならば2倍になる。
acceptKeys	キーボードで選択を決定する際に使用するキーを指定する。デフォルト値は’return’である。
leftKeys	マーカーを左へ動かすキーを指定する。デフォルト値は’left’である。
rightKeys	マーカーを右へ動かすキーを指定する。デフォルト値は’right’である。
respKeys	直接選択肢を指定するキーを(キー名を並べたシーケンスとして)指定する。最初の要素は左端を選択するキー、 第2の要素はその次を選択するキー、という具合である。
skipKeys	参加者が反応をスキップする時に使用するキーを指定する。デフォルト値は’tab’である。スキップを許可しない場合は Noneを指定する。
lineColor	線の色を指定する。デフォルト値は’White’である。
mouseOnly	Trueにするとマウスのみを反応に使用する。デフォルト値はFalseである。
noMouse	Trueにするとキーボードのみを反応に使用する。マウスは無効化されカーソルは隠される。markerStartは左端に 設定される。
minTime	反応できるようになるまでの時間を指定する。デフォルト値は0.4である。
maxTime	反応できなくなるまでの時間を指定する。maxTimeがminTime以下の場合は無制限になる。デフォルト値は0.0 (すなわち無制限)である。
disappear	反応確定後に尺度を非表示にするか否かを指定する。
flipVert	尺度の向きを垂直方向に反転する。

acceptResponse(triggeringAction, log=True)

操作と反応を記録する。

(訳注：内部で利用される関数で、一般ユーザーが使う必要はないと思われる)

getHistory()

履歴を選択項目と時刻のタプルを並べたリストとして返す。

履歴は任意の時点で取得することが可能であり、連続的な評定をリアルタイムで取得することが出来る。

getRT()

評定を決定するかスキップするまでに要した時間を返す。

選択項目が取得できない場合やmaxTimeを過ぎてしまった場合はNoneが返される。まだ選択を決定していない場合は経過時間が返される。 .. Returns the seconds taken to make the rating (or to indicate skip).

getRating()

最終的な、決定ボタンまたはキーによって確定された値、または現在選択されている値を返す。

反応がスキップされた場合はNoneとなる。maxTimeを超えてしまった場合やまだ選択項目が取得できない場合も同様である。まだ選択が決定されていない場合は現在選択されている値が返される。最初の選択項目はmarkserStartの値によって決定される。

reset(log=True)

RatingScaleオブジェクトを初期化直後の状態にリセットする。

履歴は消去され、データ属性statusがNOT_STARTEDに設定される。scaleに設定した文字列は復元されないので注意。

(訳注：scaleの文字列を復元するにはsetDescription(None)を実行する。setDescription()参照。)

setDescription(scale=None, log=True)

scaleに設定した文字列を再設定する。

ひとつのRatingScaleオブジェクトを用いて複数の次元について評定させる時に便利である。引数scaleにNoneを指定すると初期状態に戻る。非表示にする場合は空白文字を設定する。

setFlipVert(newVal=True, log=True)

尺度を乗て反転するか否かを設定する。

setMarkerPos(tick)

マーカーを指定した位置へ移動する。位置は左端の項目を0とするインデックスで指定する。インデックスの範囲が適切であるかチェックしないので注意すること。

変数rsにRatingScaleオブジェクトが格納されているとして、以下のように新たな位置を直接指定できる。

rs.setMarkerPos(2)

インデックスの範囲とprecisionの設定を確認して設定するには以下のようにする。(訳注：_から始まる関数は通常内部的に使用するものであり、APIリストに表示されていない)

rs.setMarkerPos(rs._getMarkerFromTick(2))

マウスのX座標のようなスクリーン座標から設定するには以下のようにする。

rs.setMarkerPos(rs._getMarkerFromPos(mouseX))