function VisUnit(){ let taskAccuracySum = 0; //used for gateway tasks let sessionId; /** -------------------------------------------------------------------- starts a study(schedule); gui can be either a plain div (in which case the default VisUnit display layout is constructed) or as an object where individual divs are specified for each GUI element (question, answer, next...) saveData = callback function to save the data somw somewhere; VisUnit will call this whenever a participant finishes a task and send in two params: the participant response, and the task context **/ this.startStudy = (gui, schedule, saveData = () => {}) => { sessionId = `id-${Date.now()}-${Math.random().toString(36).substr(2, 9)}` if (gui instanceof HTMLDivElement){ //empty div element; create default VisUnit gui structure inside it gui = createDefaultGUI(gui); } setupBlock(gui, saveData, schedule, 0, 0, (b,i) => {}); } /** -------------------------------------------------------------------- previews a task with the given viewer for the given data; by default all instances of the task are previewed; alternatively specific instances can be given (their data field needs to match data) **/ this.previewTask = (gui, task, viewer, data, specificInstances = null) => { let instances = specificInstances == null ? (!("instances" in task) || task.instances == null) ? [] : task.instances.filter (i => i.data == data).map( i => i.instances).flat() : specificInstances; let block = [ { type : "preview", task : task, viewer: viewer, dataset : data, instances : instances, duration : 10}]; this.startStudy(gui, block); } /** -------------------------------------------------------------------- WORKHORSE method: sets up a study block with everything associated: setting up the visual stimulus (viewer+dataset+task), returning and saving results, etc. **/ function setupBlock(gui, saveData, schedule, blockIndex, instanceIndex = 0, advanceCallback) { clearGUI(gui); //if we start a new block then ... if (instanceIndex == 0) taskAccuracySum = 0; //if we reached the end -> finish if (blockIndex >= schedule.length){ return; } let block = schedule[blockIndex]; //defaults! if (!Array.isArray(block.task.inputs)) block.task.inputs = []; if (!Array.isArray(block.task.outputs)) block.task.outputs = []; if (!Array.isArray(block.instances)) block.instances = []; //set progress let completedDuration = scheduleDuration(schedule, blockIndex) + (instanceIndex+1)*block.duration; let totalDuration = scheduleDuration(schedule); let progress = Math.trunc(100 * completedDuration/totalDuration); if (totalDuration == 0 || progress > 100) progress = 100; if (block.exit == true){ progress = 100; gui.next.disabled = true; } if (block.type == "preview"){ gui.progress.innerHTML = "(" + (instanceIndex+1) + " of " + Math.max(1,block.instances.length) + ")"; if (instanceIndex >= block.instances.length-1) gui.next.disabled = true; } else{ gui.progress.innerHTML = "(" + progress + "% done)"; } if (block.type == "eval_task" || block.type == "block_task" || block.type == "train" || block.type == "bridge_task" || block.type == "preview"){ //set up EVAL blocks and get back a 'getResponse' method let getResponse = setupEvalBlock(gui, block, (block.instances != undefined && block.instances.length > 0) ? block.instances[instanceIndex] : null); //if it's the first instance of a task, increasing saliency of task instruction //with a small animation if (instanceIndex == 0){ d3.select(gui.question).transition().duration(300). style("background-color","rgba(0,0,0,0.15)"); d3.select(gui.question).transition().delay(500).duration(500). style("background-color","rgba(0,0,0,0)"); } if (block.type == "train"){ d3.select(gui.train).transition().duration(300). style("background-color","rgba(0,0,0,0.15)"); d3.select(gui.train).transition().delay(500).duration(500). style("background-color","rgba(0,0,0,0)"); //enable training controls (checking accuracy, etc.) enableTrainingGUI(gui); gui.check.onclick = () => { let response = getResponse(); gui.correctness.hidden = false; gui.correctness.innerText = formatAccuracy(response.accuracy) + " "; gui.next.disabled = false; } } //end train if (block.type == "preview"){ gui.check.hidden = false; gui.check.onclick = () => { let response = getResponse(); gui.correctness.hidden = false; gui.correctness.innerHTML = formatAccuracy(response.accuracy) + " "; } } //--> all set up let startTime = (new Date()).getTime(); //->what happens if maxTime expires let interval = -1; if (block.max_duration){ let left = block.max_duration; interval = setInterval(() => { left = Math.max(0,left-0.1); gui.timeout.innerHTML = ""+left.toFixed(1); if (left == 0){ clearInterval(interval); interval = -1; gui.viewer.style.transition = "opacity 0.5s, visibility 0.5s"; gui.viewer.style.opacity = 0; gui.viewer.style.visibility = "hidden"; // gui.answer.querySelectorAll("input, button"). // forEach(input => input.disabled = true); } }, 100); } //->what happens when user is done (clicks next) gui.next.onclick = () => { if (interval>=0) clearInterval(interval); let response = getResponse(); response.time = ((new Date()).getTime() - startTime); if (block.type == "train"){ response.train = true; disableTrainingGUI(gui); } if (block.type == "train" || block.type == "preview") gui.correctness.hidden = true; //call provided call back to save responses response.sessionId = sessionId; saveData(response); if (response.accuracy > 0) taskAccuracySum += response.accuracy; //if there are more instances of this task -> go to next instance if (block.instances != undefined && instanceIndex < block.instances.length-1){ advanceCallback(blockIndex, instanceIndex+1); setupBlock(gui, saveData, schedule, blockIndex, instanceIndex+1, advanceCallback); } else { //gateway tasks if (block.min_accuracy && taskAccuracySum / block.instances.length < block.min_accuracy){ //exit study let exitBlock = schedule.findIndex ( b => b.exit); if (exitBlock < 0) exitBlock = schedule.length-1; advanceCallback(exitBlock, 0); setupBlock(gui, saveData, schedule, exitBlock, 0, advanceCallback); } else { //continue as normal advanceCallback(blockIndex+1, 0); setupBlock(gui, saveData, schedule, blockIndex+1, 0, advanceCallback); } } } } else{ //unrecognised block, skip setupBlock(gui, saveData, schedule, blockIndex+1); } } /** -------------------------------------------------------------------- helper method for setupBlock **/ function setupEvalBlock(gui, block, instance){ let viewer = block.hide_viewer ? null : block.viewer; //change the data in the viewer if necessary if (viewer != null && viewer.getData() != block.dataset) viewer.loadData(block.dataset); //make sure the viewer is up to date gui.viewer.innerHTML = ""; if (viewer != null) viewer.draw(gui.viewer); if (viewer != null) viewer.clearTask(); //this is the context of this particular visualisation; //it's passed into the accuracy function (and anywhere else?) let context = { viewer : viewer, data : block.dataset, task : block.task, task_instance : instance, gui : gui } if (!("inputs" in block.task)) block.task.inputs = []; let paras = block.task.inputs.map( (input,index) => input.type == "question" || input.type == "output" ? instance.inputs[index] : null); //create gui outputs/answer options gui.answer.innerHTML = ""; let responseGetters = []; for (let k=0; k { let outputs = []; let guiIndex = 0; for (let k=0; k" + output.label + "" : ""; html += ""; div.innerHTML = html; return () => div.children[0].value; } else if (output.type == "short text"){ div.innerHTML = "" return () => div.children[0].value; } else if (output.type == "long text"){ div.innerHTML = "" return () => div.children[0].value; } else if (output.type == "integer"){ div.innerHTML = ""; return () => (div.children[0].value == "" || isNaN(parseFloat(div.children[0].value))) ? null : parseFloat(div.children[0].value) } } function createDefaultGUI(gui){ gui.innerHTML = ""; gui.style = "background-color : rgb(245,250,255)"; let tbl = document.createElement('table'); gui.appendChild(tbl); let r1 = tbl.insertRow(); let cell = r1.insertCell(); let next = document.createElement("button"); next.appendChild(document.createTextNode("Next")); cell.appendChild(next); let progress = document.createElement("span"); progress.style = "color : #888888"; progress.innerHTML = "(0% done)"; cell.appendChild(progress); cell = r1.insertCell(); let timeout = document.createElement("span"); timeout.style = "color : #660000"; timeout.innerHTML = ""; cell.appendChild(timeout); cell = r1.insertCell(); cell.style.textAlign = "right"; let correctness = document.createElement("span"); correctness.margin = "5px"; cell.appendChild(correctness); let checkAnswer = document.createElement("button"); checkAnswer.appendChild(document.createTextNode("Check answer")); checkAnswer.setAttribute("hidden",true); cell.appendChild(checkAnswer); let r2 = tbl.insertRow(); cell = r2.insertCell(); cell.colSpan = 2; let train = document.createElement("div"); train.style = "color:#883300"; train.setAttribute("hidden", true); train.innerHTML = "This is practice; check your answer before advancing; actual questions follow."; cell.appendChild(train); let question = document.createElement("div"); cell.appendChild(question); cell = r2.insertCell(); cell.style.textAlign = "right"; let answer = document.createElement("div"); cell.appendChild(answer); let viewer = document.createElement("div"); viewer.setAttribute("id", gui.getAttribute("id") + "_viewer"); gui.appendChild(viewer); return { question : question, answer : answer, next : next, check : checkAnswer, correctness : correctness, progress : progress, train : train, viewer : viewer, timeout : timeout }; } function clearGUI(gui){ gui.question.innerHTML = ""; gui.answer.innerHTML = ""; gui.correctness.innerHTML = ""; gui.correctness.hidden = true; gui.viewer.style.visibility = "visible"; gui.viewer.style.opacity = 1; gui.timeout.innerHTML = ""; } //helper: takes a number btw 0..1 and converts it to a string function formatAccuracy(accuracyNumber){ if (accuracyNumber == null) return "N/A"; if (accuracyNumber > 1) accuracyNumber = 1; if (accuracyNumber < 0) return "N/A"; if (accuracyNumber == 1) return "Correct"; else if (accuracyNumber == 0) return "Incorrect"; else return parseFloat(accuracyNumber*100).toPrecision(2) + "% Correct"; } function disableTrainingGUI(gui){ gui.check.hidden = true; gui.correctness.hidden = true; gui.train.hidden = true; } function enableTrainingGUI(gui){ gui.train.hidden = false; gui.next.disabled = true; gui.check.hidden = false; } /** -------------------------------------------------------------------- provides some default values when study options are left unspecified **/ function expandDesignDefaults(design){ //study if (typeof design.blocking == "undefined") design.blocking = "vtd"; if (typeof design.block_tasks == "undefined") design.block_tasks = []; //viewers if (typeof design.viewers.how == "undefined") design.viewers.how = "within"; //datasets if (typeof design.datasets.how == "undefined") design.datasets.how = "within"; //tasks if (typeof design.tasks.how == "undefined") design.tasks.how = "within"; for (let i = 0; i data = d; this.getData = () => data; this.clearTask = () => {}; this.draw = (div) => div.innerHTML = data != null ? data.content : ""; } this.tasks = new Object(); this.tasks.showHTML = (html) => { let ret = { task : { name : "html", question : "", description : "show html content", inputs : [], outputs : [], instances : []}, viewer : new HTMLViewer(), dataset : { name : "html", description : "html content", content : html}, showBefore : (b) => { ret.show = "before"; ret.block = b; return ret}, showAfter : (b) => { ret.show = "after"; ret.block = b; return ret}, exit : () => {ret.exit = true; return ret}}; return ret; } /** -------------------------------------------------------------------- adds up study(schedule) duration; by default does it for the entire study but second parameter can indicate how much of the schedule is considered **/ function scheduleDuration(schedule, upTo = schedule.length){ let duration = 0; for (let i=0; i< upTo; i++){ let block = schedule[i]; let nrInstances = typeof block.instances == "undefined" ? 1 : block.instances.length; duration += nrInstances*block.duration; } return duration; } this.addBlockTasks = (design, schedule, allBlockTasks) => { let seq = ["dataset", "task", "viewer", "study"]; seq.reverse(); for (let i=0; i bt.block.startsWith(factor[0])); blockTasks.reverse(); for (let j=0; j t == blockTasks[j]); let bt = blockTasks[j]; // console.log("getting blocks for ", bt.task.name); let blocks = []; //an array of arrays if (bt.block.endsWith("*") || factor == "study") blocks.push(this.getBlocks(design,schedule, factor, "*")); else //if factor = viewer => iterate through all viewers in the design; etc. for (let k=0; k b.length != 0); for (let k=0; k b == blocks[k][0].start); schedule.splice(insertionPoint,0,{type : "block_task", task : t, viewer : blocks[k][0].start.viewer, dataset : blocks[k][0].start.dataset}); } else if (bt.show == "before" || bt.show == "before each" || bt.show == "between"){ //we insert before each block for (let z = 0; z b == blocks[k][z].start); schedule.splice(insertionPoint,0,{type : "block_task", task : t, viewer : blocks[k][z].start.viewer, dataset : blocks[k][z].start.dataset}); } } else if (bt.show == "after last"){ //we insert after last block let insertionPoint = schedule.findIndex( b => b == blocks[k][blocks[k].length-1].end)+1; schedule.splice(insertionPoint,0,{type : "block_task", task : t, viewer : blocks[k][blocks[k].length-1].end.viewer, dataset : blocks[k][blocks[k].length-1].end.dataset}); } else if (bt.show == "after" || bt.show == "after each"){ //we insert after each block for (let z = 0; z b == blocks[k][z].end)+1; schedule.splice(insertionPoint,0,{type : "block_task", task : t, viewer : blocks[k][z].end.viewer, dataset : blocks[k][z].end.dataset}); } } } } } } this.getBlocks = (design, schedule, factor, level) => { //IMPORTANT //factors for block tasks and train tasks are actual objects //factors for eval tasks are indeces into design //eg. factor = viewer; level = 1 (= viewer 1) if (factor == "study") return [{start : schedule[0], end : schedule[schedule.length-1]}]; let ret = []; let currentBlock = {start : 0, end : -1}; for (let i=0; i ({start : schedule[b.start], end : schedule[b.end]})); } //MAIN PUBLIC FUNCTION //given a declarative study design, create study 'schedules' (or flows), //one for each participant group this.createStudySchedules = (design) => { expandDesignDefaults(design); //the 'schedules' are created and fleshed out in multiple steps: //FIRST, put together the schedules for the main testing part based of //the design (within/between..) and blocking orders; these won't include training tasks, //vis introductions, pre or post questionnaires; they also won't include task instances //viewers/datasets/and tasks are at this point refered by indeces in the viewer/dataset/task //arrays (e.g, design.viewers.which[index]) let schedules = createBlock(design.blocking, design); //SECOND, we add task training blocks schedules.map( s => addTraining(s, design)); //THIRD, add the block tasks schedules.map( s => this.addBlockTasks(design, s, design.block_tasks)); //FOURTH, we add task instance information to eval and train blocks schedules.map( s => assignInstances(s)); //return schedules; //if you want to see what the above produced. // console.log("schedulesWithInstances:",JSON.parse(JSON.stringify(schedules))); //FIFTH, fill the actual viewer and task objects instead of their indeces; //do a little more for tasks for (let i=0; i b.exit) < 0) schedules[i].push({ type : "block_task", exit : true, viewer : null, dataset : null, task : { name : "default exit", description : "A default VisUnit exit message", question : "This concludes the study. Thank you for participating!", inputs : [], outputs : [] }, duration : 5 }); return schedules; //Finally, order schedules by duration (so that similar schedules are grouped together // (this make it easier to display them in the StudyViewer) let newSchedules = []; let timelines = schedules.map( s=>createTimeline(s)); for (let i=0; i d1, d2, d3 // v => iv v1d1 v1d2 v1d3 rv // iv v2d1 v2d2 v2d3 rv // t => iv t1v1d1 t1v1d2 t1v1d3 rv iv t2v1d1 t2v1d2 t2v1d3 rv //stopping condition, return empty schedule list if (blocking === "") return [[{type : "eval_task"}]]; //get the schedule for the 'tail' of the blocking string //then add components corresponding to the 'head' of the //blocking string to it. let subSchedules = createBlock(blocking.substr(1), design); let schedules = null; if (blocking[0] == 'v') schedules = addToSchedules(subSchedules, 'viewer', design.viewers.which, design.viewers.how, design.block_tasks); else if (blocking[0] == 'd') schedules = addToSchedules(subSchedules, 'dataset', design.datasets.which, design.datasets.how, design.block_tasks); else if (blocking[0] == 't') schedules = addToSchedules(subSchedules, 'task', design.tasks.which, design.tasks.how, design.block_tasks); return schedules; } //private function: ... function addToSchedules(schedules, factorName, levels, design, allBlockTasks){ //first, check if there are block tasks for this factor let getBlockTasks = (show) => []; /* allBlockTasks.map ( (t,index) => index). filter( (ti => allBlockTasks[ti].block.startsWith(""+factorName[0]) && show.findIndex( s => s == allBlockTasks[ti].show) >= 0));*/ let newSchedules = []; if (design === 'between'){ for (let i=0; i schedule.splice(index,0,{type : "block_task", task : t, viewer : schedule[index].viewer, dataset : schedule[index].dataset})); getBlockTasks(["after","after each","after first", "after last"]) .map( (t,index) => schedule.push({ type : "block_task", task : t, viewer : schedule[schedule.length-1].viewer, dataset : schedule[schedule.length-1].dataset})); newSchedules.push(schedule); } } } else if (design == 'within'){ for (let i = 0; i schedule.splice(index,0,{type : "block_task", task : t, viewer : schedule[index].viewer, dataset : schedule[index].dataset})); let postBlocks = []; if (j == 0) postBlocks = getBlockTasks(["after", "after first", "after each","between"]); else if (j == levels.length-1) postBlocks = getBlockTasks(["after", "after last", "after each"]); else postBlocks = getBlockTasks(["after", "after each"]); postBlocks.map( (t,index) => schedule.push({type : "block_task", task : t, viewer : schedule[schedule.length-1].viewer, dataset : schedule[schedule.length-1].dataset})); newSchedule = newSchedule.concat(schedule); } newSchedules.push(newSchedule); } } else if (design == 'within-fully-counterbalanced' || design == 'within-latin-counterbalanced'){ let ordering = design == 'within-fully-counterbalanced' ? getFullCounterBalanceOrder(levels.length) : getLatinSquare(levels.length); for (let k=0; k schedule.splice(index,0,{type : "block_task", task : t, viewer : schedule[index].viewer, dataset : schedule[index].dataset})); let postBlocks = []; if (j == 0) postBlocks = getBlockTasks(["after", "after first", "after each","between"]); else if (j == levels.length-1) postBlocks = getBlockTasks(["after", "after last", "after each"]); else postBlocks = getBlockTasks(["after", "after each"]); postBlocks.map( (t,index) => schedule.push({task : t, type : "block_task", viewer : schedule[schedule.length-1].viewer, dataset : schedule[schedule.length-1].dataset})); newSchedule = newSchedule.concat(schedule); } newSchedules.push(newSchedule); } } } else{ //console.log("error in studyschedules.js: unrecognized design " + design); return null; } return newSchedules; } //simply adds a factor=level element to each item //on a schedule function addFactor(schedule, factorName, level){ //copy the schedule let newSchedule = JSON.parse(JSON.stringify(schedule)); //append the factor to the schedule for (let i=0; i block.type == "eval_task"); //get all tasks in schedule in order let allT = evalBlocks.map(block => block.task); let tasks = allT.filter( (block,index) => index == allT.findIndex( block2 => block2 == block)); //get all viewers in schedule in order let allV = evalBlocks.map(block => block.viewer); let viewers = allV.filter( (block,index) => index == allV.findIndex( block2 => block2 == block)); //get all datasets in schedule in order let allD = evalBlocks.map(block => block.dataset); let datasets = allD.filter( (block,index) => index == allD.findIndex( block2 => block2 == block)); //get all v*d combinations in order let allVD = evalBlocks.map(block => [block.viewer, block.dataset]); let vd = allVD.filter( (block,index) => index == allVD.findIndex( block2 => block2[0]==block[0] && block2[1]==block[1])); //go through all tasks but do it in reverse order //as this will help preserve the order of task training //when all training is done at the start of the study for (let ti = tasks.length-1; ti >=0; ti--){ let t = design.tasks.which[tasks[ti]]; let tIndex = tasks[ti]; if (typeof t.train == "undefined") continue; //no training needed let trains = t.train; //each task can be trained in multiple ways if (!(trains instanceof Array)) trains = [trains]; //for all of this task's training options for (let k=0; k trainBlockIndeces.push( s.findIndex( b => b.type == "eval_task" && b.task == tasks[ti] && b.viewer == v))); else if (what == "d") datasets.map( d => trainBlockIndeces.push( s.findIndex( b => b.type == "eval_task" && b.task == tasks[ti] && b.dataset == d))); else if (what == "vd" || what == "dv") vd.map( vd2 => trainBlockIndeces.push( s.findIndex( b => b.type == "eval_task" && b.task == tasks[ti] && b.viewer == vd2[0] && b.dataset == vd2[1]))); trainBlockIndeces = trainBlockIndeces.filter( tb => tb >= 0); //we have the indeces of the blocks that need to be trained for (let i=0; i tbi <= index ? tbi : tbi + 1); s.splice(index,0,newTrainingBlock); } else if (when == "study start"){ trainBlockIndeces = trainBlockIndeces.map( tbi => tbi <= i ? tbi : tbi + 1); s.splice(i,0, newTrainingBlock); } } } } } //private function: once the sequence of viewer x data x task conditions //for this study schedule (param: schedule) was established, we need to fill // in the task repeat information, i.e. expand each generic tasks with the // apropriate number of task repeats. Task repeats are selected from //allInstances function assignInstances(schedule){ //for "eval" and "train" blocks, block.task is an index to a prototypical //task (no repeats/instances). We want to expand this into an appropriate list of //taskInstances based on how many repeats the study design demands //only certain blocks need repeats: let needsRepeats = (block) => (block.type == "train" && block.repeats != undefined && block.task.inputs != undefined) || (block.type == "eval_task" && design.tasks.which[block.task].repeats != undefined && design.tasks.which[block.task].task.inputs != undefined) || (block.type == "block_task" && design.block_tasks[block.task].repeats != undefined && design.block_tasks[block.task].task.inputs != undefined) //init instances as empty lists; will fill them up after //only need instances for tasks with repeats for (let i=0; i ur[0] == task && ur[1] == data); if (urIndex >= 0) tdUsedRepeats = usedRepeats[urIndex][2]; else usedRepeats.push([task, data, tdUsedRepeats]); let instancesForData = task.task.instances.find(inst=>inst.data==data); //no instances for this combination of task x data combination if (instancesForData == undefined){ console.warn("No available instances for task = " + task.task.name + " and data = " + data.name); for (let r = 0; r ur == availableInstances[k]) < 0){ tdUsedRepeats.push(availableInstances[k]); block.instances.push(availableInstances[k]); found = true; break; } if (!found){ block.instances.push("unavailable - insufficient instances"); console.warn("Not enough instances for task = " + task.task.name + " and data = " + data.name); } } } for (let i = 0; i inst.data==data).instances; for (let k=0; k r == instancesForData[k]) >= 0){ used = true; break; } } if (!used && block.instances.length < block.repeats) block.instances.push(instancesForData[k]) } if (block.instances.length < block.repeats) console.warn("Not enough instances for task = " + task.name + " and data = " + data.name); while (block.instances.length < block.repeats) block.instances.push("not enough instances"); } } //private function: returns a latin square of given order function getLatinSquare(order){ if (order == 1) return [[1]]; else if (order == 2) return [[1,2], [2,1]]; else if (order == 3) return [[1,2,3], [2,3,1], [3,1,2]]; else if (order == 4) return [[1,2,3,4], [2,4,1,3], [3,1,4,2], [4,3,2,1]]; else if (order == 5) return [[1,2,3,4,5], [2,4,1,5,3], [3,5,4,2,1], [4,1,5,3,2], [5,3,2,1,4]] else return null; } //private function: gets full counter balanced matrix function getFullCounterBalanceOrder(order){ if (order == 1) return [[1]]; else if (order == 2) return [[1,2], [2,1]]; else if (order == 3) return [[1,2,3], [1,3,2], [2,1,3], [2,3,1], [3,1,2], [3,2,1]]; else if (order == 4) return [[1,2,3,4], [1,2,4,3], [1,3,2,4], [1,3,4,2], [1,4,2,3], [1,4,3,2], [2,1,3,4], [2,1,4,3], [2,3,1,4], [2,3,4,1], [2,4,1,3], [2,4,3,1], [3,1,2,4], [3,1,4,2], [3,2,1,4], [3,2,4,1], [3,4,1,2], [3,4,2,1], [4,1,2,3], [4,1,3,2], [4,2,1,3], [4,2,3,1], [4,3,1,2], [4,3,2,1]]; else return null; } } }