diff --git a/packages/jspsych/src/JsPsych.ts b/packages/jspsych/src/JsPsych.ts index 8853a0b9..07165483 100644 --- a/packages/jspsych/src/JsPsych.ts +++ b/packages/jspsych/src/JsPsych.ts @@ -959,9 +959,9 @@ export class JsPsych { /** * Method that clears the screen, printing data and metadata allowing the researcher to view both post-trial. * - * @param {string} [dataFormat="json"] - * @param {string} [dataElementId="jspsych-data-display"] - * @param {string} [metadataElementId="jspsych-metadata-display"] + * @param {string} [dataFormat="json"] - The format in which data should be displayed. Defaults to "json". + * @param {string} [dataElementId="jspsych-data-display"] - The ID of the HTML element where the data will be displayed. + * @param {string} [metadataElementId="jspsych-metadata-display"] - The ID of the HTML element where the metadata will be displayed. */ displayDataAndMetadata( dataFormat = "json", diff --git a/packages/jspsych/src/modules/metadata/AuthorsMap.ts b/packages/jspsych/src/modules/metadata/AuthorsMap.ts index 3b28bc99..f5205c89 100644 --- a/packages/jspsych/src/modules/metadata/AuthorsMap.ts +++ b/packages/jspsych/src/modules/metadata/AuthorsMap.ts @@ -1,10 +1,35 @@ +/** + * Class that helps keep track of authors and allows for easy conversion to list format when + * generating the final Metadata file. + * + * @export + * @class AuthorsMap + * @typedef {AuthorsMap} + */ export class AuthorsMap { + /** + * Field that keeps track of the authors in a map. + * + * @private + * @type {({ [key: string]: {} | string })} + */ private authors: { [key: string]: {} | string }; // Define the type for authors + /** + * Creates an empty instance of authors map. Doesn't generate default metadata because + * can't assume anything about the authors. + * + * @constructor + */ constructor() { this.authors = {}; } + /** + * Returns the final list format of the authors according to Psych-DS standards. + * + * @returns {({} | string)[]} - List of authors + */ getList(): ({} | string)[] { const author_list = []; for (const key of Object.keys(this.authors)) { @@ -13,7 +38,18 @@ export class AuthorsMap { return author_list; } - // overwrites previous author when used + /** + * Method that creates an author. This method can also be used to overwrite existing authors + * with the same name in order to update fields. + * + * @param {{ + * type?: string; + * name: string; + * givenName?: string; // required + * familyName?: string; + * identifier?: string; // identifier that distinguish across dataset (URL), confusing should check description + * }} fields - All the required or possible fields associated with listing an author according to Psych-DS standards. + */ setAuthor(fields: { type?: string; name: string; @@ -38,7 +74,12 @@ export class AuthorsMap { this.authors[new_variable.name] = new_variable; } - // lets you edit specific fields if you access it + /** + * Method that fetches an author object allowing user to update (in existing workflow should not be necessary). + * + * @param {string} name - Name of author to be used as key. + * @returns {{}} - Object with author information. + */ getAuthor(name: string): {} { if (name in this.authors) { return this.authors[name]; diff --git a/packages/jspsych/src/modules/metadata/VariablesMap.ts b/packages/jspsych/src/modules/metadata/VariablesMap.ts index 1e737242..02a019a3 100644 --- a/packages/jspsych/src/modules/metadata/VariablesMap.ts +++ b/packages/jspsych/src/modules/metadata/VariablesMap.ts @@ -1,11 +1,33 @@ +/** + * Custom class that stores and handles the storage, update and retrieval of variable metadata. + * + * @export + * @class VariablesMap + * @typedef {VariablesMap} + */ export class VariablesMap { + /** + * Field that holds a map of the current variables allowing for fast look-up. + * + * @private + * @type {{}} + */ private variables: {}; + /** + * Creates the VariablesMap bycalling generateDefaultVariables() method to + * generate the basic metadata common to every dataset_description.json file. + * + * @constructor + */ constructor() { this.generateDefaultVariables(); } - // trial type, trial index, time elapsed, interal typenode id - can add more below + /** + * Generates the default variables shared between every JsPsych experiment and fills in + * with filler descriptions for reseachers to change. + */ generateDefaultVariables(): void { this.variables = {}; @@ -50,6 +72,11 @@ export class VariablesMap { this.setVariable(internal_type_node_id); } + /** + * Returns a list of the variables instead of an object according to the Psych-DS format. + * + * @returns {{}[]} - The list of variables represented as objects. + */ getList(): {}[] { var var_list = []; for (const key of Object.keys(this.variables)) { @@ -58,7 +85,27 @@ export class VariablesMap { return var_list; } - // could replace this method and instead pass in fields directly, would make it faster + /** + * Allows user to set a variable and includes all the fields that are possible according to + * Psych-DS guidelines. Only requires the name field which it uses a key to map to the variable. + * Can also be used to overwrite existing variables if they have the same name. + * + * @param {{ + * type?: string; + * name: string; // required + * description?: string | {}; + * value?: string; // string, boolean, or number + * identifier?: string; // identifier that distinguish across dataset (URL), confusing should check description + * minValue?: number; + * maxValue?: number; + * levels?: string[] | []; // technically property values in the other one but not sure how to format it + * levelsOrdered?: boolean; + * na?: boolean; + * naValue?: string; + * alternateName?: string; + * privacy?: string; + * }} fields - Input fields as specified by Psych-DS standards. + */ setVariable(fields: { type?: string; name: string; // required @@ -86,10 +133,22 @@ export class VariablesMap { this.variables[new_variable.name] = new_variable; } + /** + * Allows you to get information for a single variable returning empty dict if it doesn't exist. + * Allows you to update fields but not recommended in favor of updateVariable. + * + * @param {string} name - Name of variable to map to. + * @returns {{}} - Variable information or empty dict if doesn't exist + */ getVariable(name: string): {} { return this.variables[name] || {}; } + /** + * Method that gets a list of the names of variables. + * + * @returns {string[]} - String list containing names of existing variables. + */ getVariableNames(): string[] { var var_list = []; for (const key of Object.keys(this.variables)) { @@ -99,7 +158,15 @@ export class VariablesMap { return var_list; } - // levels, description + /** + * Allows you to update a variable or add a value in the case of updating values. In other situations will + * replace the existing value with the new value. Has special cases and logic for levels and names making it + * easier to update variable values. + * + * @param {string} var_name + * @param {string} field_name + * @param {(string | boolean | number | {})} added_value + */ updateVariable( var_name: string, field_name: string, @@ -145,6 +212,11 @@ export class VariablesMap { } } + /** + * Allows you to delete a variable by key/name. Returns console error if not found. + * + * @param {string} var_name - Name of variable to be deleted. + */ deleteVariable(var_name: string): void { if (var_name in this.variables) { delete this.variables[var_name]; @@ -152,24 +224,4 @@ export class VariablesMap { console.error(`Variable "${var_name}" does not exist.`); } } - - updateVariableTest(): void { - // editing new variables - const test_var = { - type: "PropertyValue", - name: "Test", - description: "Random description", - value: "numeric", - }; - this.setVariable(test_var); - this.updateVariable("Test", "levels", "
hello world
"); - this.updateVariable("Test", "levels", "......spot me......
"); - - this.updateVariable("Test", "name", "NewTest"); - // jsPsych.metadata.deleteVariable("Test"); - // jsPsych.metadata.deleteVariable("NewTest"); - this.updateVariable("NewTest", "minValue", 10); - this.updateVariable("NewTest", "description", "this is a new description"); - } } diff --git a/packages/jspsych/src/modules/metadata/index.ts b/packages/jspsych/src/modules/metadata/index.ts index 4567ebc2..5862a10e 100644 --- a/packages/jspsych/src/modules/metadata/index.ts +++ b/packages/jspsych/src/modules/metadata/index.ts @@ -3,7 +3,7 @@ import { AuthorsMap } from "./AuthorsMap"; import { VariablesMap } from "./VariablesMap"; /** - * Description placeholder + * Class that handles the storage, update and retrieval of Metadata. * * @export * @class JsPsychMetadata @@ -11,21 +11,21 @@ import { VariablesMap } from "./VariablesMap"; */ export class JsPsychMetadata { /** - * Description placeholder + * Field that contains all metadata fields that aren't represented as a list. * * @private * @type {{}} */ private metadata: {}; /** - * Description placeholder + * Custom class that stores and handles the storage, update and retrieval of author metadata. * * @private * @type {AuthorsMap} */ private authors: AuthorsMap; /** - * Description placeholder + * Custom class that stores and handles the storage, update and retrieval of variable metadata. * * @private * @type {VariablesMap} @@ -33,7 +33,8 @@ export class JsPsychMetadata { private variables: VariablesMap; /** - * Creates an instance of JsPsychMetadata. + * Creates an instance of JsPsychMetadata while passing in JsPsych object to have access to context + * allowing it to access the screen printing information. * * @constructor * @param {JsPsych} JsPsych @@ -41,10 +42,11 @@ export class JsPsychMetadata { constructor(private JsPsych: JsPsych) { this.generateDefaultMetadata(); } - - // Can update with more important information + w; /** - * Description placeholder + * Method that fills in JsPsychMetadata class with all the universal fields with default information. + * This is automatically called whenever creating an instance of JsPsychMetadata and indicates all + * the required fields that need to filled in to be Psych-DS compliant. */ generateDefaultMetadata(): void { this.metadata = {}; @@ -55,32 +57,31 @@ export class JsPsychMetadata { this.variables = new VariablesMap(); } - // Methods for accessing and setting simple fields /** - * Description placeholder + * Method that sets simple metadata fields. This method can also be used to update/overwrite existing fields. * - * @param {string} key - * @param {*} value + * @param {string} key - Metadata field name + * @param {*} value - Data associated with the field */ setMetadataField(key: string, value: any): void { this.metadata[key] = value; } /** - * Description placeholder + * Simple get that accesses the data associated with a field. * - * @param {string} key - * @returns {*} + * @param {string} key - Field name + * @returns {*} - Data associated with the field */ getMetadataField(key: string): any { return this.metadata[key]; } - // To get the final data /** - * Description placeholder + * Returns the final Metadata in a single javascript object. Bundles together the author and variables + * together in a list rather than object compliant with Psych-DS standards. * - * @returns {{}} + * @returns {{}} - Final Metadata object */ getMetadata(): {} { const res = this.metadata; @@ -90,17 +91,17 @@ export class JsPsychMetadata { return res; } - // may need to include, missing documentation in the document /** - * Description placeholder + * Method that creates an author. This method can also be used to overwrite existing authors + * with the same name in order to update fields. * * @param {{ * type?: string; * name: string; - * givenName?: string; // required + * givenName?: string; * familyName?: string; - * identifier?: string; // identifier that distinguish across dataset (URL), confusing should check description - * }} fields + * identifier?: string; + * }} fields - All the required or possible fields associated with listing an author according to Psych-DS standards. */ setAuthor(fields: { type?: string; @@ -113,18 +114,18 @@ export class JsPsychMetadata { } /** - * Description placeholder + * Method that fetches an author object allowing user to update (in existing workflow should not be necessary). * - * @param {string} name - * @returns {{}} + * @param {string} name - Name of author to be used as key. + * @returns {{}} - Object with author information. */ getAuthor(name: string): {} { return this.authors.getAuthor(name); } - // Simple set will overwrite, get structure so that can get fields and return /** - * Description placeholder + * Method that creates a variable. This method can also be used to overwrite variables with the same name + * as a way to update fields. * * @param {{ * type?: string; @@ -140,7 +141,7 @@ export class JsPsychMetadata { * naValue?: string; * alternateName?: string; * privacy?: string; - * }} fields + * }} fields - Fields associated with the current Psych-DS standard. */ setVariable(fields: { type?: string; @@ -160,23 +161,24 @@ export class JsPsychMetadata { this.variables.setVariable(fields); } - // saving a variable /** - * Description placeholder + * Allows you to access a variable's information by using the name of the variable. Can + * be used to update fields within a variable, but suggest using updateVariable() to prevent errors. * - * @param {string} name - * @returns {{}} + * @param {string} name - Name of variable to be accessed + * @returns {{}} - Returns object of fields */ getVariable(name: string): {} { return this.variables.getVariable(name); } /** - * Description placeholder + * Allows you to update a variable or add a value in the case of updating values. In other situations will + * replace the existing value with the new value. * - * @param {string} var_name - * @param {string} field_name - * @param {(string | boolean | number | {})} added_value + * @param {string} var_name - Name of variable to be updated. + * @param {string} field_name - Name of field to be updated. + * @param {(string | boolean | number | {})} added_value - Value to be used in the update. */ updateVariable( var_name: string, @@ -187,26 +189,27 @@ export class JsPsychMetadata { } /** - * Description placeholder + * Allows you to delete a variable by key/name. * - * @param {string} var_name + * @param {string} var_name - Name of variable to be deleted. */ deleteVariable(var_name: string): void { this.variables.deleteVariable(var_name); } /** - * Description placeholder + * Gets a list of all the variable names. * - * @returns {string[]} + * @returns {string[]} - List of variable string names. */ getVariableNames(): string[] { return this.variables.getVariableNames(); } - // display at the end of the experiment /** - * Description placeholder + * Method that allows you to display metadata at the end of an experiment. + * + * @param {string} [elementId="jspsych-metadata-display"] - Id for how to style the metadata. Defaults to default styling. */ displayMetadata(elementId = "jspsych-metadata-display") { const metadata_string = JSON.stringify(this.getMetadata(), null, 2); @@ -215,9 +218,9 @@ export class JsPsychMetadata { document.getElementById(elementId).textContent = metadata_string; } - // Method to save metadata as JSON file /** - * Description placeholder + * Method that begins a download for the dataset_dea.cription.json at the end of experiment. + * Allows you to download the metadat. */ saveAsJsonFile(): void { const jsonString = JSON.stringify(this.getMetadata(), null, 2); @@ -233,52 +236,4 @@ export class JsPsychMetadata { URL.revokeObjectURL(url); } - - // method testing different get and set methods and generating fake metadata - /** - * Description placeholder - */ - generateFakeMetadata(): void { - const author1 = { - name: "John Cena", - }; - this.setAuthor(author1); - - const author2 = { - name: "Wreck-it-Ralph", - identifier: "www.google.com", - }; - this.setAuthor(author2); - - const prop_value_var = { - type: "PropertyValue", - name: "Response Time (rt)", - description: "Time participant takes to respond to a stimulus", - value: "numeric", - minValue: 0, - maxValue: 10000, - }; - this.setVariable(prop_value_var); - - const stimulus_var = { - type: "PropertyValue", - name: "Stimulus", - description: { - "+
": - "This is a fixation screen that helps concentrate focus", - '["img/happy_face_1.jpg", "img/happy_face_2.jpg","img/happy_face_3.jpg"]': - "These are different pictures of peoples faces that we using for the study", - }, - value: "null", - levels: [ - "+
", - "img/happy_face_1.jpg", - "img/happy_face_2.jpg", - "img/happy_face_3.jpg", - ], - }; - this.setVariable(stimulus_var); - - return; - } }