instructions.RmdHere are instructions for using the norman package, to generate a report (in PDF) on any given set of exam marks.
This is all specific to the administration of courses in the Department of Statistics at the University of Warwick. It is of no conceivable interest to anyone else.
I recommend reading the whole document before doing anything — to get the idea of how all this is meant to work.
The instructions below (from step 1 onwards) will all assume that you have a functioning installation of R, Rtools, RStudio and LaTeX — specifically, a setup that is capable of “knitting” an R Markdown (.Rmd) file to a PDF output document. (A part of that setup with be the installation of the R add-on package rmarkdown.)
These installations are all fairly standard. Our IT support staff should be able to handle it without problem.
It’s probably best to test your setup on a relatively simple R Markdown document, such as the one you get when selecting File –> New file –> R markdown in Rstudio’s menu. With such a file open in the RStudio editor, try doing Knit to PDF (from the “Knit” menu).
In Windows, setting up these things seems sometimes to be problematic, I don’t know why. But there are plenty of tips available online (e.g., https://rickpackblog.wordpress.com/2017/10/04/miktex-install-for-r-windows-pdf-output-r-markdown/ ). Good luck with it! Thankfully you’ll only need to do it once — until you get a new computer, of course.
The package norman builds Warwick Statistics reports on exam marks.
To install norman for the first time: in your R Console (which is one of the panes in the RStudio window), paste the following and hit return:
if (!("remotes" %in% installed.packages()[,"Package"])) install.packages("remotes")
remotes::install_github("DavidFirth/norman", build_opts = "--no-build-vignettes")The installation of norman should also trigger the installation of 2 other packages if you do not have them already. They are aplpack and ggplot2.
Again in your R console:
install.packages("rmarkdown")This will be needed only later, whenever the norman package itself has been updated to a new version — for example, after norman has been improved to fix bugs or to add new features to the reports it makes. If you have only just installed norman (as detailed above), you should skip this section for now but keep it in mind for when needed.
Whenever you do find the need to update norman, in your R console just issue the following command:
norman::update()In 2019 for example, you might want to have folders named something like
— but the names can be chosen freely, depending on your specific filing needs. The name of each folder should indicate clearly which marks will be used in making the corresponding report.
You can have as many of these folders as you want — it just needs to be one folder for each report that you want to make. Each folder will be a separate “project” (in the terminology of RStudio).
This determines which of the folders you made will be the one that you will be working in next. That folder will be called your current working folder in what follows (and the report that you want to make in that folder will be called your current report).
Your working folder must contain the following three things. (Other things can be there too, for example your own notes or whatever; but the software won’t work properly without the 3 things listed below.)
The most essential input to this report-building package is a subfolder containing exam marks.
The subfolder should be named simply as marks. If you give it any other name, the software will not work. (This is deliberate.)
The folder can contain any number of comma-separated-values (.csv) files. Each such file must have a name that starts with the 5-character code for a module, for example ST344_raw_marks_2019.csv. The rest of each file name (after the first 5 characters, before .csv) can be anything, within reason.
Each of the .csv files must contain at least columns named sprCode and overallMark — these being the columns that identify students, and give each student’s mark in the module. Any other columns present in the .csv files will simply be ignored.
This must be a comma-separated-values file named module_names.csv file with 2 columns, headed ModuleCode and ModuleName.
This file must provide a module name for (at least) each module code that will be found in the marks folder for the current report. (Different module_names.csv files can be used in different reports, if needed.)
(The module_names.csv file can safely contain also module codes/names that are not relevant to your current report — they will simply be ignored.)
This must be a simple, plain text file named modules_expected_here.txt (a file made, for example, with Notepad+). It should contain one 5-character module code on each line.
The modules listed in this file should be all the ones that are relevant to your current report.
This file is used only for checking purposes, to provide a warning if either
From the File menu in RStudio, pick New Project and then Existing Directory. Then browse to your current working folder and click Create Project.
Still in RStudio: File -> New File -> R Markdown -> From Template, then from the menu pick the item Warwick Stats report on module marks.
This will open up a template .Rmd file for editing.
In that template there are 3 places labelled ???? where you will want to make appropriate edits. (The edits can be done at a later time, if you want to see your report first.) These edits will provide:
When you have finished editing those 3 things, or if you have decided to postpone that editing until later, pick File -> Save as… and save your .Rmd file into your current working folder, with a name that will clearly identify your report. (For example, 2019_Second_year_marks_report_before_scaling.Rmd — or whatever you want, but it must have the file extension .Rmd.)
Just click on Knit at the top of your RStudio window.
If all goes well, this will make your report as a PDF document in your current working folder (with the same name as your .Rmd file, but with the .pdf extension replacing .Rmd).
When the data has changed (for whatever reason), or when you want to make fresh edits to the title, author or remarks fields of the report, you can update your report just by opening the .Rmd file (in RStudio). Make any necessary edits and then click Knit to save the report and re-make the PDF document.
Note that this will over-write your previous report. So if you want to keep the previous PDF, you should re-name it first, before updating the report as described above.