User Tools

Site Tools


projects:workgroups:notes_on_writing_text_for_the_book

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Last revision Both sides next revision
projects:workgroups:notes_on_writing_text_for_the_book [2019/03/13 10:11]
schuemie
projects:workgroups:notes_on_writing_text_for_the_book [2019/06/26 09:08]
schuemie [Keep in mind]
Line 1: Line 1:
 ====== Notes on writing text for the Book of OHDSI ====== ====== Notes on writing text for the Book of OHDSI ======
  
 +Most of the information on this page can be found in [[https://​raw.githubusercontent.com/​OHDSI/​TheBookOfOhdsi/​master/​extras/​CheatSheet.pdf|The Book of OHDSI Cheat Sheet]].
  
-===== General layout of a chapter=====+===== General layout of a chapter ===== 
 + 
 +Please try to adhere to the following general layout for each chapter:
  
   * Introduction  ​   * Introduction  ​
Line 10: Line 13:
   * Exercises   * Exercises
  
-===== Keep in mind=====+===== Keep in mind =====
  
-  * Hyperlinks should show the actual URL, so that a printed copy would still have a readable link.+  ​* Abbreviations should be re-defined in each chapter. So yes, the first time you mention CDM in your chapter it should be CDM (Common Data Model). 
 + 
 +  * Table names should be all-caps, so OBSERVATION_PERIOD. Field names should be lower case, so observation_period_id.  
 + 
 +  * When quoting, use "​double quotes"​. 
 + 
 +  ​* Hyperlinks should show the actual URL, so that a printed copy would still have a readable link. To avoid formatting issues, it might be best to add the URL as a footnote. Use URLs sparingly.
  
   * Tables and figures should be designed with small screens in mind.   * Tables and figures should be designed with small screens in mind.
 +
 +  * The maximum section depth is 3, so for example section 2.3.4. You can finagle a 4th level by using bold headers (not numbered).
  
   * Keep filename extensions in lower case, so '​figure.png',​ not '​figure.PNG'​.   * Keep filename extensions in lower case, so '​figure.png',​ not '​figure.PNG'​.
  
-  * Only use alphanumeric characters in labels. So not '```{r figure_1}'​ but '```{r figure1}'​.+  * Only use alphanumeric characters in labels. So not ''```{r figure_1}'' but ''```{r figure1}''.
  
   * Tables and lists only render correctly if they have an empty line in front of them.   * Tables and lists only render correctly if they have an empty line in front of them.
  
-  * Extra rows in the boob.bib file (not used in the text) are not a problem.+  * Extra rows in the book.bib file (not used in the text) are not a problem.
  
 ===== Editing the Book  ===== ===== Editing the Book  =====
Line 36: Line 47:
 To start editing the book, first [[https://​help.github.com/​en/​articles/​fork-a-repo|fork]] the [[https://​github.com/​OHDSI/​TheBookOfOhdsi|TheBookOfOhdsi repo]]. Then [[https://​happygitwithr.com/​rstudio-git-github.html|clone]] the fork using RStudio. To start editing the book, first [[https://​help.github.com/​en/​articles/​fork-a-repo|fork]] the [[https://​github.com/​OHDSI/​TheBookOfOhdsi|TheBookOfOhdsi repo]]. Then [[https://​happygitwithr.com/​rstudio-git-github.html|clone]] the fork using RStudio.
  
-You can build the entire book in RStudio in the Build tab (top right panel). Alternatively,​ you can build a preview just of your chapter using the //​preview_chapter()//​ command.+You can build the entire book in RStudio in the Build tab (top right panel). Alternatively,​ you can build a preview just of your chapter using the //​preview_chapter()//​ command ​in R.
  
 After making your edits, commit and push them to your forked repository. From there, you can create a [[https://​help.github.com/​en/​articles/​creating-a-pull-request|pull-request]] to the main repository. After making your edits, commit and push them to your forked repository. From there, you can create a [[https://​help.github.com/​en/​articles/​creating-a-pull-request|pull-request]] to the main repository.
  
-===== Generic ​Markdown syntax =====+===== Markdown syntax =====
  
 An overview of basic Markdown syntax can be found [[https://​www.markdownguide.org/​basic-syntax/​|here]]. ​ An overview of basic Markdown syntax can be found [[https://​www.markdownguide.org/​basic-syntax/​|here]]. ​
 +
 +Some useful extended syntax:
 +
 +Tables: ​
 +
 +  | Concept ID | Name |
 +  | ---------- | ---- |
 +  | 8532 | FEMALE|
 +  | 8507 | MALE|
 +  ​
 +Important! The number of hyphens in the second row determines how wide the table is. The relationship between number of hyphens and table width is not documented, but 10 hyphens translates into approximately 10-20% width.
 +
 +You can add a table caption like this:
 +
 +  Table: (\#​tab:​conceptTable) A table with two concepts.
 +  ​
 +  | Concept ID | Name |
 +  | ---------- | ---- |
 +  | 8532 | FEMALE|
 +  | 8507 | MALE|
 +    ​
 +Footnotes:
 +
 +  Here's a sentence with a footnote. [^1]
 +  ​
 +  [^1]: This is the footnote.
 +
 +Heading ID:
 +
 +  ### P-value mantras{#​custom-id}
 +
 +  For more detail, see section \@ref(custom-id)
 +
 +Definition list:
 +
 +  term
 +  : definition
  
 ===== Adding figures ===== ===== Adding figures =====
  
-Please add figure files to a subfolder of the [[https://​github.com/​OHDSI/​TheBookOfOhdsi/​tree/​master/​images|images folder]]. The subfolder should have the same name as the chapter Rmd file.+Please add figure files to a subfolder of the [[https://​github.com/​OHDSI/​TheBookOfOhdsi/​tree/​master/​images|images folder]]. The subfolder should have the same name as the chapter Rmd file. Keep filename extensions in lower case, so '​figure.png',​ not '​figure.PNG'​.
  
 In the chapter, you can include a figure using the following piece of text: In the chapter, you can include a figure using the following piece of text:
  
-  ```{r figure1, fig.cap='​The prediction problem',​echo=FALSE,​ out.width='​100%'​}+  ```{r figure1, fig.cap='​The prediction problem',​echo=FALSE,​ out.width='​100%', fig.align='​center'}
   knitr::​include_graphics("​images/​PatientLevelPrediction/​Figure1.png"​)   knitr::​include_graphics("​images/​PatientLevelPrediction/​Figure1.png"​)
   ```   ```
  
-Here, ''​figure1''​ is the label that can be used to reference the figure. You furthermore must specify a caption and the path to the figure file.+Here, ''​figure1''​ is the label that can be used to reference the figure. Only use alphanumeric characters in labels. So not ''​```{r figure_1}''​ but ''​```{r figure1}''​. You furthermore must specify a caption and the path to the figure file.
  
 You can reference the figure in your text for example using ''​Figure \@ref(fig:​figure1) shows ...''​. You can reference the figure in your text for example using ''​Figure \@ref(fig:​figure1) shows ...''​.
 +
 +==== Adding ATLAS screenshots ====
 +
 +It is hard to take screenshots of ATLAS where the resulting font size in the image in the book is big enough to read. Try to keep screenshots to a minimum. If you need to make a screenshot, here are instructions for making ok screenshots:​
 +
 +  * In Chrome, open the developer tools using Ctrl + Shift + i.
 +  * Click the second button top left that looks like a mobile phone.
 +  * In the main Chrome window, set the width to 1000 and the zoom to 150%
 +  * Use for example the Windows Snipping Tool to capture the screen. However, you cannot include the full screen width, and for example it is best to leave out the left navigation bar.
  
 ===== Adding literature references ===== ===== Adding literature references =====
Line 76: Line 133:
 ==== Referencing in text ==== ==== Referencing in text ====
  
-The first field in the BibTeX ​in its label, and this label can be used to reference the citation. This can be done with and without square brackets. For example, ''​As proposed by @reps2018''​ will render to //`As proposed by Reps et al. (2018)`//, while ''​As proposed elsewhere [@reps2018]''​ will render to //`As proposed elsewhere (Reps et al. 2018)`//+The first field in the BibTeX ​is its label, and this label can be used to reference the citation. This can be done with and without square brackets. For example, ''​As proposed by @reps2018''​ will render to //`As proposed by Reps et al. (2018)`//, while ''​As proposed elsewhere [@reps2018]''​ will render to //`As proposed elsewhere (Reps et al. 2018)`// 
 + 
 +A convenient way of inserting citatiosn is to use the citation add-in that comes with the bookdown package: 
 + 
 +{{:​projects:​workgroups:​screenshot.png?​400|}} 
 + 
 +===== Referencing OHDSI tools ===== 
 + 
 +We will explain where to find the OHDSI tools and how to install them once in the book. All other references to OHDSI tools should just mention the tool name, and the name should be a hyperlink to the tool page. For R packages, use the Github Pages page, for example: 
 + 
 +   This done through the [FeatureExtraction](https://​ohdsi.github.io/​FeatureExtraction/​) package. 
 + 
  
projects/workgroups/notes_on_writing_text_for_the_book.txt · Last modified: 2019/08/07 14:02 by schuemie