Python wrapper for the R fastFMM package
The Python package fast-fmm-rpy2 is a wrapper of the fastFMM R Package. It provides the functions required to reproduce the analyses from the manuscript: A Statistical Framework for Analysis of Trial-Level Temporal Dynamics in Fiber Photometry Experiments.
This package has other software dependencies. The following must already be installed:
- The R Project for Statistical Computing (R)
fastFMMR Package
- See the official R documentation and Photometry FLMM tutorial for more information on installing R and system requirements for your system.
Warning
Depending on your system and local environment you may encounter a compatibility issue between the latest version of R (4.5.0) and the latest version of rpy2 (version 3.5.17) on Ubuntu. See rpy2 issue for more info. The issue has been fixed on the master branch of rpy2 but has not shipped with a published release yet.
Download the fastFMM by running the following command within
install.packages("fastFMM", dependencies = TRUE)
For more information see the fastFMM R package repo.
Assuming all the prerequisites in Dependencies are installed, fast-fmm-rpy2 can be installed using pip.
pip install fast-fmm-rpy2As the name implies fast-fmm-rpy2 uses the Python package rpy2 to wrap the R package. Refer to rpy2 documentation for troubleshooting or any issues loading shared C libraries.
# fast_fmm_rpy2/fmm_run.py
def fui(
csv_filepath: Path | None,
formula: str,
parallel: bool = True,
import_rules=local_rules,
r_var_name: str | None = "py_dat",
):
"""
Run the fastFMM model using the specified formula and data.
Parameters
----------
csv_filepath : Path or None
The file path to the CSV file containing the data.
If None, `r_var_name` must be provided.
formula : str
The formula to be used in the fastFMM model.
parallel : bool, optional
Whether to run the model in parallel. Default is True.
import_rules : object, optional
The import rules to be used for the local converter.
Default is `local_rules`.
r_var_name : str or None, optional
The R variable name to be used for the data. If `csv_filepath` is None,
this must be provided. Default is "py_dat".
Returns
-------
mod : object
The fitted fastFMM model.
Raises
------
AssertionError
If `csv_filepath` is None and `r_var_name` is not provided.
ValueError
If `csv_filepath` is not None and `r_var_name` is not provided.
"""# fast_fmm_rpy2/plot_fui
def plot_fui(
fuiobj,
num_row=None,
xlab="Functional Domain",
title_names=None,
ylim=None,
align_x=None,
x_rescale=1,
y_val_lim=1.1,
y_scal_orig=0.05,
return_data=False,
):
"""
Plot fixed effects from a functional univariate inference object.
Parameters:
-----------
fuiobj : dict
A dictionary containing the following keys:
- betaHat: numpy array of shape (num_vars, num_points) containing
coefficient estimates
- betaHat_var: numpy array of shape (num_points, num_points, num_vars)
containing variance estimates (optional)
- argvals: numpy array of domain points
- qn: numpy array of quantiles for joint confidence bands
(if variance is included)
num_row : int, optional
Number of rows for subplot grid
xlab : str, optional
Label for x-axis
title_names : list of str, optional
Names for each coefficient plot
ylim : tuple, optional
Y-axis limits (min, max)
align_x : float, optional
Point to align x-axis to (useful for time domain)
x_rescale : float, optional
Scale factor for x-axis
y_val_lim : float, optional
Factor to extend y-axis limits
y_scal_orig : float, optional
Factor to adjust bottom y-axis limit
return_data : bool, optional
Whether to return the plotting data
Returns:
--------
matplotlib.figure.Figure or tuple
If return_data=False, returns the figure
If return_data=True, returns (figure, list of dataframes)
"""See photometry_FLMM for tutorials on using fast-fmm-rpy2 to create Functional Mixed Models for Fiber Photometry.
The Python rpy2 implementation of fastFMM uses pandas to read in CSV files. The string of numbers in the CSV file is converted to floating point numbers using the 'roundtrip' converter, see read_csv docs. On different systems this converter may have subtle differences with the read.csv function in R. See the Python docs and R docs for more information on the issues and limitations with floating point numbers. There are many resources outlining these issues, for example the edited reprint of David Goldberg's paper What Every Computer Scientist Should Know About Floating-Point Arithmetic or The Anatomy of a Floating Point Number. Due to numerical precision limitations, arrays in R and Python are tested for near equality instead of exact equality. The tests in this package check if the floating point numbers parsed from the provided CSVs and computed models are equal within a tolerance level for Python and R.
Note
Depending on the system, there may be subtle differences in floating point numbers if you run fastFMM in R versus using fast-fmm-rpy2.
This software is developed under a CC0 1.0 Universal license. See the License file for more details.
If you use this package please reference the following papers, as well as our most recent Zenodo release:
- Cui et al. (2022) Implementation of the fast univariate inference approach
- Loewinger et al. (2024) A statistical framework for analysis of trial-level temporal dynamics in fiber photometry experiments.
The versioning of this package is managed by bump-my-version. Bumping the version using bump-my-version will update the project version in the pyproject.toml, create a commit and create a tag.
To bump the version
- Have or install a recent version of uv
- Setup virtual environment and install dependencies
uv sync --extra dev
- Bump version
uv run bump-my-version bump <major|minor|patch>
Show the possible versions resulting from the bump subcommand.
uv run bump-my-version show-bumpTest the bump command, don't write any files, just pretend.
uv run bump-my-version bump <major|minor|patch> --verbose --dry-run