Quartoで論文を書いて英文誌に投稿するまで (3) -- 本文執筆からPDF出力まで

[メタデータ記入からデータ埋め込みまで]()の続きです。
いよいよ論文本体を執筆していきます。

# Step 6. 本文を執筆する

Markdown 記法を使った論文執筆について、ここでは簡単に紹介します。

## 基本

- 「Method」といった見出しは、# の後に書く
- Level 2 (3) の見出しは、## (###) の後に書く
- 一文は改行せずに書き、ピリオドが現れたら改行する
- 段落を分けるときは、１行空ける

## 装飾

- 大文字： `**アスタリスク二つで囲む**`
- イタリック文字： `_アンダースコアで囲む_`
- 下付き文字： `~チルダで囲む~`
- 上付き文字： `^キャレットで囲む^`

## Tips

- 改ページするときは `{{< pagebreak >}}` と書く
- コメントアウトするときは `<!-- コメントアウトしたい文章 -->` と書く
- ギリシャ文字を書きたいときは、`${\chi}$` といったように書く


````paper.qmd
（略）
```{r}
source('in-render.R')
```

{{< pagebreak >}}

# Introduction

<!-- この文は論文に出力されない -->
This is the introduction.
Suggoku suggoku nagai bunsyo datta to shitemo, sorega ichibun nara, qmd file no naka deha, kaigyo sezuni kakuto iiyo.

<!-- 段落ごとの１行要約を日本語で書いとくのがオススメ -->
Konna fuu ni, 1 gyo akeruto, kai-danraku atsukai ni naruyo.

<!-- 装飾について -->
Sousyoku mo kantan.
**Bold** toka, _Italic_ mo kantan dashi, _p_~unc.~ toka ${\chi}$^2^ mitai na no mo rakusyo.

## Aim

Konnna fuu ni, # wo kasaneru koto de midashi no level wo shitei suruyo.
````

とやると、↓のような PDF が生成されます。

![ss-pdf1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/304493/93718e30-a6fe-4bbe-a4a7-501749aadfd2.png)

## 引用

- `bibliography.bib` にある論文情報のうち、citation key を記載して引用する
- ( ) 内にひとつ論文を挙げるなら `[@Dirac1953888]` といったように、`[@]` を用いて記載する
- ( ) 内に複数論文を挙げるなら `[@Dirac1953888; @Feynman1963118]` といったように、`;` を使って併記する
- ( ) を使わずに論文を挙げるなら、`@Dirac1953888` といったように、`@` のみを用いて記載する
- 論文以外の情報と併記したいときは、`[Jouhou\; @Dirac1953888]` といったように、`\` でエスケープした `;` を用いて併記する
- 参考文献リストを載せたい位置には、`::: {#refs}  :::`と記載する

``` paper.qmd
## Previous research

The bibliography.bib includes two articles [@Dirac1953888; @Feynman1963118].
However, I've never read them.
Is the @Feynman1963118 a review article?
The other paper seems to propose the famous calculation method [Lorents transformation\; @Dirac1953888].

# References

::: {#refs}
:::

```

↓

![ss-pdf2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/304493/0a7db2cd-a178-469f-8898-8835df62db3d.png)

# Step 7. データを本文に埋め込む

ここからが Quarto の本領発揮です。
`in-render.R` で読み込んだデータを、本文中に埋め込みます。
helper.R にある関数をガンガン使っていきます。

## 基本

以下のようにして埋め込みます。

```paper.qmd
# Method

We recruited `{r} n_subjects` participants to the experiment.
We used Python `{r} python_ver` and Pingouin-stat package `{r} pingouin_ver`.
```

↓

![ss-pdf3.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/304493/fef04904-1bb6-44c0-adea-3d97e2d3b118.png)

`in-render.R` の代わりに Python コードを使っている場合は、`{r}` の代わりに `{python}` から始めます。
ちょっと長くなってしまって見辛くなるので、R を使うのがオススメなのです。

## 小数点以下桁数を指定して埋め込む

私が作ったツールを使って、小数点以下桁数を指定しながら数値を埋め込みます。
以下のように書きます。

```paper.qmd
# Result

The mean and standard deviation are shown in @tbl-descriptive.

The correlation coefficient between Neuroticism and Openness was _r_ = `{r} nr$ngto(corr['open', 'r'])` (_p_ `{r} nr$p(corr['open', 'p.unc'])`.)
The scatter plot is shown in @fig-scatter.
The significant negative correlation was found between Neuroticism and Extraversion (_r_ = `{r} nr$ngto(corr['extra', 'r'])`, _p_ `{r} nr$p(corr['extra', 'p.unc'])`.)
All correlation coefficients are shown in @tbl-corr.
```

↓

![ss-pdf4.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/304493/9c3d8e24-49bf-40bd-9645-38aa2331fd3b.png)

`@tbl-...` とか `@fig-...` についてはのちほどご説明します。

このように、`nr$ngto()` や `nr$p()` などで変数を囲んでやれば、`in-render.R` の `NumRenderer()` 内で設定した桁数に丸めて埋め込まれます。
`abbr_ngto_head = TRUE` に設定していたので、頭の0が省略されます。
また、 `min_pval` を 0.001 に設定しているので、`nr$p()` が、自動的に 0.001 より小さい値を `< .001` 表記にしてくれます。

- `nr$ngto()`: `sdgt_not_greater_than_one` に設定した桁数で丸める
- `nr$perc()`: `sdgt_percent` に設定した桁数で丸める
- `nr$gen()`: `sdgt_general` に設定した桁数で丸める
- `nr$p()`: `sdgtpval` に設定した桁数で丸める

## 図を挿入する

以下のように書きます。

```paper.qmd
The scatter plot is shown in @fig-scatter.

{{< pagebreak >}}

# Figures

::: {#fig-scatter}
![](tex-source-files/fig_scatter.png)

Scatter plot between Neuroticism and Openness.
:::
```

すると、本文には
> The scatter plot is shown in Figure 1.

と、`@fig-scatter` が自動的にFigure 1 に置き換えられます。
Figure のほうは↓このように表示されます。

![ss-figure.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/304493/05a8a759-f3f4-4f71-ab40-70af0905b517.png)

`fig-scatter` の部分は、自由な文字列を設定できます。
図ごとに名前をつけてやりましょう。

## 表を挿入する

以下のように書くと、.csv を表として埋め込み、本文内で参照できます。

````paper.qmd
The mean and standard deviation are shown in @tbl-descriptive.
# Tables

{{< pagebreak >}}

```{r}
#| label: tbl-basic
#| tbl-cap: "Average and standard deviation of scores"
desc
```
````

![ss-table.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/304493/4ad22287-845b-4416-a030-067c97343415.png)

`desc` というのは、`in-render.R` で以下のように書いて読み込んだ表でしたね。

```
desc <- read.csv(path_table_descriptive, row.names = 2)
```

しかしこのままでは投稿できません。
表の見た目を整えましょう。

### 表の見た目を整える（例１）

````
::: {.landscape}
```{r}
#| label: tbl-descriptive
#| tbl-cap: "Average and standard deviation of scores"
desc[, !colnames(desc) %in% 'highlevel'] |>
  set_sdgt(nr) |>
  fullform_colnames(abbr) |>
  fullform_rownames(abbr) |>
  set_table_appearance() |>
  pack_rows_bycol(desc, 'highlevel', abbr)
```

Danraku wo wakezuni kaigyo suru tameni, bunmatsu ni space wo 2-ko oiteiru.  
_M_: Mean value  
_SD_: Standard deviation
:::
````

これで、↓こうなります。ページ向きは横になっています。

![ss-table3.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/304493/faf320b8-e6bb-4e8c-9d97-b5272d49276f.png)

まず、`desc[, !colnames(desc) %in% 'highlevel']` で、`highlevel` 列をいったん削除します。

`|>` は、パイプ演算子と呼ばれます。
`desc |> set_sdgt(nr)` は、`set_sdgt(desc, nr)` と同義です。
これ以降、パイプ演算子を使って、表に `helper.R` にある関数たちを適用しています。

`set_sdgt()` は、`NumRenderer()` に設定した桁数を使って表の中の桁数を丸めてくれています。

`fullform_colnames()` と `fullform_rownames()` は、`abbr` として設定した対応表を使って、略語を正式語に変換してくれています。
前者は列名、後者は行名の略語を変換しています。
今回の例には出していませんが、`fullform_cols()` という、指定した列に含まれる文字列を変換する関数も `helper.R` に入っています。

`pack_rows_bycol()` は、マルチインデックス表示をしてくれています。

↓のように、

```
::: {.landscape}
（略）
:::
```

`::: {.landscape} :::` の間に囲むことで、その範囲を横向きページにできます。

### 表の見た目を整える（例２）

もう一つの表も埋め込みましょう。

````
```{r}
#| label: tbl-corr
#| tbl-cap: "Correlation coefficients"
corr |>
  set_sdgt(nr, ngto = c("r"), p = c("p.unc", "p.corr")) |>
  fullform_colnames(abbr) |>
  fullform_rownames(abbr) |>
  set_table_appearance()
```

footnote kinou wo tsukawazu, chokusetsu kaita houga yosasou.  
Bun no atama ga indent sareru no dake ga mondai.  
_r_: Pearson's correlation coefficients.  
$p_{\mathrm{unc.}}$: Uncorrected p-value.  
$p_{\mathrm{Bonf.}}$: p-value corrected by Bonferoni's method.

````

↓
![ss-table4.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/304493/9fcff82a-5cb7-4efb-91f0-b680b52ea8ba.png)

この表では、`set_sdgt()` に `ngto` と `p` の引数を与えています。
`ngto` (Not Greater Than One) の列として `r`、`p` (p 値）の列として `p.unc` と `p.corr` を指定しました。
これにより、数値の表示が先ほどとは変わっています。
先頭の 0 が省略されたり、.001未満の p 値が `< .001` 表記になったりしています。

### （メモ）要改善点

表の脚注を、本文としてそのまま書くことで表してしまっているのがイマイチなポイントです。
本文として書いているので、文頭がインデントされてしまっています。
kable の `footnote` 関数を使えばいい感じになるかなとも思ったのですが、うまくいきません。
kable と Quarto の噛み合わせがよくないのかもしれません。

<details><summary>うまくいかなかった例１</summary><div>

````
```{r}
#| label: tbl-corr-bad1
#| tbl-cap: "(BAD EXAMPLE 1) Correlation coefficients"
corr |>
  set_sdgt(nr) |>
  fullform_colnames(abbr) |>
  fullform_rownames(abbr) |>
  kableExtra::kable(row.names = TRUE,
                    format = "latex",
                    escape = FALSE,
                    booktabs = TRUE) |>
  kableExtra::footnote(general_title = "", threeparttable = TRUE, escape = FALSE,
                       c('This table uses footnote function. But it gives up full-length-width. Also, this requires any words after the table.',
                         "\\\\textit{r}: Pearson's correlation coefficients",
                         '$p_{\\\\mathrm{unc.}}$: Uncorrected p-value',
                         "$p_{\\\\mathrm{Bonf.}}$: p-value corrected by Bonferoni's method"))
```

(Such mean-less sentence is required, otherwise, pagebreak does not work)
````

![ss-bad-table1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/304493/c99b6bb8-84f4-482c-9719-6e4c34333964.png)

kable の `footnote` 関数を使いました。
基本はいい感じなのですが、横幅が狭く感じますね。
これに `kableExtra::kable_styling(full_width = TRUE)` を組み合わせればいいかなと思ったのですが、うまくいきません。
`full_width = TRUE` かつ `threeparttable = TRUE` とするためには、`kable()` にて `longtable = TRUE` とする必要があります。
しかし、`longtable = TRUE` かつ `full_width = TRUE` にすると、エラーが出てしまいます。

またもう一点、```{r}...```のあとに何かしらの文章がないと、`{{< pagebreak >}}` が効きません。
ピリオド一個置くだけでもいいのですが、たぶんタイポだと思われてしまいますよね……。
</div></details>

<details><summary>うまくいかなかった例２</summary><div>

````
```{r}
#| label: tbl-corr-bad2
#| tbl-cap: "(BAD EXAMPLE 2) Correlation coefficients"
corr |>
  set_sdgt(nr) |>
  fullform_colnames(abbr) |>
  fullform_rownames(abbr) |>
  kableExtra::kable(row.names = TRUE,
                    format = "latex",
                    escape = FALSE,
                    booktabs = TRUE) |>
  kableExtra::kable_styling(full_width = TRUE) |>
  kableExtra::footnote(general_title = "", threeparttable = FALSE, escape = FALSE,
                       c('This table uses foot note function. But it gives up long foot note. Also, this requires any words after the table. threeparttable requires longtable is TRUE, but if both longtable and full-width are TRUE, Quarto returns error.',
                         "\\\\textit{r}: Pearson's correlation coefficients",
                         '$p_{\\\\mathrm{unc.}}$: Uncorrected p-value',
                         "$p_{\\\\mathrm{Bonf.}}$: p-value corrected by Bonferoni's method"))
```

.
<!-- ↑pagebreak を効かせるためのダミー文字 -->
````

![ss-bad-table2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/304493/0207866d-bb58-4054-930e-2b59c4961927.png)

`threeparttable` を諦めればいい感じになるのですが、長い脚注があると右に見切れてしまいます。
また、やはり `{{< pagebreak >}}` のためのダミー文字が必要となります。
脚注が長くなく、かつ改ページが必要ないなら、この方法でもよいかもしれません。

</div></details>

# Step 6. 本文を PDF 出力する

作成した paper.qmd をもとに、PDF を出力しましょう。
私のように VSCode を使っている方へのオススメは、Quarto Extension を使用することです。

![extension.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/304493/847a22ed-daf9-415a-b964-fbc493380d48.png)

VSCode のショートカットである `Cmd (Control) + C` を使ってコマンドパレットを呼び出します。
`preview` と打ち込んで、`Quarto: Preview` コマンドを実行します。

![ss-preview.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/304493/935c7ae0-daa7-4dc3-bec6-ec43e0af2d08.png)

あるいは、Terminal 等にて、`quarto render paper.qmd` です。
これで、`paper.pdf` が生成されます。
また、中間ファイルとして　`paper.tex` と `tex-source-files/`[^1] が生成されます。
ジャーナルへ投稿するときは、この２つのファイル・ディレクトリをアップロードすればOKです。

[^1]: `paper.tex` や `paper.pdf` と同時に、`paper.tex` が参照するさまざまなファイルが生成されます。これらのファイルは、`tools/post-render.py` によって 'tex-source-files/' の中に格納されます。

続きは[周辺文書作成編](https://qiita.com/issakuss/items/2c6de20e8d4d4bb82a8c)にて。