Metadata-Version: 2.1
Name: fiberphotopy
Version: 0.1.0
Summary: Package for analyzing fiber photometry data
Home-page: https://github.com/kpuhger/fiberphotopy
Author: Kyle P
License: UNKNOWN
Platform: UNKNOWN
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
Requires-Dist: pandas (>=1.4.2)
Requires-Dist: numpy (>=1.21.5)
Requires-Dist: statsmodels (>=0.13.2)
Requires-Dist: matplotlib (>=3.5.1)
Requires-Dist: seaborn (>=0.11)
Requires-Dist: pingouin (>=0.5.0)
Requires-Dist: pyyaml (>=5)
Requires-Dist: ruamel-yaml (>=0.15)

.. role:: raw-latex(raw)
   :format: latex

fiberphotopy
============

Code for analyzing fiber photometry data collected on the Doric Fiber
Photometery acquisition system.

Import the package as follows:

.. code:: python

   import fiberphotopy as fp

Installation
------------

The easiest way to install fiberphotopy is with ``pip``. Open your
terminal and enter the following:

.. code:: bash

   python -m pip install git+https://github.com/kpuhger/fiberphotopy.git 

Features
--------

Loading data
~~~~~~~~~~~~

Whole session data should be stored in a directory and can be loaded
like this:

.. code:: python

   fp.load_session_data(...)

-  Args can be used to modify the name of the signal and reference
   wavelengths as well as to specify the input channel on the
   photoreceiver and the output channel for the two excitation LEDs.
-  By default, this function calls ``trim_ttl_data`` which looks for a
   TTL pulse that indicates the start and end of a behavioral session.
   This is optional and be turned off by setting ``TTL_trim=False``.
-  By default, this function also downsamples the data to 10 Hz. This is
   controlled by the ``downsample=True`` argument and the associated
   ``freq`` argument.
-  By default, this function uses the standard method of motion
   correction for photometry data. It fits a linear model to the
   reference channel (e.g., 405nm) to predict the fluoresence in the
   signal channel (e.g., 465nm). Next, it calculates a dFF as: 
   ``100*(Y-Y_pred)/Y_pred``
-  By default, the ‘Animal’ column will be populated with the name of
   the associated data file. This column can be renamed by creating a
   dict of ``{'filename': 'subject_id'}`` mappings and passed into
   ``load_session_data`` with the ``subject_dict`` argument.

Visualizing session data
~~~~~~~~~~~~~~~~~~~~~~~~

The entire session can be visualized by running:

.. code:: python

   fp.plot_fp_session(...)

This generates a two-panel plot. The top panel plot the raw reference
and signal fluorescene values on the same plot, and the bottom panel
plots the dFF calculated from those reference and signal values.

Trial-level data
~~~~~~~~~~~~~~~~

These functions have only been tested on auditory fear conditioning
experiments (trace or delay FC). Please check the function documentation
for more information.

For trace fear condtioning (TFC) experiments, you can get trial-level
data by calling

.. code:: python

   fp.tfc_trials_df(...)

-  This function takes a DataFrame as input (e.g., from
   ``load_session_data``) and creates a trial-level DataFrame with a new
   column ‘Trial’ containing the trial number and ‘time_trial’
   containing a standardized time array for extracting identical events
   across trials.
-  By default, this function provides two methods of trial-normalized
   data:

   1. ``'dFF_znorm'``: z-score values computed across the entire trial
      period.
   2. ``'dFF_baseline_norm'``: baseline-normalized values. Computed as
      (x - mean(baseline))/std(baseline)

Visualizing trial data
~~~~~~~~~~~~~~~~~~~~~~

There are 3 main functions to visualize trial-level data:

.. code:: python

   fp.plot_trial_avg(...)

This will plot the trial-average for the specified yvar. Data is
averaged across trials for each subject, and these subject
trial-averages are used to calculate the trial-level error for plotting.

.. code:: python

   fp.plot_trial_indiv(...)

This will generate a figure with ``m x n`` subplots.
The shape of the figure is controlled with the ``subplot_params``
argument to indicate how many rows and columns to use for the figure.

.. code:: python

   fp.plot_trial_heatmap(...)

This will generate a heatmap of the data across trials. If the input
DataFrame contains multiple subjects it will calculate the average
values for each time bin before generating the heatmap.


