Starting a new project v3 - RodentDataAnalytics/mwm-ml-gen GitHub Wiki

This section describes in depth how to start a new project and load your exported from Ethovision data.

Create a new project
Data format
Assign animal groups
Settings
Select animals
Properties and plotting

Create a new project

On the main menu press the button New Project and on the pop-up window specify a project name and the location in which your project will be created (the default path is the folder: My Documents > MWMGEN). Press OK to continue

new project

Data format

Trajectory Raw Data: This field requires a valid path in which the exported data from Ethovision are located. Each subfolder inside the specified folder will be assumed that contains a different experiment session. Each session needs to have at least one file (thus if the specified folder or any subfolders are empty then no session will be created for them). The picture below shows accepted input folder arrangements.

data input

Format Fields: These fields require information from the exported files of Ethovision. Each one of these files should contain a cell specifying the animal id and a sequence of cells specifying the location of the animal over Time in X, Y coordinates. These cells needs to be provide in the same way as it is shown in the picture and has to be unique. There is also the option of providing multiple values by separating them with comma, such as ID Field: rat,id. The picture below shows how to fill the format fields.

format input

After all the values have been entered press Load Data to import the data into the software. When the importing is complete the Sessions field will contain a number specifying how many sessions (subfolders) have been loaded and the table on the upper right side of the window will fill with values. For the moment the Group column should contain NaN values, the Exclude column should be deactivated and the Available column should be filled with zeros. The File Name column should contain the names of the loaded files and the next two columns should specify the sessions and the animal IDs. The Points column will contain the value 1 if trajectory information (Time, and X,Y coordinates) has been found inside the loaded filed. If any cell of the columns ID and Points contains NaN value then the animal ID and the Points have been failed to be parsed from the specific file.

table 1

Important note: the ID format cells need to be followed (horizontally) by a cell containing a numeric value. The Rec. Time, X and Y cells need to be followed (vertically) by numeric values any empty or non-numeric values (e.g. ' - ' will be excluded).

Assign animal groups

The button Assign Groups will become activated after the data have been successfully loaded. Upon pressing it a new window will pop-up which allows the separation of the animals into groups.

animal groups

The table on the left side contains all the Animal IDs of the specific session, to change the session use the buttons <= and => below the table. In the middle of the window the Assign button assigns (the selected from the Animal IDs list) animal ID(s) to a group specified by a number provided in the empty textfield. The groups need to be numeric with value larger than zero. The table on the right side of the screen will show in which group each animal ID has been assign to. Using the Save button animal groups can be exported to a CSV-file and the Load button can load one of these CSV-files (this CSV-file will be automatically created inside the setting folder of the project once this window is closed with name 'animal_groups.csv'). When everything is set the OK button will bring forth the previous screen. In case no animal groups needs to be created then OK button can be pressed immediately when this screen appears and then the program will automatically assign all the animals to one group.

When the previous screen appears the table's Group column will now contains the assigned groups.

table 2

Important note: In case some animals are not assigned to a group the program will ask to automatically assign them into a new group.

Settings

When the animal groups have been specified the two remaining fields, Days and Trials will become activated. The Days field needs to contain a number specifying for how many days the experiment was conducted while the Trials field needs to contain a sequence of comma-separated numbers specifying the trials conducted per day. For example the picture below shows that this experiment was conducted for 3 days and every day 4 trials were taking place.

When these two field are filled pressing the Refresh button will activate the Exclude column of the table as well as the Exclude group dropbox below the table.

Select animals

If the above steps has been followed the table should not contain any NaN values and the Exclude column should be activated. By ticking the checkbox inside a cell of the Exclude column this particular file will be excluded from this project. Each time the Refresh button or any checkbox is pressed the program checks for consistency between the Days and the Trials field with the number of non excluded animal IDs meaning that if for example we have a total of 12 trials over all the Days then each animal ID needs to exist 12 times per session inside the table. Any animal that is excluded or do not meet the criterion described before will be excluded and its Available (last column) value will be 0.

select animals

By using the Sort by options the table can be sorted by each of its columns ascending or descending order. Moreover if all the animals of a particular group needs to be excluded the Exclude group options give the ability to exclude a whole group or re-include all the groups by selecting the 'None' option.

Properties and plotting

In the properties panel the arena specifications needs to be defined along with the trial timeout.

Trial Timeout: Specifies the time that the animal has in order to find the platform. Must be provided in seconds.
Centre [X,Y]: Specifies the location of the center of the arena. This information should be defined during the calibration procedure with Ethovision. In case it is unknown then it can be obtained from the Ethovision 'background' arena picture although in that case the exact position needs to be provided.
Arena Radius: Specifies the radius of the arena. Must be provided in cm.
Platform [X,Y]: Specifies the location of the platform inside the arena. Given that the center of the arena is known from the calibration process, the platform location is easy to be calculated. This information can also be obtained from the Ethovision 'background' arena picture.

data input arena

Platform Radius: Specifies the radius of the platform. Must be provided in cm.
FlipX & FlipY In case the platform appears in the wrong position, ticking one of these two checkboxes or both will position the platform to the correct quadrant.

settings

After specifying the above properties the animal trajectories can be plotted by using the plotter options on the left side of the screen. In order to plot the trajectory number needs to be specified (according to the table's enumeration) and then the OK button be pressed. The buttons <= and => can be used to plot the previous and the next trajectory, while the buttons Arena, Trajectory and Both plot either only the arena or only the trajectory or both the arena and trajectory. Always the trajectory needs to be inside the arena and in case of errors the arena properties needs to be re-specified.