docs/nb/outlier_correction.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "dea46a42",
   "metadata": {},
   "source": [
    "# Outlier correction"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e99d247f",
   "metadata": {},
   "source": [
    "We import pose-estimation data, and perform outlier correction on that pose-estimation data using heuristic rules. The application of those rules are described here:\n",
    "https://github.com/sgoldenlab/simba/blob/master/misc/Outlier_settings.pdf"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "cb913766",
   "metadata": {},
   "outputs": [],
   "source": [
    "from simba.outlier_tools.outlier_corrector_movement import OutlierCorrecterMovement\n",
    "from simba.outlier_tools.outlier_corrector_location import OutlierCorrecterLocation\n",
    "from simba.utils.cli import set_outlier_correction_criteria_cli\n",
    "from simba.pose_importers.dlc_importer_csv import import_multiple_dlc_tracking_csv_file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "f7cc63fa",
   "metadata": {},
   "outputs": [],
   "source": [
    "# DEFINITIONS: HERE WE (i) DEFINE THE PATHS TO OUR DATA / SIMBA PROJECT, (ii) HOW WE SHOULD INTERPOLATE / SMOOTH OUR NEW\n",
    "# DATA, AND (III) THE ATTRIBUTES OF OUR NEW VIDEOS (FPS ETC.)\n",
    "\n",
    "## Define the path to our SimBA project config ini\n",
    "CONFIG_PATH = '/Users/simon/Desktop/envs/troubleshooting/notebook_example/project_folder/project_config.ini'\n",
    "\n",
    "## Define the path to the directory holding our new DLC CSV pose-estimation data\n",
    "DATA_DIR = '/Users/simon/Desktop/envs/troubleshooting/notebook_example/data'\n",
    "\n",
    "## Define if / how you want to interpolate missing pose-estimation data,\n",
    "## and if/how you want to smooth the new pose estimation data: here we do neither.\n",
    "INTERPOLATION_SETTING = 'None' # OPTIONS: 'None', Animal(s): Nearest', 'Animal(s): Linear', 'Animal(s): Quadratic','Body-parts: Nearest', 'Body-parts: Linear', 'Body-parts: Quadratic'\n",
    "SMOOTHING_SETTING = None # OPTIONS: 'Gaussian', 'Savitzky Golay'\n",
    "SMOOTHING_TIME = None # TIME IN MILLISECOND\n",
    "\n",
    "## Define the fps and the pixels per millimeter of the incoming data: has to be the same for all new videos.\n",
    "## if you have varying fps / px per millimeter / resolutions, then use gui (2023/05)\n",
    "FPS = 15\n",
    "PX_PER_MM = 4.6\n",
    "RESOLUTION = (600, 400) # WIDTH X HEIGHT\n",
    "\n",
    "#Define the body-parts and critera we want to use for outlier correction. NOTE: You can also set this manually in the project_config.ini or thrugh\n",
    "# the SimBA GUI.\n",
    "AGGREGATION_METHOD = 'mean'\n",
    "BODY_PARTS = {'Animal_1': {'Movement': ['Nose_1', 'Tail_base_1'],\n",
    "                           'Location': ['Nose_1', 'Tail_base_1']},\n",
    "              'Animal_2': {'Movement': ['Nose_2', 'Tail_base_2'],\n",
    "                           'Location': ['Nose_2', 'Tail_base_2']}}\n",
    "MOVEMENT_CRITERION = 0.7\n",
    "LOCATION_CRITERION = 2.0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "c3d8767e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Importing Aqu_FFJ_Cre_721 to SimBA project...\n",
      "Pose-estimation data for video Aqu_FFJ_Cre_721 imported to SimBA project (elapsed time: 0.1718s)...\n",
      "Importing Aqu_FFJ_Cre_723 to SimBA project...\n",
      "Pose-estimation data for video Aqu_FFJ_Cre_723 imported to SimBA project (elapsed time: 0.1681s)...\n",
      "Importing Aqu_FFJ_Cre_722 to SimBA project...\n",
      "Pose-estimation data for video Aqu_FFJ_Cre_722 imported to SimBA project (elapsed time: 0.1617s)...\n",
      "SIMBA COMPLETE: Imported 3 pose estimation file(s) (elapsed time: 0.5078s) \tcomplete\n"
     ]
    }
   ],
   "source": [
    "# WE RUN THE DATA IMPORTER FOR OUR DIRECTORY OF FILES\n",
    "## This imports your DLC files in the ``DATA_DIR`` according to the smoothing / interpolation settings defined above\n",
    "import_multiple_dlc_tracking_csv_file(config_path=CONFIG_PATH,\n",
    "                                        interpolation_setting=INTERPOLATION_SETTING,\n",
    "                                        smoothing_setting=SMOOTHING_SETTING,\n",
    "                                        smoothing_time=SMOOTHING_TIME,\n",
    "                                        data_dir=DATA_DIR)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "38306f7e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Processing video Aqu_FFJ_Cre_721. Video 1/3...\n",
      "Corrected movement outliers for file Aqu_FFJ_Cre_721 (elapsed time: 0.2929s)...\n",
      "Processing video Aqu_FFJ_Cre_723. Video 2/3...\n",
      "Corrected movement outliers for file Aqu_FFJ_Cre_723 (elapsed time: 0.2713s)...\n",
      "Processing video Aqu_FFJ_Cre_722. Video 3/3...\n",
      "Corrected movement outliers for file Aqu_FFJ_Cre_722 (elapsed time: 0.2674s)...\n",
      "SIMBA COMPLETE: Log for corrected \"movement outliers\" saved in project_folder/logs (elapsed time: 0.8572s) \tcomplete\n",
      "Processing video Aqu_FFJ_Cre_721. Video 1/3..\n",
      "Corrected location outliers for file Aqu_FFJ_Cre_721 (elapsed time: 49.6797s)...\n",
      "Processing video Aqu_FFJ_Cre_723. Video 2/3..\n",
      "Corrected location outliers for file Aqu_FFJ_Cre_723 (elapsed time: 24.645s)...\n",
      "Processing video Aqu_FFJ_Cre_722. Video 3/3..\n",
      "Corrected location outliers for file Aqu_FFJ_Cre_722 (elapsed time: 15.1142s)...\n",
      "SIMBA COMPLETE: Log for corrected \"location outliers\" saved in project_folder/logs (elapsed time: 89.4743s) \tcomplete\n"
     ]
    }
   ],
   "source": [
    "#We set the outlier criteria in the project_config.ini and run the outlier correction. NOTE: You can also set this manually in the project_config.ini or thrugh\n",
    "# the SimBA GUI. If this has already been done, there is **no need** to call `set_outlier_correction_criteria_cli`.\n",
    "set_outlier_correction_criteria_cli(config_path=CONFIG_PATH,\n",
    "                                    aggregation=AGGREGATION_METHOD,\n",
    "                                    body_parts=BODY_PARTS,\n",
    "                                    movement_criterion=MOVEMENT_CRITERION,\n",
    "                                    location_criterion=LOCATION_CRITERION)\n",
    "\n",
    "\n",
    "_ = OutlierCorrecterMovement(config_path=CONFIG_PATH).run()\n",
    "_ = OutlierCorrecterLocation(config_path=CONFIG_PATH).run()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "47975a2a",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:simba_dev] *",
   "language": "python",
   "name": "conda-env-simba_dev-py"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}