psyinfr

psyinfrは心理学のインフラツールとなることを目的としたRパッケージです。

インストール方法

以下の方法でGitHub経由でインストールができます。

# install.packages("remotes")
# remotes::install_github("ykunisato/psyinfr")
install.packages("psyinfr", repos = c('https://ykunisato.r-universe.dev', 'https://cloud.r-project.org'))

使用方法

使用準備

psyinfrはrstudioとgithubの利用が前提となっていますので，rstudioとgithubアカウントを作成してください。githubでプライベートアカウントを作って，rstudioで使えるようにしてください。

Research Compendiumの準備

以下を実行すると，研究に必要なファイルとフォルダを用意するResearch Compendiumが作られます。

psyinfr::set_rc()

研究ルーティン関数

その日の研究の開始時に以下の関数を実行すると，GitHubのリポジトリからプルを行った上で，ラボノートを作成します。ラボノートは自動で開きますので，適宜メモをとりながら研究を実施して，適宜knitをしてください。

psyinfr::researchIn()

その日の研究の終了時に以下の関数を実行すると，ラボノートを保存した上で，変更加えたファイルにコミットを加えた上で，GitHubに自動的にプッシュします。

psyinfr::researchOut()

日々の研究は，researchIn()で初めて，researchOut()で終わります。なお，バックアップ先がOSFが良い場合は，up2osf()も使えます。

jsPsych課題作成テンプレート(JATOS用)の準備

以下を実行すると、カレントワーキングディレクリーに認知課題名のフォルダを作成し，必要なjsPsych関連ファイルがダウンロードされます。特に設定をしなくても，その中にあるtask.jsファイルに書き込むだけでjsPsych課題が作成できます。

psyinfr::set_cbat("stroop", "8.2.2")

set_cbat()はversion 0.3.2からjsPsych課題作成テンプレートの提供をcbat4rパッケージに移管し、psyinfrはcbat4rの関数を再エクスポートする形になりました。それに伴い、旧use_rc引数はoutput_dir・add_root_dir引数に置き換わっています。

output_dir（デフォルト"."）　課題フォルダを作成する場所を指定します。
add_root_dir（デフォルトTRUE）　TRUEの場合はoutput_dir内に認知課題名のフォルダを作成し、その中にHTMLファイルとjsPsych関連ファイルがダウンロードされます。FALSEの場合はoutput_dir直下に配置されます。

旧use_rcとの対応は以下の通りです。

旧 use_rc = 1　→　set_cbat("stroop", "8.2.2") (output_dir = ".", add_root_dir = TRUE)
旧 use_rc = 2　→　set_cbat("stroop", "8.2.2", add_root_dir = FALSE)
旧 use_rc = 3　→　set_cbat("stroop", "8.2.2", output_dir = "exercise")（exerciseフォルダが存在している必要があります）

JATOSIFY

「jsPsych課題作成テンプレート(JATOS用)」で作成した課題のフォルダを作業用フォルダにコピーした上で、その作業用フォルダ内で以下のコードを実行すると、JATOSにアップロード可能なJZIPファイルを作れます。作業用フォルダにコピーしてから作業するのは、作用フォルダ内のフォルダとファイルを丸ごと圧縮するためです。 study_titleに実験（課題）名、html_file_listにjsPsych課題のHTMLのリスト（この順番でJATOS上の実験が行われます）,JATOS_versionにJATOSのバージョンを指定してください。

psyinfr::jatosify(study_title = "exp01", html_file_list = c("ic.html","age_gender.html","task01.html"), JATOS_version = "3.9")

Quarto Manuscriptsプロジェクトの準備

論文（paper.qmd）と解析ノートブックをひとまとめにしたQuarto Manuscriptsプロジェクトを作成します。

psyinfr::set_manuscript()

以下の構成のフォルダが作られます。paper.qmdはsenshuQmdテンプレートのものです。

manuscript/
  _quarto.yml
  paper.qmd            論文（senshuQmdテンプレート）
  bibliography.bib
  figures/
  _extensions/senshu/  senshu-pdf の書式定義
  notebooks/
    Analysis_01.qmd    解析ノートブック（psyinfr::readJatos()でデータを読み込む例）
    Data_collection.qmd データ収集ノートブック（cbat4rで調査を作る例）
  data/
    jatos_results_data_demo.txt  動作確認用のデモデータ（100名分）

dataフォルダにはJATOS形式のデモデータが入っており，Analysis_01.qmdがそれを読み込むようになっています。そのためプロジェクトを作った直後でもレンダーが通ります。自分のデータが集まったらdataフォルダに置いて，Analysis_01.qmdのファイル名を書き換えてください。

Data_collection.qmdのコードでcbat4rの課題を作ると，survey/surveyフォルダにできるデモ用HTML（demo_XXX.html）へのリンクが，レンダー時にData_collection.qmdのページ（Notebooks）へ自動で並びます。並び順はjatosify()のhtml_file_listに書いた順（参加者が課題を行う順）です。課題のフォルダは_quarto.ymlのresources:で出力にコピーされるので，リンク先のデモがそのまま動きます。課題をまだ作っていない場合は何も表示されません。

Analysis_01.qmdには，senshuQmdテンプレートと同じような解析の例（記述統計，相関，ヒストグラム，t検定と効果量，平均値の棒グラフ，クロス集計とカイ二乗検定，重回帰分析）と，その結果をpaper.qmdに埋め込む方法の解説が入っています。実行にはknitr，tidyverse，psych，jtools，ggsignif，effsizeが必要です。

レンダーには以下を使います。_manuscriptフォルダにウェブサイト（index.html）とPDF（paper.pdf）が出力され，ノートブックも一緒に公開されます。レンダーが成功するとindex.htmlがブラウザで開きます（開かないようにするにはopen = FALSEを指定します）。

psyinfr::render_manuscript("manuscript")

RStudioのRenderボタンはquarto previewを実行しますが，プレビューはプロジェクトの最初の書式（ウェブサイト）しかレンダーせず，PDFはダウンロードのリンクをクリックしたときに作られます。毎回PDFまで作りたい場合はrender_manuscript()（中身はquarto render）を使ってください。プレビューを見ながら書きたい場合はrender_manuscript("manuscript", preview = TRUE)とすると，全書式をレンダーした上でプレビューが立ち上がります。

出力形式は_quarto.ymlのformatで指定しています（そのためpaper.qmdのYAMLからはformat:の行を外してあります）。また，execute-dir: projectを指定しているので，ノートブックからもプロジェクト直下からの相対パス（data/...）でデータを読み込めます。

主な引数は以下の通りです。

project_name（デフォルト"manuscript"）　作成するプロジェクトのフォルダ名です。
output_dir（デフォルト"."）　プロジェクトを作成する場所を指定します。
add_root_dir（デフォルトTRUE）　FALSEにするとoutput_dir直下にファイルを配置します。
overwrite（デフォルトFALSE）　paper.qmdや_quarto.ymlが既にある場合は停止します。TRUEで上書きします。

JATOSの結果データの整形

JATOSからエクスポートした結果データ（1行が1コンポーネントのjsPsychデータになっているテキストファイル）を，Rで解析できる形に整形します。

d <- psyinfr::readJatos("jatos_results_data_20260809054431.txt")
d
#> <jatos_data>
#>   participants: 5
#>   tasks       : ic, qnr_mood, qnr_sleep, completion_code

以下の3つのデータフレームがリストで返ってきます。

d$trials　1行が1試行。rtやtrial_typeなどの試行レベルの変数がそのまま列になります。
d$long　1行が1つの回答項目（参加者×課題×試行×項目）。{"mood_1":1,"mood_2":0}のようなresponseがitemとvalueに展開され，数値に変換できるものはvalue_numにも入ります。
d$wide　1行が1参加者，1列が1項目。統計解析でよく使う形式です。

head(d$wide)
#>   workerID approval mood_1 mood_2 mood_3 sleep_1 sleep_2 sleep_3 ...
#> 1     1552 説明を...      1      0      1       0       2       1

主な引数は以下の通りです。

format（デフォルト"all"）　"trials", "long", "wide"を指定すると，そのデータフレームだけを返します。
id_col（デフォルト"workerID"）/ task_col（デフォルト"taskName"）　参加者と課題を識別する変数名を指定します。
extra_cols（デフォルトなし）　d$wideに加えたい試行レベルの列を指定します。例えばextra_cols = "id"とすると，完了コード（参加ID）の列が追加されます。
prefix（デフォルト"auto"）　d$wideの列名の付け方です。"auto"は課題間で重複する項目名（やresponse）にだけ課題名を付け，"always"は常に付け，"never"は付けません。
drop_cols（デフォルトなし）　d$trialsから落とす列を指定します。drop_cols = "stimulus"とするとHTMLの長い文字列を除けます。

psyinfr::readJatos("jatos_results_data_20260809054431.txt",
                   format = "wide", extra_cols = "id")

なお，1行ごとのテキスト形式だけでなく，ファイル全体がJSON配列の形式や，JATOSのメタデータ付きJSONエクスポートも読み込めます。メタデータ付きの場合はjatos_workerIdなどの列が追加されます。壊れている行はスキップして警告を出します。

Phase3用テンプレートの準備

以下のように，set_phaser("ゲーム名（英語）","Phaser3のバージョン")を実行すると，exerciseフォルダ内に指定したゲーム名のフォルダを作成し，必要なファイルを用意します(use_rc = FALSEにするとカレントディレクトリー内にフォルダを作ります)。ゲーム名.htmlを開くとデモ的なものがうごきます。ゲーム名のついたフォルダ内のtask.jsファイルを編集していくとゲーム作れます。

psyinfr::set_phaser("game1","3.80.1",use_rc = TRUE)

Research Compendiumを使わない場合は，以下の用にuse_rc = FALSEにします（デフォルトはTRUEです）。

psyinfr::set_phaser("game1","3.80.1",use_rc = FALSE)

なお，Phase3はローカルで動作確認する場合は，ローカルサーバーが必要です。Rでもservrパッケージで簡単にローカルサーバーがたてられるので，以下を実行して表示されたURLで動作確認ができます（RStudioのViewerで見れるので確認が楽です）。

servr::httd()

ローカルサーバーは以下で止められます。

servr::daemon_stop(1)

高負荷計算関数

負荷の高い計算をするために一時的に高スペックなPCやサーバーを使用する場合，解析が終了したら通知し，自動的にGitHubにアップされると便利です。そのために，まず，以下でgitとslackの設定をします（なお，slackはご自身でSlack APIの設定をされて，メッセージを送信するチャンネルとトークンが取得済みとします。また，RstudioにGitHubリポジトリをクローン済みとします）。

psyinfr::setGitSlack(git_name,git_email,slack_token,slack_channel)

上記の関数で，slackとgithubの設定ができたら，runHighLoad()で高負荷なRコードを書いたファイルを指定します。指定するRファイルは１つでも走りますが（Stanなどが想定されます），複数のファイルも指定できます。複数ファイルが指定されたら，parallel::parLapply()で並列化して実行します。計算がすべて終了したら，slackの設定したチャンネルに「2022/03/15 06:05 負荷の高い計算が終了しました。関連するファイルをコミットしてプッシュしました。」といったメッセージが送付され，リポジトリの更新されたファイルはコミットされて，プッシュされます。

psyinfr::runHighLoad(c("t1.R","t2.R","t3.R"))