You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A JavaScript library and CLI tool for [ERC](https://github.com/o2r-project/erc-spec) result checking.
15
6
16
-
-------------------------------------------------
7
+
The checker is part of the project Opening Reproducible Research ([o2r](http://o2r.info/)).
8
+
Its purpose is to verify the result of reproductions of scientific papers as part of the o2r reproducibility service by means of comparing the HTML of the original and reproduced article.
17
9
18
-
A JavaScript library and CLI tool for [ERC](https://github.com/o2r-project/erc-spec) metadata, execution, and result checking.
10
+
The checker runs on [NodeJS](https://nodejs.org/en/).
11
+
The tool implements a [NodeJS module](#node-module), which is a function returning a [JavaScript Promise](https://www.npmjs.com/package/promise).
12
+
It further implements a [command line interface](#command-line-interface) (WORK IN PROGRESS).
19
13
20
-
The checker is part of the [o2r-project](http://www.o2r.info/). Its purpose is to verify the o2r-platform's reproduction automatism for scientific papers in HTML format.
14
+
The documentation is available at **[https://o2r.info/erc-checker/](https://o2r.info/erc-checker/)**.
21
15
22
-
The checker runs on [NodeJS](https://nodejs.org/en/). The tool implements a [NodeJS module](#node-module), which is a function returning a [JavaScript Promise](https://www.npmjs.com/package/promise).
23
-
24
-
It further implements a [command line interface](#command-line-interface) (WORK IN PROGRESS).
25
-
26
-
-------------------------------------------------
27
-
28
-
## NodeJS module usage
29
-
30
-
The checker's `index.js` exports an object called `ercChecker`. This object contains a function that takes two paths to HTML files and optional further parameters, and returns a JavaScript Promise.
31
-
32
-
#### Installation
33
-
34
-
The erc-checker is currently not featured as an official npm module in the [node package repository](https://www.npmjs.com/).
35
-
36
-
Instead, it is best installed directly from GitHub:
The checker is executed with a `config` object (`JSON`).
59
-
60
-
```javascript
61
-
62
-
var config = {
63
-
directoryMode: Boolean, // default: false --- read papers from directories automatically? (false: paths for both papers MUST be specified; true: path to directory MUST be specified)
64
-
pathToMainDirectory: String,
65
-
pathToOriginalHTML: String,
66
-
pathToReproducedHTML: String,
67
-
saveFilesOutputPath: String, // necessary if diff-HTML or check metadata should be saved
68
-
saveDiffHTML: Boolean, // default: false
69
-
outFileName: String, // choose a name for diff-HTML (defaults to "diffHTML.html")
70
-
saveMetadataJSON: Boolean, // default: false
71
-
createParentDirectories: Boolean, // default: false --- IF outputPath does not yet exist, this flag MUST be settrue; otherwise, the check fails
72
-
comparisonSetBaseDir: String, // base directory of repository to be checked, used to create a file list (glob)
73
-
checkFileTypes: [String], // case insensitive list of file endings to be included; currently defaults to ["htm", "html"]
74
-
quiet: Boolean // default: false
75
-
};
76
-
77
-
```
78
-
79
-
80
-
___Note:___ optional parameters may be left out of the config object when not used. In this case, defaults apply.
81
-
82
-
In directory mode, individual path parameters will be ignored. Otherwise, main directory path will be ignored.
83
-
84
-
One of the following configurations __MUST__ be made
85
-
- `directoryMode = false` and `pathToOriginalHTML`&&`pathToReproducedHTML` valid paths to HTML files, _or_
86
-
- `directoryMode = true`&&`pathToMainDirectory` valid path to a directory structure as seen below:
87
-
88
-
```
89
-
target_directory
90
-
│
91
-
└───original
92
-
│ │ main.html
93
-
| │ someOther.html
94
-
│
95
-
└───reproduced
96
-
│ main.html
97
-
```
98
-
99
-
In `directoryMode`, there __MUST__ be two subdirectories, `original` and `reproduced`.
100
-
101
-
___Note___: HTML files in directories are NOT REQUIRED to be named "_main.html_". However, the checker will pick the first `.html`file found _in alphabetical order_ .
102
-
103
-
The tool will compare both HTML files forimages only. The images __MUST__ be __base64__-encoded, and encapsulatedin an HTML img tag, as generated automatically when rendering an `.Rmd` file into HTML format.
104
-
105
-
If both HTML papers contain an equal number of images, the checker may write a new HTML file, containing the results of the comparison between all images in the input files, as created by [`pixelmatch`](https://github.com/mapbox/pixelmatch), as well as highlighted text differences between both papers.
106
-
107
-
Further parameters (in order):
108
-
- `saveFilesOutputPath: String`: third path for file output; necessary if either parameter `saveDiffHTML` or `saveMetadataJSON` is set, otherwise ignored
109
-
- `saveDiffHTML: Boolean`: save diffHTML file to output directory
110
-
- `outFileName: String`: choose a custom name for diffHTML (default is "diffHTML.html")
111
-
- `saveMetadataJSON: Boolean`: save metadata.json to output directory
112
-
- `createParentDirectories: Boolean`: create parent directories for output (if false and directories of path not yet created, output will not be created)
113
-
- `comparisonSetBaseDir: String`: path to the base directory of the repository to be checked, may be absolute or relative
114
-
- `checkFileTypes: [String]`: case insensitive list of file endings to be included in the comparison set for the check
115
-
- `quiet: Boolean` : silence loggers
116
-
117
-
#### Errors
118
-
Any errors during execution cause the returned JSPromise to be __rejected__. Errors will be caught and
119
-
- logged out to the console
120
-
- saved in a check metadata JSON object, which is returned as _rejection argument_:
121
-
```javascript
122
-
{
123
-
"checkSuccessful": ... ,
124
-
"images": [ ... ],
125
-
"display": {
126
-
"diff": "[merged diff-HTML]"
127
-
},
128
-
"start": Date,
129
-
"end": Date,
130
-
"errors": [ <Error description> ]
131
-
}
132
-
```
133
-
Metadata may contain a varying amount of data, depending on where in the process an error occurred.
134
-
135
-
Externally caused errors will occur, if:
136
-
- paths to files / directory are invalid
137
-
- output path does not exist, and createParentDirectories flag is not set
138
-
- papers contain an unequal number of images
139
-
- base64-encoded image invalid / broken
140
-
141
-
142
-
#### Returns
143
-
The `ercChecker` function returns a JSPromise.
144
-
145
-
If execution is successful, the Promise will be __resolved__, containing a check metadata JSON object:
146
-
```javascript
147
-
{
148
-
"checkSuccessful": Boolean,
149
-
"images": [
150
-
{
151
-
"imageIndex": Number,
152
-
"compareResults": {
153
-
"differences": Number,
154
-
"dimension": Number
155
-
}
156
-
}, ...
157
-
],
158
-
"display": {
159
-
"diff": String // contains the entire result HTML,
160
-
// with images swapped for diff-Images where differences were found;
161
-
// contains merged text of both papers, with differences highlighted
162
-
},
163
-
"comparisonSet": [String], // contains relative paths of all files with file type ending
164
-
// matching the specified in config file using the `checkFileTypes` attribute
165
-
"start": Number,
166
-
"end": Number,
167
-
"errors": []
168
-
}
169
-
```
170
-
171
-
##### Development
172
-
For debugging purposes: When running the checker with a NodeJS environment variable `DEV` set true, the result AND reject metadata will include an absolute path to the temp-directory used during the check.
173
-
174
-
### How to use the checker module
175
-
176
-
```javascript
177
-
const checker = require('<path>/<to>/erc-checker/index').ercChecker; // import the ercChecker module, which is a function
178
-
179
-
// head: checker(config);
180
-
```
181
-
182
-
The `ercChecker` function will return a Promise, which will be resolved on successful execution, or rejected on error.
183
-
184
-
Thus, while the Checker will run asynchronously, it can be chained in a controlled fashion.
0 commit comments