touchstone-language v1.0.2
Touchstone Language (TSL)
TSL is a language for describing experimental design.
The parser (dynamically generated from parser.jison
) parse the TSL specification and generate abstract syntax tree.
Then, the syntax tree is taken by the generator (generator.ts
) to create the corresponding trial tables.
The code is written in TypeScript, together with worker.js
which is copied (with additions at the header and footer) from the Touchstone 2 codebase.
The source code is stored in src
and the compiled code is in dist
.
However, worker.js
need to be manually copied.
Related project
Touchstone2 a GUI for designing experiments.
Instlalation and scripts
npm run build
- compiles the TypeScript files to JavaScriptnpm run test
- runs all unit testsnpm run trial-table
- generates a trial table for 4 participants based on a tsl fileparser
- returns the parsed object from tslrpc-server
- starts up the rpc server
Compiling one TSL file
- Compiling one TSL file
node dist/src/run_parser.js [tsl_path]
If tsl_path
is not set, the script use the variable input_path
defined in the file.
This command is also good if the parser (tsl.jison
) doesn't compile properly because the detailed parsing error will be printed in the console.
- Generating trial table
node dist/src/run_generator.js [tsl_path]
Testing
The test cases are in test
folder.
TSL input are in the test/testcases
folder.
Run the tests with:
npm test
This will run all tests in the folder, watch for file changes, and re-run them. If you add a new test file, you'll have quit (Ctrl + C) and re-run this command.
Calling TSL from a remote process
TSL can be called from other process, which may be written in another language such as Python.
- Install ZeroMQ.
- Mac:
- install homebrew
- run
brew install zeromq
- Mac:
- Install zerorpc-node
npm install --no-save zerorpc
- Run the server
node dist/src/rpc_server.js
The server will listen to requests at port 4242. (The port number is hard-coded.)
Example Python 3 client
- Install
msgpack
:pip install msgpack
- Install
zerorpc
:pip install zerorpc
- Run the example:
python examples/python_rpc_client/client.py
Extension
Trial table generator
To add a new type of a trial table generator that corresponds to the design node in TSL abstract syntax tree,
simply create the generator with the function signature in the type TSLGeneratorFunction
(see: tsl_types.ts
).
Then, register the function with the corresponding name of the AST node with the following command:
TSLStrategyRegistry.sharedRegistry().addGeneratorForStrategy("between", generator);
See an example in src/counterbalancing/between.ts
.
Tips
To debug the jison code, the following command will allow you to print entire hierarchy of variables.
console.log(require('util').inspect(result, true, 10));
TODOs
All TODOs are commented in the code in src
folder.
Credits
TSL is a work by the People and Computing Lab (ZPAC) at the University of Zurich and the ex)situ lab.
If you use or build upon TSL, please cite the following paper.
Alexander Eiselmayer, Chat Wacharamanotham, Michel BeaudouinLafon, and Wendy E. Mackay. 2019. Touchstone2: An Interactive Environment for Exploring Trade-offs in HCI Experiment Design. In CHI Conference on Human Factors in Computing Systems Proceedings (CHI 2019), May 4–9, 2019, Glasgow, Scotland Uk. ACM, New York, NY, USA, 11 pages. https://doi.org/10.1145/3290605.3300447
@inproceedings{Eiselmayer:2019:TIE:3290605.3300447,
author = {Eiselmayer, Alexander and Wacharamanotham, Chat and Beaudouin-Lafon, Michel and Mackay, Wendy E.},
title = {Touchstone2: An Interactive Environment for Exploring Trade-offs in HCI Experiment Design},
booktitle = {Proceedings of the 2019 CHI Conference on Human Factors in Computing Systems},
series = {CHI '19},
year = {2019},
isbn = {978-1-4503-5970-2},
location = {Glasgow, Scotland Uk},
pages = {217:1--217:11},
articleno = {217},
numpages = {11},
url = {http://doi.acm.org/10.1145/3290605.3300447},
doi = {10.1145/3290605.3300447},
acmid = {3300447},
publisher = {ACM},
address = {New York, NY, USA},
keywords = {counterbalancing, experiment design, power analysis, randomization, reproducibility},
}