mirror of
https://github.com/jspsych/jsPsych.git
synced 2025-05-11 16:18:11 +00:00
Pushed inital version of documentation for metadata
This commit is contained in:
vzhang03
parent
8e9835f285
commit
32c0917525
@ -1,20 +1,35 @@
|
||||
# Metadata Module
|
||||
|
||||
The metadata module contains functions for interacting metadata according to [Psych-DS standards](https://psych-ds.github.io/). To interact with the metadata, we strongly recommend you call the generate method on the experiment data then adjust fields accordingly. The generate method uses documentation for plugins and extensions created in the main JsPsych repo to create default descriptions. This works best for experiments run in v8+, but will also work for old experimental data.
|
||||
The metadata module contains functions for interacting metadata according to [Psych-DS standards](https://psych-ds.github.io/). To interact with the metadata, we strongly recommend you call the generate method on the experiment data then adjust fields accordingly. The generate method uses documentation for plugins and extensions created in the main JsPsych repo to create default descriptions. This works best for experiments run in v8+, but will also work for old experimental data.
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## metadata.generate
|
||||
|
||||
```javascript
|
||||
var metadata = new jsPsychMetadata();
|
||||
metadata.generate(properties);
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Type | Description
|
||||
----------|------|------------
|
||||
| data | object, string | Can be passed|
|
||||
| metadata | object | Optional metadata that can be passed in to adjust the output of the generate method. Each key-value pair will map to a parameter field, and will either overwite existing data or create new fields. All normal fields can be adjusted as entries within the object, but for authors and variables the entries need to be nested within an "author" or "variables" key mapping. Similarily, updating the descriptions of variables needs to be a nested map. |
|
||||
| csv | boolean| Optional flag that should be marked true if data is in a string csv format. If passing in as an object or Json should left false. |
|
||||
|
||||
### Return value
|
||||
|
||||
Returns nothing.
|
||||
|
||||
### Description
|
||||
|
||||
This method creates metadata using data from JsPsych experiments by loading and parsing plugin information. This method allows you to adjust the fields by specifying an object with the fields, authors and variables with the changes. This accepts both csv and json strings, and if passing in a csv will need to specify the boolean csv flag.
|
||||
|
||||
### Examples
|
||||
|
||||
|
||||
|
||||
#### Calling metadata after running an experiment
|
||||
#### Calling metadata after running an experiment and adjusting fields
|
||||
|
||||
```javascript
|
||||
var metadata = new jsPsychMetadata();
|
||||
@ -24,7 +39,7 @@ const metadata_options = {
|
||||
author: {
|
||||
"John": {
|
||||
name: "John",
|
||||
givenName: "Johnathan",
|
||||
givenName: "Jonathan",
|
||||
},
|
||||
},
|
||||
variables: {
|
||||
@ -40,14 +55,102 @@ const metadata_options = {
|
||||
}
|
||||
|
||||
var jsPsych = initJsPsych({
|
||||
on_finish: async function() {
|
||||
await metadata.generate(jsPsych.data.get().json());
|
||||
on_finish: async function() {
|
||||
await metadata.generate(jsPsych.data.get().json(), metadata_options);
|
||||
},
|
||||
default_iti: 250
|
||||
});
|
||||
```
|
||||
|
||||
#### Calling metadata on data loaded locally
|
||||
---
|
||||
|
||||
## metadata.getMetadata
|
||||
|
||||
```javascript
|
||||
var metadata = new jsPsychMetadata();
|
||||
metadata.getMetadata();
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
No parameters.
|
||||
|
||||
### Return value
|
||||
|
||||
Returns the metadata as an object.
|
||||
|
||||
### Description
|
||||
|
||||
This method allows you to access the metadata for processes.
|
||||
|
||||
---
|
||||
|
||||
## metadata.localSave
|
||||
|
||||
```javascript
|
||||
var metadata = new jsPsychMetadata();
|
||||
metadata.localSave();
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
No parameters.
|
||||
|
||||
### Return value
|
||||
|
||||
Returns nothing. Downloads file locally.
|
||||
|
||||
### Description
|
||||
|
||||
This method allows you download the metadata in the format specified as Psych-DS, a json file named "dataset_description.json".
|
||||
|
||||
---
|
||||
|
||||
## metadata.updateMetadata
|
||||
|
||||
```javascript
|
||||
var metadata = new jsPsychMetadata();
|
||||
metadata.updateMetadata();
|
||||
```
|
||||
### Parameters
|
||||
|
||||
| Parameter | Type | Description
|
||||
----------|------|------------
|
||||
| metadata | object | Optional metadata that can be passed in to adjust the output of the generate method. Each key-value pair will map to a parameter field, and will either overwite existing data or create new fields. All normal fields can be adjusted as entries within the object, but for authors and variables the entries need to be nested within an "author" or "variables" key mapping. Similarily, updating the descriptions of variables needs to be a nested map. |
|
||||
|
||||
### Return value
|
||||
|
||||
Returns nothing.
|
||||
|
||||
### Description
|
||||
|
||||
This method allows you to adjust the fields by specifying an object with the fields, authors and variables with the changes. This method can also allow you to generate the metadata from scratch.
|
||||
|
||||
### Examples
|
||||
|
||||
#### Calling metadata after running an experiment and adjusting fields
|
||||
|
||||
```javascript
|
||||
var metadata = new jsPsychMetadata();
|
||||
|
||||
const metadata_options = {
|
||||
randomField: "this is a field",
|
||||
author: {
|
||||
"John": {
|
||||
name: "John",
|
||||
givenName: "Jonathan",
|
||||
},
|
||||
},
|
||||
variables: {
|
||||
"trial_type" : {
|
||||
description: {
|
||||
"chat-plugin": "this chat plugin allows you to talk to gpt!",
|
||||
}
|
||||
},
|
||||
"trial_index": {
|
||||
name: "index",
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
await metadata.updateMetadata(metadata_options);
|
||||
```
|
||||
@ -1,5 +1,6 @@
|
||||
import { AuthorFields, AuthorsMap } from "./AuthorsMap";
|
||||
import { PluginCache } from "./PluginCache";
|
||||
import { saveTextToFile } from "./utils";
|
||||
import { VariableFields, VariablesMap } from "./VariablesMap";
|
||||
|
||||
/**
|
||||
@ -60,7 +61,7 @@ export default class JsPsychMetadata {
|
||||
* @param {string} key - Metadata field name
|
||||
* @param {*} value - Data associated with the field
|
||||
*/
|
||||
setMetadataField(key: string, value: any): void {
|
||||
private setMetadataField(key: string, value: any): void {
|
||||
this.metadata[key] = value;
|
||||
}
|
||||
|
||||
@ -70,7 +71,7 @@ export default class JsPsychMetadata {
|
||||
* @param {string} key - Field name
|
||||
* @returns {*} - Data associated with the field
|
||||
*/
|
||||
getMetadataField(key: string): any {
|
||||
private getMetadataField(key: string): any {
|
||||
return this.metadata[key];
|
||||
}
|
||||
|
||||
@ -94,7 +95,7 @@ export default class JsPsychMetadata {
|
||||
*
|
||||
* @param {AuthorFields | string} author - All the required or possible fields associated with listing an author according to Psych-DS standards. Option as a string to define an author according only to name.
|
||||
*/
|
||||
setAuthor(fields: AuthorFields): void {
|
||||
private setAuthor(fields: AuthorFields): void {
|
||||
this.authors.setAuthor(fields); // Assuming `authors` is an instance of the AuthorsMap class
|
||||
}
|
||||
|
||||
@ -104,7 +105,7 @@ export default class JsPsychMetadata {
|
||||
* @param {string} name - Name of author to be used as key.
|
||||
* @returns {(AuthorFields | string | {})} - Object with author information. Empty object if not found.
|
||||
*/
|
||||
getAuthor(name: string): AuthorFields | string | {} {
|
||||
private getAuthor(name: string): AuthorFields | string | {} {
|
||||
return this.authors.getAuthor(name);
|
||||
}
|
||||
|
||||
@ -128,7 +129,7 @@ export default class JsPsychMetadata {
|
||||
* privacy?: string;
|
||||
* }} fields - Fields associated with the current Psych-DS standard.
|
||||
*/
|
||||
setVariable(variable: VariableFields): void {
|
||||
private setVariable(variable: VariableFields): void {
|
||||
this.variables.setVariable(variable);
|
||||
}
|
||||
|
||||
@ -139,11 +140,11 @@ export default class JsPsychMetadata {
|
||||
* @param {string} name - Name of variable to be accessed
|
||||
* @returns {{}} - Returns object of fields
|
||||
*/
|
||||
getVariable(name: string): {} {
|
||||
private getVariable(name: string): {} {
|
||||
return this.variables.getVariable(name);
|
||||
}
|
||||
|
||||
containsVariable(name: string): boolean {
|
||||
private containsVariable(name: string): boolean {
|
||||
return this.variables.containsVariable(name);
|
||||
}
|
||||
|
||||
@ -155,7 +156,7 @@ export default class JsPsychMetadata {
|
||||
* @param {string} field_name - Name of field to be updated.
|
||||
* @param {(string | boolean | number | {})} added_value - Value to be used in the update.
|
||||
*/
|
||||
updateVariable(
|
||||
private updateVariable(
|
||||
var_name: string,
|
||||
field_name: string,
|
||||
added_value: string | boolean | number | {}
|
||||
@ -168,7 +169,7 @@ export default class JsPsychMetadata {
|
||||
*
|
||||
* @param {string} var_name - Name of variable to be deleted.
|
||||
*/
|
||||
deleteVariable(var_name: string): void {
|
||||
private deleteVariable(var_name: string): void {
|
||||
this.variables.deleteVariable(var_name);
|
||||
}
|
||||
|
||||
@ -177,7 +178,7 @@ export default class JsPsychMetadata {
|
||||
*
|
||||
* @returns {string[]} - List of variable string names.
|
||||
*/
|
||||
getVariableNames(): string[] {
|
||||
private getVariableNames(): string[] {
|
||||
return this.variables.getVariableNames();
|
||||
}
|
||||
|
||||
@ -189,7 +190,6 @@ export default class JsPsychMetadata {
|
||||
displayMetadata(display_element) {
|
||||
const elementId = "jspsych-metadata-display";
|
||||
const metadata_string = JSON.stringify(this.getMetadata(), null, 2);
|
||||
// const display_element = this.JsPsych.getDisplayElement();
|
||||
display_element.innerHTML += `<p id="jspsych-metadata-header">Metadata</p><pre id="${elementId}" class="jspsych-preformat"></pre>`;
|
||||
document.getElementById(elementId).textContent += metadata_string;
|
||||
}
|
||||
@ -198,19 +198,9 @@ export default class JsPsychMetadata {
|
||||
* Method that begins a download for the dataset_description.json at the end of experiment.
|
||||
* Allows you to download the metadat.
|
||||
*/
|
||||
saveAsJsonFile(): void {
|
||||
const jsonString = JSON.stringify(this.getMetadata(), null, 2);
|
||||
const blob = new Blob([jsonString], { type: "application/json" });
|
||||
const url = URL.createObjectURL(blob);
|
||||
|
||||
const a = document.createElement("a");
|
||||
a.href = url;
|
||||
a.download = "dataset_description.json";
|
||||
document.body.appendChild(a);
|
||||
a.click();
|
||||
document.body.removeChild(a);
|
||||
|
||||
URL.revokeObjectURL(url);
|
||||
localSave() {
|
||||
let data_string = JSON.stringify(this.getMetadata());
|
||||
saveTextToFile(data_string, "dataset_description.json");
|
||||
}
|
||||
|
||||
/**
|
||||
@ -428,4 +418,10 @@ export default class JsPsychMetadata {
|
||||
private async getPluginInfo(pluginType: string, variableName: string, version, extension?) {
|
||||
return this.pluginCache.getPluginInfo(pluginType, variableName, version, extension);
|
||||
}
|
||||
|
||||
updateMetadata(metadata) {
|
||||
for (const key in metadata) {
|
||||
this.processMetadata(metadata, key);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
19
packages/metadata/src/utils.ts
Normal file
19
packages/metadata/src/utils.ts
Normal file
@ -0,0 +1,19 @@
|
||||
// private function to save text file on local drive
|
||||
export function saveTextToFile(textstr: string, filename: string) {
|
||||
const blobToSave = new Blob([textstr], {
|
||||
type: "text/plain",
|
||||
});
|
||||
let blobURL = "";
|
||||
if (typeof window.webkitURL !== "undefined") {
|
||||
blobURL = window.webkitURL.createObjectURL(blobToSave);
|
||||
} else {
|
||||
blobURL = window.URL.createObjectURL(blobToSave);
|
||||
}
|
||||
|
||||
const link = document.createElement("a");
|
||||
link.id = "jspsych-download-as-text-link";
|
||||
link.style.display = "none";
|
||||
link.download = filename;
|
||||
link.href = blobURL;
|
||||
link.click();
|
||||
}
|
||||
Loading…
Reference in New Issue
Block a user