docs/build/html/index.html
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Welcome to DeepOF! — deepof 0.6.2 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/jupyter-sphinx.css" type="text/css" />
<link rel="stylesheet" href="_static/thebelab.css" type="text/css" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<link rel="shortcut icon" href="_static/deepof.ico"/>
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<script src="_static/thebelab-helper.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@jupyter-widgets/html-manager@^1.0.1/dist/embed-amd.js"></script>
<script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="#">
<img src="_static/deepof_sidebar.ico" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<!-- Local TOC -->
<div class="local-toc"><ul>
<li><a class="reference internal" href="#">Welcome to DeepOF!</a></li>
<li><a class="reference internal" href="#getting-started">Getting started</a><ul>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#what-you-need">What you need</a></li>
<li><a class="reference internal" href="#basic-usage">Basic usage</a></li>
</ul>
</li>
<li><a class="reference internal" href="#tutorials">Tutorials</a><ul>
<li><a class="reference internal" href="#formatting-your-data">Formatting your data</a></li>
<li><a class="reference internal" href="#supervised-and-unsupervised-pipelines">Supervised and unsupervised pipelines</a></li>
<li><a class="reference internal" href="#advanced-usage">Advanced usage</a></li>
</ul>
</li>
<li><a class="reference internal" href="#cite-us">Cite us!</a></li>
<li><a class="reference internal" href="#contributing-and-support">Contributing and support</a></li>
<li><a class="reference internal" href="#api-reference">API Reference</a></li>
</ul>
</div>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="#">deepof</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="#" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Welcome to DeepOF!</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/index.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<style>
/* CSS overrides for sphinx_rtd_theme */
/* 24px margin */
.nbinput.nblast.container,
.nboutput.nblast.container {
margin-bottom: 19px; /* padding has already 5px */
}
/* ... except between code cells! */
.nblast.container + .nbinput.container {
margin-top: -19px;
}
.admonition > p:before {
margin-right: 4px; /* make room for the exclamation icon */
}
/* Fix math alignment, see https://github.com/rtfd/sphinx_rtd_theme/pull/686 */
.math {
text-align: unset;
}
</style>
<p><a class="reference external" href="https://gitlab.mpcdf.mpg.de/lucasmir/deepof/-/pipelines"><img alt="Pipeline" src="https://gitlab.mpcdf.mpg.de/lucasmir/deepof/badges/master/pipeline.svg" /></a> <a class="reference external" href="https://coverage.readthedocs.io/en/coverage-5.3/"><img alt="Coverage" src="https://gitlab.mpcdf.mpg.de/lucasmir/deepof/badges/master/coverage.svg" /></a> <a class="reference external" href="https://deepof.readthedocs.io/en/latest"><img alt="Documentation Status" src="https://readthedocs.org/projects/deepof/badge/?version=latest" /></a> <a class="reference external" href="https://www.codefactor.io/repository/github/lucasmiranda42/deepof"><img alt="CodeFactor" src="https://www.codefactor.io/repository/github/lucasmiranda42/deepof/badge" /></a> <a class="reference external" href="https://pypi.org/project/deepof/"><img alt="Version" src="https://img.shields.io/badge/release-v0.6.2-informational" /></a> <a class="reference external" href="https://mlfpm.eu/"><img alt="MLFPM" src="https://img.shields.io/badge/funding-MLFPM-informational" /></a> <a class="reference external" href="https://github.com/psf/black"><img alt="Black" src="https://img.shields.io/badge/code%20style-black-black" /></a> <a class="reference external" href="https://doi.org/10.21105/joss.05394"><img alt="JOSS" src="https://joss.theoj.org/papers/10.21105/joss.05394/status.svg" /></a></p>
<section id="welcome-to-deepof">
<h1>Welcome to DeepOF!<a class="headerlink" href="#welcome-to-deepof" title="Permalink to this heading"></a></h1>
<p>A suite for postprocessing time-series extracted from videos of freely moving rodents using <a class="reference external" href="http://www.mousemotorlab.org/deeplabcut">DeepLabCut</a> and <a class="reference external" href="https://sleap.ai/">SLEAP</a>.</p>
<a class="reference internal image-reference" href="https://gitlab.mpcdf.mpg.de/lucasmir/deepof/-/raw/master/logos/deepOF_logo_w_text.png"><img alt="DeepOF logo" class="align-center" src="https://gitlab.mpcdf.mpg.de/lucasmir/deepof/-/raw/master/logos/deepOF_logo_w_text.png" style="width: 400px;" /></a>
</section>
<section id="getting-started">
<h1>Getting started<a class="headerlink" href="#getting-started" title="Permalink to this heading"></a></h1>
<p>You can use this package to either extract pre-defined motifs from the time series (such as time-in-zone, climbing,
basic social interactions) or to embed your data into a sequence-aware latent space to extract meaningful motifs in an
unsupervised way! Both of these can be used within the package, for example, to automatically
compare user-defined experimental groups. The package is compatible with single and multi-animal DLC 2.X, and SLEAP projects.</p>
<a class="reference internal image-reference" href="_images/deepof_pipelines.png"><img alt="DeepOF label scheme" class="align-center" src="_images/deepof_pipelines.png" style="width: 400px;" /></a>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this heading"></a></h2>
<p>The easiest way to install DeepOF is to use <a class="reference external" href="https://pypi.org/project/deepof">pip</a>. Create and activate a virtual environment with Python >=3.9 and <3.11, for example using conda:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">conda</span> <span class="n">create</span> <span class="o">-</span><span class="n">n</span> <span class="n">deepof</span> <span class="n">python</span><span class="o">=</span><span class="mf">3.9</span>
</pre></div>
</div>
<p>Then, activate the environment and install DeepOF:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">conda</span> <span class="n">activate</span> <span class="n">deepof</span>
<span class="n">pip</span> <span class="n">install</span> <span class="n">deepof</span>
</pre></div>
</div>
<p>Alternatively, you can download our pre-built <a class="reference external" href="https://hub.docker.com/repository/docker/lucasmiranda42/deepof">Docker image</a>,
which contains all compatible dependencies:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># download the latest available image</span>
docker<span class="w"> </span>pull<span class="w"> </span>lucasmiranda42/deepof:latest
<span class="c1"># run the image in interactive mode, enabling you to open python and import deepof</span>
docker<span class="w"> </span>run<span class="w"> </span>-it<span class="w"> </span>lucasmiranda42/deepof
</pre></div>
</div>
<p>Or use <a class="reference external" href="https://python-poetry.org/">poetry</a>:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># after installing poetry and cloning the DeepOF repository, just run</span>
poetry<span class="w"> </span>install<span class="w"> </span><span class="c1"># from the main directory</span>
</pre></div>
</div>
<p><strong>NOTE</strong>: installation via pip is at the moment not compatible with Apple Silicon. If you’d like to install DeepOF on such machines,
please use either poetry or Docker. You should also install hdf5 using <a class="reference external" href="https://brew.sh/">homebrew</a>, as described in <a class="reference external" href="https://github.com/mlfpm/deepof/issues/15">this</a> issue.</p>
</section>
<section id="what-you-need">
<h2>What you need<a class="headerlink" href="#what-you-need" title="Permalink to this heading"></a></h2>
<p>DeepOF relies heavily on DeepLabCut and SLEAP output. Thorough tutorials on how to get started with pose estimation using DLC can be found <a class="reference external" href="https://www.mousemotorlab.org/deeplabcut">here</a>, and for SLEAP <a class="reference external" href="https://sleap.ai/tutorials/tutorial.html">here</a>.
Once your videos are processed and tagged, you can use DeepOF to extract and annotate your motion-tracking time-series. While many features in DeepOF can work regardless of the set of labels used, we currently recommend using videos from a top-down perspective, and follow our recommended
set of labels (which can be found in the full documentation page). Pre-trained models following this scheme, and capable of recognizing either <strong>C57Bl6</strong> mice alone, or <strong>C57Bl6</strong> and <strong>CD1</strong> mice can be downloaded from <a class="reference external" href="https://datashare.mpcdf.mpg.de/s/DKg0jd7YYqnyQv9">our repository</a>.</p>
<a class="reference internal image-reference" href="_images/deepof_DLC_tagging.png"><img alt="DeepOF label scheme" class="align-center" src="_images/deepof_DLC_tagging.png" style="width: 800px;" /></a>
</section>
<section id="basic-usage">
<h2>Basic usage<a class="headerlink" href="#basic-usage" title="Permalink to this heading"></a></h2>
<p>The main module with which you’ll interact is called <code class="docutils literal notranslate"><span class="pre">`deepof.data`</span></code>. Let’s import it and create a project:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">deepof.data</span>
<span class="n">my_deepof_project</span> <span class="o">=</span> <span class="n">deepof</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">Project</span><span class="p">(</span>
<span class="n">project_path</span><span class="o">=</span><span class="s2">"."</span><span class="p">,</span> <span class="c1"># Path where to create project files</span>
<span class="n">video_path</span><span class="o">=</span><span class="s2">"/path/to/videos"</span><span class="p">,</span> <span class="c1"># Path to DLC tracked videos</span>
<span class="n">table_path</span><span class="o">=</span><span class="s2">"/path/to/tables"</span><span class="p">,</span> <span class="c1"># Path to DLC output</span>
<span class="n">project_name</span><span class="o">=</span><span class="s2">"my_deepof_project"</span><span class="p">,</span> <span class="c1"># Name of the current project</span>
<span class="n">exp_conditions</span><span class="o">=</span><span class="p">{</span><span class="n">exp_ID</span><span class="p">:</span> <span class="n">exp_condition</span><span class="p">}</span> <span class="c1"># Dictionary containing one or more experimental conditions per provided video</span>
<span class="n">bodypart_graph</span><span class="o">=</span><span class="s2">"deepof_14"</span> <span class="c1"># Labelling scheme to use. See the last tutorial for details</span>
<span class="p">)</span>
</pre></div>
</div>
<p>This command will create a <code class="docutils literal notranslate"><span class="pre">`deepof.data.Project`</span></code> object storing all the necessary information to start. There are
many parameters that we can set here, but let’s stick to the basics for now.</p>
<p>One you have this, you can run you project using the <code class="docutils literal notranslate"><span class="pre">`.create()`</span></code> method, which will do quite a lot of computing under
the hood (load your data, smooth your trajectories, compute distances, angles, and areas between body parts, and save all
results to disk). The returned object belongs to the <code class="docutils literal notranslate"><span class="pre">`deepof.data.Coordinates`</span></code> class.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">my_project</span> <span class="o">=</span> <span class="n">my_project</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>Once you have this, you can do several things! But let’s first explore how the results of those computations mentioned
are stored. To extract trajectories, distances, angles and/or areas, you can respectively type:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">my_project_coords</span> <span class="o">=</span> <span class="n">my_project</span><span class="o">.</span><span class="n">get_coords</span><span class="p">(</span><span class="n">center</span><span class="o">=</span><span class="s2">"Center"</span><span class="p">,</span> <span class="n">polar</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">align</span><span class="o">=</span><span class="s2">"Nose"</span><span class="p">,</span> <span class="n">speed</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
<span class="n">my_project_dists</span> <span class="o">=</span> <span class="n">my_project</span><span class="o">.</span><span class="n">get_distances</span><span class="p">(</span><span class="n">speed</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
<span class="n">my_project_angles</span> <span class="o">=</span> <span class="n">my_project</span><span class="o">.</span><span class="n">get_angles</span><span class="p">(</span><span class="n">speed</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
<span class="n">my_project_areas</span> <span class="o">=</span> <span class="n">my_project</span><span class="o">.</span><span class="n">get_areas</span><span class="p">(</span><span class="n">speed</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
</pre></div>
</div>
<p>Here, the data are stored as <code class="docutils literal notranslate"><span class="pre">`deepof.data.table_dict`</span></code> instances. These are very similar to python dictionaries
with experiment IDs as keys and pandas.DataFrame objects as values, with a few extra methods for convenience. Peeping
into the parameters you see in the code block above, <code class="docutils literal notranslate"><span class="pre">`center`</span></code> centers your data (it can be either a boolean or
one of the body parts in your model! in which case the coordinate origin will be fixed to the position of that point);
<code class="docutils literal notranslate"><span class="pre">`polar`</span></code> makes the <code class="docutils literal notranslate"><span class="pre">`.get_coords()`</span></code> method return polar instead of Cartesian coordinates, and <code class="docutils literal notranslate"><span class="pre">`speed`</span></code>
indicates the derivation level to apply (0 is position-based, 1 speed, 2 acceleration, 3 jerk, etc). Regarding
<code class="docutils literal notranslate"><span class="pre">`align`</span></code> and <code class="docutils literal notranslate"><span class="pre">`align-inplace`</span></code>, they take care of aligning the animal position to the y Cartesian axis: if we
center the data to “Center” and set <code class="docutils literal notranslate"><span class="pre">`align="Nose",</span> <span class="pre">align_inplace=True`</span></code>, all frames in the video will be aligned in a
way that will keep the Center-Nose axis fixed. This is useful to constrain the set of movements that one can extract
with our unsupervised methods.</p>
<p>As mentioned above, the two main analyses that you can run are supervised and unsupervised. They are executed by
the <code class="docutils literal notranslate"><span class="pre">`.supervised_annotation()`</span></code> method, and the <code class="docutils literal notranslate"><span class="pre">`.deep_unsupervised_embedding()`</span></code> methods of the <code class="docutils literal notranslate"><span class="pre">`deepof.data.Coordinates`</span></code>
class, respectively.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">supervised_annot</span> <span class="o">=</span> <span class="n">my_project</span><span class="o">.</span><span class="n">supervised_annotation</span><span class="p">()</span>
<span class="n">gmvae_embedding</span> <span class="o">=</span> <span class="n">my_project</span><span class="o">.</span><span class="n">deep_unsupervised_embedding</span><span class="p">()</span>
</pre></div>
</div>
<p>The former returns a <code class="docutils literal notranslate"><span class="pre">`deepof.data.TableDict`</span></code> object, with a pandas.DataFrame per experiment containing a series of
annotations. The latter is a bit more complicated: it returns a series of objects that depend on the model selected (we
offer three flavours of deep clustering models), and allow for further analysis comparing cluster expression and dynamics.</p>
<p>That’s it for this (very basic) introduction. Check out the tutorials too see both pipelines in action, and the full API
reference for details!</p>
</section>
</section>
<section id="tutorials">
<h1>Tutorials<a class="headerlink" href="#tutorials" title="Permalink to this heading"></a></h1>
<section id="formatting-your-data">
<h2>Formatting your data<a class="headerlink" href="#formatting-your-data" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="tutorial_notebooks/deepof_preprocessing_tutorial.html"><span class="doc">Formatting your data: feature extraction from motion tracking output</span></a></p></li>
</ul>
</section>
<section id="supervised-and-unsupervised-pipelines">
<h2>Supervised and unsupervised pipelines<a class="headerlink" href="#supervised-and-unsupervised-pipelines" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="tutorial_notebooks/deepof_supervised_tutorial.html"><span class="doc">DeepOF supervised pipeline: detecting pre-defined behaviors</span></a></p></li>
<li><p><a class="reference internal" href="tutorial_notebooks/deepof_unsupervised_tutorial.html"><span class="doc">DeepOF unsupervised pipeline: exploring the behavioral space</span></a></p></li>
</ul>
</section>
<section id="advanced-usage">
<h2>Advanced usage<a class="headerlink" href="#advanced-usage" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p><a class="reference internal" href="tutorial_notebooks/deepof_custom_labels_tutorial.html"><span class="doc">Using custom labelling schemes</span></a></p></li>
</ul>
</section>
</section>
<section id="cite-us">
<h1>Cite us!<a class="headerlink" href="#cite-us" title="Permalink to this heading"></a></h1>
<p>If you use DeepOF in your research, please consider citing:</p>
<ol class="arabic simple">
<li><p><a class="reference external" href="https://joss.theoj.org/papers/10.21105/joss.05394">DeepOF: a Python package for supervised and unsupervised pattern recognition in mice motion tracking data (JOSS, 2023)</a></p></li>
<li><p><a class="reference external" href="https://www.nature.com/articles/s41467-023-40040-3">Automatically annotated motion tracking identifies a distinct social behavioral profile following chronic social defeat stress (Nature Communications, 2023)</a></p></li>
</ol>
</section>
<section id="contributing-and-support">
<h1>Contributing and support<a class="headerlink" href="#contributing-and-support" title="Permalink to this heading"></a></h1>
<p>If you’d like to contribute to DeepOF, please check out our <a class="reference external" href="https://github.com/mlfpm/deepof/blob/master/CONTRIBUTING.md">contributing guidelines</a>. If
you’d like to report a bug, suggest a new feature, or need help with general usage, please open an issue in our <a class="reference external" href="https://github.com/mlfpm/deepof/issues">issue tracker</a>.</p>
</section>
<section id="api-reference">
<h1>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this heading"></a></h1>
<ul class="simple">
<li><p><a class="reference external" href="_generated/deepof.data.html">deepof.data (main data-wrangling module)</a></p></li>
<li><p><a class="reference external" href="_generated/deepof.utils.html">deepof.utils (data-wrangling auxiliary functions)</a></p></li>
<li><p><a class="reference external" href="_generated/deepof.models.html">deepof.models (deep unsupervised models)</a></p></li>
<li><p><a class="reference external" href="_generated/deepof.hypermodels.html">deepof.hypermodels (deep unsupervised hypermodels for hyperparameter tuning)</a></p></li>
<li><p><a class="reference external" href="_generated/deepof.annotation_utils.html">deepof.annotation_utils (rule-based and supervised annotation auxiliary functions)</a></p></li>
<li><p><a class="reference external" href="_generated/deepof.model_utils.html">deepof.model_utils (deep machine learning models’ auxiliary functions)</a></p></li>
<li><p><a class="reference external" href="_generated/deepof.visuals.html">deepof.visuals (visualization functions)</a></p></li>
<li><p><a class="reference external" href="_generated/deepof.post_hoc.html">deepof.post_hoc (post-hoc analysis functions)</a></p></li>
</ul>
</section>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>© Copyright 2024, Lucas Miranda.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>