Metadata-Version: 2.1
Name: fipster
Version: 0.1.0
Summary: Fiber photometry analysis tools used by Fipster.
Author: Han de Jong
License: MIT
Project-URL: Homepage, https://github.com/handejong/Fipster
Project-URL: Repository, https://github.com/handejong/Fipster
Project-URL: Issues, https://github.com/handejong/Fipster/issues
Keywords: fiber photometry,neuroscience,analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev

# Fipster Python
Fipster Python is actively maintained and updated. There is no GUI, but you can use matplotlib controls (both task bar as well as code) to control figure behavior. `Fipster_python` is completely Matplotlib and Pandas based and can be conveniently incorporated into an analysis pipeline, for instance into a Jupyter Notebook.

## Installation
Install Fipster into the Python environment you want to use:

```bash
python -m pip install -e /path/to/Fipster/Fipster_python
```

If you are already in the `Fipster_python` directory, you can instead run:

```bash
python -m pip install -e .
```

The `-e` flag performs an editable install, which is convenient during development because changes to the package are picked up without reinstalling it.

After installation:

- Import the package anywhere with `import fipster`
- Legacy code can still use `import Fipster as fip`
- Launch the command-line viewer with `fipster path/to/recording.mat`

The basic structure of the code is as follows. There are two main classes, `FIP_signal` and `Sweepset`.

## FIP_signal
Contains the main dataset. From a Python script or Jupyter Notebook, import the package and load a dataset like so:

```python
import fipster

# To load the data
signal = fipster.FIP_signal(filename="your/filename/here.mat")
```

For backwards compatibility, the legacy import continues to work:

```python
import Fipster as fip

# To load the data
signal = fip.FIP_signal(filename='your/filename/here.mat')
```

You can also run Fipster Python directly from the command line. This will present the complete dataset in a figure and make the dataset available in your workspace as an object named `signal`.

```bash
fipster ../raw_data/example_1.mat
```

(This will load the example data, change this to load you own data)

If you run Fipster from the command line, have a look at the end of the code under `__name__ == '__main__'` and include your own `main` function with formatting and/or normalization rules.

## Development
The package now uses a standard `src/` layout:

```text
Fipster_python/
  pyproject.toml
  Fipster.py
  src/fipster/
  tests/
```

- `src/fipster/core.py` contains the main implementation
- `src/fipster/cli.py` contains the console entry point
- `Fipster.py` is a thin compatibility shim for older codebases
- `tests/` contains pytest-based regression tests

### Overview of the available methods and important properties
Note: the examples below suppose you loaded your dataset in an object named "signal" as demonstrated above. To get a complete overview of all methods and their docstrings type "dir(signal)". To read the docstring of a particular method use the 'help' function like so:

```python
dir(signal) # Will print a list of properties and methods
help(signal) # Will print available docstrings of methods
help(signal.plot) # Will print docstring of the 'plot' method
help(signal.derive_timestamps) # Will print docstring of the "derive_timestamps" method
# etc..
```
### Properties:
- signal.settings: a dict with the settings the most important one of which is called "fit ref" which can be set to
    - "polyfit": (DEFAULT) will fit the 405nm and 470nm trace using a polynomal fit
    - "means": will fit the signal means
    - "rolling polyfit": will fit using a polynomal fit executed on a rolling window
    - "no fit": will not fit the 405nm and 470nm traces
- signal.timestamps: a dict where derived or imported timestamps are stored
    - Include new stamps simply so: signal.timestamps['my_new_stamps'] = np.array([list of times in 's'])
- signal.facecolor, .axcolor & .colormap
    - formatting options for your plots. Will include more in the future.

### Methods:
- signal.plot: will plot the signal
    - Use the "raw_data" and "timestamps" parameters to indicate what data you want to see plotted
- signal.derive_timestamps: derive timestamps from all or one particular analog input channel
- signal.peri_event: will output a peri-event (sweepset) object, see below.
- signal.sync_time: used to align the timeline of the 'signal' object with some external dataset.
- signal.quick_peri: essentially a wrapper for "derive_timestamps" and "peri_event" to quickly make a PEH of your FIP data
- signal.import_signal: to include an additional signal in the object
    - For instance: I've used this to include the temporal derivative of a FIP signal into the dataset.
    - Active development: not very robust.
- signal.get_data: get your fitted and/or normalized data for use in the rest of your code.
- signal.get_ref: get your fitted reference trace.


### What FIP_signal.plot() looks like:
This is with facecolor = 'k' and axcolor='w'

<img src="https://raw.githubusercontent.com/handejong/Fipster/master/Images/fipster_python_example.jpeg" alt="Example of FIP_signal.plot" width="800px" />

## Sweepset
This is the standard peri-event dataset class. It is usually created by using the 'peri_event' or 'quick_peri' methods of the FIP_signal class. Again: use 'dir' and 'help' to read docstrings of the included methods.

These examples suppose you named our sweepset object PE:

### Properties:
- PE.settings: dict with baseline and normalization settings
- PE.selector: list of bools about which trials (sweeps) to include in your analysis (used to exclude individual trials)
- PE.facecolor & .axcolor: formatting rules

### Methods
- PE.get_data: get normalized peri-event data:
    - Note: this uses PE.settings to normalize based on a baseline window.
- PE.make_Figure: Plot all channels
- PE.get_average: to get the response averaged over the trials.
    - Note that if you have enough trials, it is almost always better to use auROC instead of the average (Z-score or dF) response to combine/compare multiple animals/recordings.
- PE.auroc: To get the auROC-normalized response:
    - For trial-based assays, this has many advantaged over Z-score normalization (if you have enough trials!): The idea is from [Cohen et al. Nature 2012](https://www.nature.com/articles/nature10754). Specifically, it is in figure S1 of that paper.

### What sweepset.make_figure() looks like:

<img src="https://raw.githubusercontent.com/handejong/Fipster/master/Images/sweepset_example.jpeg" alt="Example of sweepset.make_figure" width="800px" />

## Example code
Have a look at <b>FIP_example.py</b> for an overview of what an analysis could look like. 
