Planning: standardized dynamic foraging analysis

# Session-wise analysis
Here let's brainstorm what standardized analyses and plots we want to have for each behavioral session. They will be plugged into the pipeline and appear in the Streamlit app within 24 hrs after the session.

1. Basic analysis (***will go to Repo 2 below***)
- [ ] Extract basic session-wise task parameters ([Han's code](https://github.com/AllenNeuralDynamics/aind-foraging-behavior-bonsai-basic/blob/8dce33237ed362af4d35aa305f701cbf486ce14d/code/process_nwbs.py#L188-L231)) and performance stats ([Han's code](https://github.com/AllenNeuralDynamics/aind-foraging-behavior-bonsai-basic/blob/8dce33237ed362af4d35aa305f701cbf486ce14d/code/process_nwbs.py#L294-L341))
- [ ] Extract basic trial-wise behavioral stats ([Han's code](https://github.com/AllenNeuralDynamics/aind-foraging-behavior-bonsai-basic/blob/8dce33237ed362af4d35aa305f701cbf486ce14d/code/process_nwbs.py#L89-L118))
- [ ] Extract and plot instantaneous stats within sessions; also aggregate across sessions
- https://github.com/AllenNeuralDynamics/foraging-behavior-browser/issues/2
- [x] Plot choice and reward history ([Han's code](https://github.com/AllenNeuralDynamics/aind-foraging-behavior-bonsai-basic/blob/8dce33237ed362af4d35aa305f701cbf486ce14d/code/plot/foraging_matplotlib.py#L10)) 
- [x] Plot licks raster and histogram aligned to the GoCue and reaction time distribution splitted by side ([Han's code](https://github.com/hanhou/map-ephys/blob/de8e5e2c6c5aa9c2dc0df1a1b82b492554e21f9c/pipeline/plot/foraging_plot.py#L849))
- [x] Plot inter-lick-interval for sanity check https://github.com/AllenNeuralDynamics/aind-behavior-blog/issues/141, https://github.com/AllenNeuralDynamics/dynamic-foraging-analysis/issues/17
- [ ] Compute win-stay-lose-shift rates ([Han's code](https://github.com/hanhou/map-ephys/blob/de8e5e2c6c5aa9c2dc0df1a1b82b492554e21f9c/pipeline/model/descriptive_analysis.py#L24))

- [ ] Linear regression on reaction times ([Han's code](https://github.com/hanhou/map-ephys/blob/de8e5e2c6c5aa9c2dc0df1a1b82b492554e21f9c/pipeline/model/descriptive_analysis.py#L528))

2. Model fittings on animal choice (***will go to Repo 3 below***)
- [x] (Descriptive) Logistic regression ([Han's code](https://github.com/hanhou/map-ephys/blob/de8e5e2c6c5aa9c2dc0df1a1b82b492554e21f9c/pipeline/model/descriptive_analysis.py#L167))

- AllenNeuralDynamics/aind-dynamic-foraging-models#3
- [ ] (Generative) Maximum likelihood fitting of a series of RL models on choices, including model comparison ([Han's code](https://github.com/hanhou/map-ephys/blob/master/pipeline/model/bandit_model.py), [Han's notebook](https://github.com/hanhou/map-ephys/blob/master/notebook/han/Demo_foraging_behavior.ipynb)) 
- AllenNeuralDynamics/aind-dynamic-foraging-models#2
- [ ] (Generative) A volatile Kalman filter model ([CohenLab](https://github.com/JeremiahYCohenLab/cooperAnalysis/tree/cd508383c859a4ccae9c2a59c0f9620f429aeff7/matlabCode/operantMatching/learningModels/idealObserverModels))
- [ ] (Generative and hierachical) Stan model ([CohenLab](https://github.com/JeremiahYCohenLab/basicAnalysis/tree/main/behaviorAnalysis); _can we also fit them on individual sessions?_)
- [ ] (Descriptive with HMM) Faeze's GLM-HMM model (_not ready for standardization_)
- [ ] (Descriptive with nonstationarity) PsyTrack and Alex's paper

3. Video analysis
- [ ] Basic analysis such as motion energy etc. (***will go to Repo 4 below***)
- [ ] Supervised methods: DLC/LP ([this capsule](https://codeocean.allenneuraldynamics.org/capsule/3300060/tree)?)
- [ ] Unsupervised methods: auto-encoder such as BehavNet (Faeze; _not ready for standardization_)
- [ ] HMM analysis on extracted (latent) video trajectories (_not ready for standardization_)

# How should we organize the repos?
We should divide things across multiple repos. _Originally posted by @jsiegle in [#8](https://github.com/AllenNeuralDynamics/dynamic-foraging-analysis/issues/8#issuecomment-1979279616)_:
> My inclination to divide things across multiple repos also stems from my experience with the AllenSDK. If all analysis code lives in one package, it starts to develop idiosyncrasies that make it difficult for others to reuse/contribute to. The biggest problem with the AllenSDK was probably the fact that numerous pinned dependencies made it impossible to install in an existing environment, but a tangential problem was that its monolithic nature meant that very few people inside the Institute actually used it as a starting point for exploratory analysis. Obviously we are not trying to create something on the same scale, but I think it's important to plan for the type of code ecosystem we want to end up with before investing significant time building shared packages.

See section PROPOSED REPOSITORY STRUCTURE of [this doc](https://alleninstitute-my.sharepoint.com/:w:/g/personal/jeremiah_cohen_alleninstitute_org/ETjW2aUaDN9OvA2IwfMRgmEBl8c0kVAFUiWDJfhKETU11g?e=YWheNj&CID=ac9424d3-6551-b417-405e-8da9095daf48&clickparams=eyJBcHBOYW1lIjoiVGVhbXMtRGVza3RvcCIsIkFwcFZlcnNpb24iOiI1MC8yMzExMzAyODcyNCIsIkhhc0ZlZGVyYXRlZFVzZXIiOmZhbHNlfQ%3D%3D). And here is an excerpt from the part relevant to foraging behavior.

## Repo 1: [aind-dynamic-forgaing-data-utils](https://github.com/AllenNeuralDynamics/aind-dynamic-foraging-data-utils)

- Purpose: Ingests NWB and spits out dataframes with the relevant information. Focused on dynamic foraging. Other tasks can branch and build task-specific utils.
- Inputs are nwbs, outputs are dataframes (tidy and not)
- Dependencies: xarray (includes numpy and pandas), scikit-learn (includes scipy), matplotlib
- Example functions:
- nwb_to_dataframe()
- align_to_behavior()

## Repo 2: [aind-dynamic-foraging-basic-analysis](https://github.com/AllenNeuralDynamics/aind-dynamic-foraging-basic-analysis)

- Purpose: extract basic session-wise (e.g. foraging efficiency) and trial-wise statistics (e.g. reaction time); generate basic plots that will be put in the data visualization app. include functions that understand task structure; encourage code reuse across everyone working on the same project
- Inputs are dataframes, NOT nwbs
- Dependencies: aind-nwb-utils, aind-ephys-utils, aind-ophys-utils, aind-behavior-utils
- Other desired functions:
- plot_licks() - plot lick times relative to key events
- plot_reward/choice_history()
- regress_behavior()
- Other potential repositories: patch-foraging-analysis, dynamic-routing-analysis

## Repo 3: [aind-dynamic-foraging-models](https://github.com/AllenNeuralDynamics/aind-dynamic-foraging-models)

- Purpose: a place to put dynamic-foraging related descriptive models (e.g,. logistic regression), generative models (e.g., Q-learning and Bayesian inference model), and their associated model fitting modules. The generative model should have separately coded agents that can be readily plugged into any simulation. The fitting function should return all fitted parameters and metrics such as AIC and BIC.
- Dependencies:
- Example functions: [Logistic regression models (Han),](https://github.com/hanhou/map-ephys/blob/master/pipeline/model/descriptive_analysis.py) [RL models (Han),](https://github.com/hanhou/map-ephys/blob/master/pipeline/model/bandit_model.py) and a [CO capsule refactored by Stefano](https://codeocean.allenneuraldynamics.org/capsule/7317870/tree) (with pipeline too)

## Repo 4:[ aind-dynamic-foraging-video-analysis](https://github.com/AllenNeuralDynamics/aind-dynamic-foraging-behavior-video-analysis)

- added August 2025 by Rachel-- Matt Becker has code for video analysis of tongue data, so we created this repo to house them.

- Purpose:
- basic analysis of behavioral video (motion energy etc.)
- not sure if the DLC/LP stuff will be in this repo. Maybe not, since we already have them in CO pipeline.
- Dependencies:
- Example functions