RatingScale
=====================================

.. code-block:: python

    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)動く。

.. code-block:: python

    # 例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参照。


.. A class for obtaining ratings, e.g., on a 1-to-7 or categorical scale.

.. A RatingScale instance is a re-usable visual object having a draw() method, with customizable appearance and response options. draw() displays the rating scale, handles the subject’s mouse or key responses, and updates the display. When the subject accepts a selection, .noResponse goes False (i.e., there is a response).

.. You can call the getRating() method anytime to get a rating, getRT() to get the decision time, or getHistory() to obtain the entire set of (rating, RT) pairs.

.. There are five main elements of a rating scale: the scale (text above the line intended to be a reminder of how to use the scale), the line (with tick marks), the marker (a moveable visual indicator on the line), the labels (text below the line that label specific points), and the accept button. The appearance and function of elements can be customized by the experimenter; it is not possible to orient a rating scale to be vertical. Multiple scales can be displayed at the same time, and continuous real-time ratings can be obtained from the history.

.. The Builder RatingScale component gives a restricted set of options, but also allows full control over a RatingScale via the ‘customize_everything’ field.

.. A RatingScale instance has no idea what else is on the screen. The experimenter has to draw the item to be rated, and handle escape to break or quit, if desired. The subject can use the mouse or keys to respond. Direction keys (left, right) will move the marker in the smallest available increment (e.g., 1/10th of a tick-mark if precision = 10).

.. Example 1:

..     A basic 7-point scale:

..     ratingScale = visual.RatingScale(win)
..     item = <statement, question, image, movie, ...>
..     while ratingScale.noResponse:
..         item.draw()
..         ratingScale.draw()
..         win.flip()
..     rating = ratingScale.getRating()
..     decisionTime = ratingScale.getRT()
..     choiceHistory = ratingScale.getHistory()

.. Example 2:

.. For fMRI, sometimes only a keyboard can be used. If your response box sends keys 1-4, you could specify left, right, and accept keys, and not need a mouse:

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

.. Example 3:

..     Categorical ratings can be obtained using choices:

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

.. For other examples see Coder Demos -> stimuli -> ratingScale.py.
.. Authors:	

..     2010 Jeremy Gray: original code and on-going updates
..     2012 Henrik Singmann: tickMarks, labels, ticksAboveLine
..     2014 Jeremy Gray: multiple API changes (v1.80.00)

=============== ============================================================================================================
パラメータ      解説
=============== ============================================================================================================
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        尺度の向きを垂直方向に反転する。
=============== ============================================================================================================

.. Parameters:

.. win :
..     A Window object (required).
.. choices :
..     A list of items which the subject can choose among. choices takes precedence over low, high, precision, scale, labels, and tickMarks.
.. low :
..     Lowest numeric rating (integer), default = 1.
.. high :
..     Highest numeric rating (integer), default = 7.
.. precision :
..    Portions of a tick to accept as input [1, 10, 60, 100]; default = 1 (a whole tick). Pressing a key in leftKeys or rightKeys will move the marker by one portion of a tick. precision=60 is intended to support ratings of time-based quantities, with seconds being fractional minutes (or minutes being fractional hours). The display uses a colon (min:sec, or hours:min) to signal this to participants. The value returned by getRating() will be a proportion of a minute (e.g., 1:30 -> 1.5, or 59 seconds -> 59/60 = 0.98333). hours:min:sec is not supported.
.. scale :
..    Optional reminder message about how to respond or rate an item, displayed above the line; default = ‘<low>=not at all, <high>=extremely’. To suppress the scale, set scale=None.
.. labels :
..    Text to be placed at specific tick marks to indicate their value. Can be just the ends (if given 2 labels), ends + middle (if given 3 labels), or all points (if given the same number of labels as points).
.. tickMarks :
..    List of positions at which tick marks should be placed from low to high. The default is to space tick marks equally, one per integer value.
.. tickHeight :
..    The vertical height of tick marks: 1.0 is the default height (above line), -1.0 is below the line, and 0.0 suppresses the display of tickmarks. tickHeight is purely cosmetic, and can be fractional, e.g., 1.2.
.. marker :
..    The moveable visual indicator of the current selection. The predefined styles are ‘triangle’, ‘circle’, ‘glow’, ‘slider’, and ‘hover’. A slider moves smoothly when there are enough screen positions to move through, e.g., low=0, high=100. Hovering requires a set of choices, and allows clicking directly on individual choices; dwell-time is not recorded. Can also be set to a custom marker stimulus: any object with a .draw() method and .pos will work, e.g., visual.TextStim(win, text='[]', units='norm').
.. markerStart :
..    The location or value to be pre-selected upon initial display, either numeric or one of the choices. Can be fractional, e.g., midway between two options.
.. markerColor :
..    Color to use for a predefined marker style, e.g., ‘DarkRed’.
.. markerExpansion :
..    Only affects the glow marker: How much to expand or contract when moving rightward; 0=none, negative shrinks.
.. singleClick :
..     Enable a mouse click to both select and accept the rating, default = False. A legal key press will also count as a singleClick. The ‘accept’ box is visible, but clicking it has no effect.
.. pos: tuple (x, y)
..     Position of the rating scale on the screen. The midpoint of the line will be positioned at (x, y); default = (0.0, -0.4) in norm units
.. size :
..    How much to expand or contract the overall rating scale display. Default size = 1.0. For larger than the default, set size > 1; for smaller, set < 1.
.. stretch:
..    Like size, but only affects the horizontal direction.
.. textSize :
..    The size of text elements, relative to the default size (i.e., a scaling factor, not points).
.. textColor :
..    Color to use for labels and scale text; default = ‘LightGray’.
.. textFont :
..    Name of the font to use; default = ‘Helvetica Bold’.
.. showValue :
..    Show the subject their current selection default = True. Ignored if singleClick is True.
.. showAccept :
..    Show the button to click to accept the current value by using the mouse; default = True.
.. acceptPreText :
..    The text to display before any value has been selected.
.. acceptText :
..    The text to display in the ‘accept’ button after a value has been selected.
.. acceptSize :
..    The width of the accept box relative to the default (e.g., 2 is twice as wide).
.. acceptKeys :
..     A list of keys that are used to accept the current response; default = ‘return’.
.. leftKeys :
..    A list of keys that each mean “move leftwards”; default = ‘left’.
.. rightKeys :
..     A list of keys that each mean “move rightwards”; default = ‘right’.
.. respKeys :
..    A list of keys to use for selecting choices, in the desired order. The first item will be the left-most choice, the second item will be the next choice, and so on.
.. skipKeys :
..    List of keys the subject can use to skip a response, default = ‘tab’. To require a response to every item, set skipKeys=None.
.. lineColor :
..    The RGB color to use for the scale line, default = ‘White’.
.. mouseOnly :
..    Require the subject to use the mouse (any keyboard input is ignored), default = False. Can be used to avoid competing with other objects for keyboard input.
.. noMouse:
..    Require the subject to use keys to respond; disable and hide the mouse. markerStart will default to the left end.
.. minTime :
..    Seconds that must elapse before a response can be accepted, default = 0.4.
.. maxTime :
..    Seconds after which a response cannot be accepted. If maxTime <= minTime, there’s no time limit. Default = 0.0 (no time limit).
.. disappear :
..     Whether the rating scale should vanish after a value is accepted. Can be useful when showing multiple scales.
.. flipVert :
..    Whether to mirror-reverse the rating scale in the vertical direction.


acceptResponse(triggeringAction, log=True)
-------------------------------------------------

操作と反応を記録する。

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

.. Commit and optionally log a response and the action.


getHistory()
----------------------------

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

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

.. Return a list of the subject’s history as (rating, time) tuples.

.. The history can be retrieved at any time, allowing for continuous ratings to be obtained in real-time. Both numerical and categorical choices are stored automatically in the history.

getRT()
----------------------------

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

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

.. Returns None if no rating available, or maxTime if the response timed out. Returns the time elapsed so far if no rating has been accepted yet (e.g., for continuous usage).

getRating()
--------------------

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

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

.. Returns the final, accepted rating, or the current value.

.. The rating is None if the subject skipped this item, took longer than maxTime, or no rating is available yet. Returns the currently indicated rating even if it has not been accepted yet (and so might change until accept is pressed). The first rating in the list will have the value of markerStart (whether None, a numeric value, or a choice value).

reset(log=True)
-----------------------

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

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

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

.. Restores the rating-scale to its post-creation state.

.. The history is cleared, and the status is set to NOT_STARTED. Does not restore the scale text description (such reset is needed between items when rating multiple items)

setDescription(scale=None, log=True)
---------------------------------------------------

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

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

.. Method to set the brief description (scale).

.. Useful when using the same RatingScale object to rate several dimensions. setDescription(None) will reset the description to its initial state. Set to a space character (‘ ‘) to make the description invisible.

setFlipVert(newVal=True, log=True)
----------------------------------------------------

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

.. Sets current vertical mirroring to newVal.

setMarkerPos(tick)
----------------------------------------------------

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

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

.. code-block:: python

    rs.setMarkerPos(2)

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

.. code-block:: python

    rs.setMarkerPos(rs._getMarkerFromTick(2))

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

.. code-block:: python

    rs.setMarkerPos(rs._getMarkerFromPos(mouseX))

.. Method to allow the experimenter to set the marker’s position on the scale (in units of tick marks). This method can also set the index within a list of choices (which start at 0). No range checking is done.

.. Assuming you have defined rs = RatingScale(...), you can specify a tick position directly:

.. rs.setMarkerPos(2)

.. or do range checking, precision management, and auto-rescaling:

.. rs.setMarkerPos(rs._getMarkerFromTick(2))

.. To work from a screen coordinate, such as the X position of a mouse click:

.. rs.setMarkerPos(rs._getMarkerFromPos(mouseX))