diff --git a/CHANGELOG.md b/CHANGELOG.md index 822c21db..85a5ce00 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog +## [1.1.0] - 2023-06-27 + +### Added + +- option to save screenshot of results [#230](https://github.com/ssciwr/vstt/pull/230) +- optional delay before central target is displayed [#228](https://github.com/ssciwr/vstt/pull/228) + +### Changed + +- trial stops when maximum condition time exceeded instead of allowing trial to complete [#229](https://github.com/ssciwr/vstt/pull/229) + ## [1.0.0] - 2023-06-26 First official release. diff --git a/docs/index.rst b/docs/index.rst index 8416a40f..da8d5df6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,6 +18,7 @@ Visuomotor Serial Targeting Task (VSTT) reference/trial-conditions reference/statistics reference/framerate + reference/file-formats .. toctree:: :maxdepth: 2 diff --git a/docs/quickstart/display-results.rst b/docs/quickstart/display-results.rst index a1ef7dda..570358e0 100644 --- a/docs/quickstart/display-results.rst +++ b/docs/quickstart/display-results.rst @@ -1,8 +1,10 @@ Displaying results ================== -To display the results from a trial, select it from the list and click "Display Trial". -You can also display all the trials with the same conditions with "Display Condition". +To display the results from a trial, select it from the list and click "View Trial". +Alternatively click "Image Trial" to save a screenshot of these results as a png image file. +For combined results from all the trials with the same trial conditions as the selected trial, +click "View Condition" or "Image Condition". .. figure:: images/results-list.png :alt: Results diff --git a/docs/quickstart/images/gui.png b/docs/quickstart/images/gui.png index 0252401f..b493448b 100644 Binary files a/docs/quickstart/images/gui.png and b/docs/quickstart/images/gui.png differ diff --git a/docs/quickstart/images/results-list.png b/docs/quickstart/images/results-list.png index 84263d16..ec218b9c 100644 Binary files a/docs/quickstart/images/results-list.png and b/docs/quickstart/images/results-list.png differ diff --git a/docs/quickstart/share-experiment.rst b/docs/quickstart/share-experiment.rst index 3632970e..2fdd183a 100644 --- a/docs/quickstart/share-experiment.rst +++ b/docs/quickstart/share-experiment.rst @@ -1,96 +1,13 @@ Sharing experiments =================== -Experiments can be exported in different formats: psydat, Excel, and json. -Psydat is the default format used by VSTT, -which can also be opened from Python scripts or Jupyter notebooks. -The Excel and json formats are provided to allow experiments -and results to be shared, analysed and modified -without requiring the VSTT software to do so. - -.. list-table:: File format comparison - :widths: 25 25 25 25 - :header-rows: 1 - - * - - - psydat - - Excel - - json - * - Export experiment - - Yes - - Yes - - Yes - * - Import experiment - - Yes - - Yes - - Yes - * - Export results - - Yes - - Yes - - No - * - Import results - - Yes - - No - - No - -psydat ------- - -This is the default file format, which includes the experiment results. -These files can be opened in the VSTT GUI or in Python -(see the example notebook for more information). - -Excel ------ - -Experiments can also be exported as Excel spreadsheets. -The first 3 pages in the spreadsheet define the experiment: +There are several ways to share experiment setups and results with others. -* metadata -* display_options -* trial_list +If they also install VSTT then you can simply share the .psydat file, +which contains both the experimental setup and any results. -These values can be edited in Excel and then the modified experiment can -be opened in the VSTT GUI (File -> Open, choose Excel as filetype). -Note that results are not imported from an Excel file. - -The excel sheet also contains a statistics page with calculated statistics for each trial. -Then there is a sheet of data for each trial in the experiment with the following columns: - -* timestamps - * start at 0 for each trial, increase throughout the trial -* mouse_positions_x - * x coordinate of mouse at this timestamp -* mouse_positions_y - * y coordinate of mouse at this timestamp -* i_target - * ``-99`` if no target is visible - * ``-1`` if central target is visible - * otherwise index (e.g. ``0``, ``1``, etc) of current displayed target -* target_x - * x coordinate of currently visible target - * ``-99`` if no target is visible -* target_y - * y coordinate of currently visible target - * ``-99`` if no target is visible - -There is also the option to export a separate page of data for each target, -so a single trial with 8 targets would result in 8 separate pages of experiment data. -In this case for each target the timestamps begin at a negative value, -and reach zero when the target is displayed. - -json ----- - -Experiments can also be exported as a json text file. -This is a convenient format for sharing experimental setups, -as it can be easily read and modified in a text editor. -These files can also be opened in the VSTT GUI -(File -> Open, choose JSON as filetype). -The json file contains all the information required to define the experiment: - -* metadata -* display_options -* trial_list +You can also export experiments in Excel or json format, +which allows experiments and results to be shared, analysed and modified +without requiring the VSTT software to do so. -This format does not include any statistics or experimental results. +See :doc:`File formats <../reference/file-formats>` for more information. diff --git a/docs/reference/file-formats.rst b/docs/reference/file-formats.rst new file mode 100644 index 00000000..2322b464 --- /dev/null +++ b/docs/reference/file-formats.rst @@ -0,0 +1,96 @@ +File formats +============ + +Experiments can be imported and exported in different formats: psydat, Excel, and json. +Psydat is the default format used by VSTT, +which can also be opened from Python scripts or Jupyter notebooks. +The Excel and json formats are provided to allow experiments +and results to be shared, analysed and modified +without requiring the VSTT software to do so. + +.. list-table:: File format comparison + :widths: 25 25 25 25 + :header-rows: 1 + + * - + - psydat + - Excel + - json + * - Export experiment + - Yes + - Yes + - Yes + * - Import experiment + - Yes + - Yes + - Yes + * - Export results + - Yes + - Yes + - No + * - Import results + - Yes + - No + - No + +psydat +------ + +This is the default file format, which includes the experiment results. +These files can be opened in the VSTT GUI or in Python +(see the example notebook for more information). + +Excel +----- + +Experiments can also be exported as Excel spreadsheets. +The first 3 pages in the spreadsheet define the experiment: + +* metadata +* display_options +* trial_list + +These values can be edited in Excel and then the modified experiment can +be opened in the VSTT GUI (File -> Open, choose Excel as filetype). +Note that results are not imported from an Excel file. + +The excel sheet also contains a statistics page with calculated statistics for each trial. +Then there is a sheet of data for each trial in the experiment with the following columns: + +* timestamps + * start at 0 for each trial, increase throughout the trial +* mouse_positions_x + * x coordinate of mouse at this timestamp +* mouse_positions_y + * y coordinate of mouse at this timestamp +* i_target + * ``-99`` if no target is visible + * ``-1`` if central target is visible + * otherwise index (e.g. ``0``, ``1``, etc) of current displayed target +* target_x + * x coordinate of currently visible target + * ``-99`` if no target is visible +* target_y + * y coordinate of currently visible target + * ``-99`` if no target is visible + +There is also the option to export a separate page of data for each target, +so a single trial with 8 targets would result in 8 separate pages of experiment data. +In this case for each target the timestamps begin at a negative value, +and reach zero when the target is displayed. + +json +---- + +Experiments can also be exported as a json text file. +This is a convenient format for sharing experimental setups, +as it can be easily read and modified in a text editor. +These files can also be opened in the VSTT GUI +(File -> Open, choose JSON as filetype). +The json file contains all the information required to define the experiment: + +* metadata +* display_options +* trial_list + +This format does not include any statistics or experimental results. diff --git a/misc/example-experiment.psydat b/misc/example-experiment.psydat new file mode 100644 index 00000000..a8c9e2e9 Binary files /dev/null and b/misc/example-experiment.psydat differ diff --git a/src/vstt/__init__.py b/src/vstt/__init__.py index 40ab6a86..32273a72 100644 --- a/src/vstt/__init__.py +++ b/src/vstt/__init__.py @@ -5,4 +5,4 @@ "__version__", ] -__version__ = "1.0.0" +__version__ = "1.1.0"