Skip to content

Commit

Permalink
JNB: Improve description of steps
Browse files Browse the repository at this point in the history
  • Loading branch information
@scottclowe
scottclowe committed Mar 25, 2022
1 parent 8c7a54c commit f845a6e
Show file tree
Hide file tree
Showing 2 changed files with 58 additions and 31 deletions.
30 changes: 19 additions & 11 deletions examples/Basic usage - Function.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Import packages"
"## Import packages\n",
"\n",
"First, we need to import fissa."
]
},
{
Expand All @@ -37,6 +39,13 @@
"import fissa"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We also import some plotting dependencies which we'll make use in this notebook to display the results."
]
},
{
"cell_type": "code",
"execution_count": null,
Expand Down Expand Up @@ -91,12 +100,11 @@
"If the ROIs were defined using ImageJ, use ImageJ's export function to save them in a zip.\n",
"Then, provide the ROI filename,\n",
"```python\n",
"rois = \"rois.zip\" # for a single set of rois across images\n",
"rois = [\"rois1.zip\", \"rois2.zip\", ...] # for a roiset for each image\n",
"rois = \"rois.zip\" # for a single set of ROIs used across all images\n",
"```\n",
"or list of ROI filenames\n",
"```python\n",
"rois = [\"rois1.zip\", \"rois2.zip\", ...] # for a roiset for each image\n",
"rois = [\"rois1.zip\", \"rois2.zip\", ...] # for a unique roiset for each image\n",
"```\n",
"Defining a different roiset per image can be useful if you need to adjust for motion drift, for example.\n",
"\n",
Expand Down Expand Up @@ -134,15 +142,15 @@
"\n",
"The output of `fissa.run_fissa()` is structured as a 2-d array of 2-d arrays (it can't be a 4-d array because of differing trial lengths).\n",
"\n",
"The results from the cell (roi) numbered `c` and the trial (TIFF) numbered `t` are located at `result[c, t][0, :]`.\n",
"The results from the cell (ROI) numbered `c` and the trial (TIFF) numbered `t` are located at `result[c, t][0, :]`.\n",
"\n",
"The fourth (last) dimension works through frames within the TIFF file.\n",
"The fourth and final dimension works through frames within the TIFF file (time).\n",
"\n",
"The third dimension contains all the decontaminated signals from the ROI and its surrounding neuropil.\n",
"The 0-th entry of this is the signal which most closely corresponds to the raw signal within the ROI.\n",
"The other signals are the (isolated) contaminants.\n",
"The third dimension iterates over output signals.\n",
"The 0-th entry of this is the signal which most closely corresponds to the raw signal within the ROI, and is FISSA's best guess for the decontaminated cell source signal.\n",
"The other signals are the isolated signals from contaminants such as neuropil and neighbouring cells.\n",
"\n",
"Let's compare the raw to separated trace for a single trial from an example roi."
"Let's compare the raw signal to the separated signal for a single trial from an example ROI."
]
},
{
Expand Down Expand Up @@ -611,7 +619,7 @@
"% S = load('fissa-example/separated.mat')\n",
"S = load('experiment_results.mat')\n",
"% Select the second trial\n",
"% On Python, this is equivalent to trial = 1\n",
"% (On Python, this would be trial = 1)\n",
"trial = 2;\n",
"% Plot the result traces for each ROI\n",
"figure; hold on;\n",
Expand Down
59 changes: 39 additions & 20 deletions examples/Basic usage.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Import packages"
"## Import packages\n",
"\n",
"Before we can begin, we need to import fissa."
]
},
{
Expand All @@ -37,6 +39,13 @@
"import fissa"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We also import some plotting dependencies which we'll make use in this notebook to display the results."
]
},
{
"cell_type": "code",
"execution_count": null,
Expand Down Expand Up @@ -66,35 +75,40 @@
"\n",
"To run a separation step with fissa, you need create a `fissa.Experiment` object, which will hold your extraction parameters and results.\n",
"\n",
"The inputs to the `fissa.Experiment` instance are:\n",
"The mandatory inputs to `fissa.run_fissa` are:\n",
"\n",
"- the experiment images\n",
"- the regions of interest (ROIs) to extract\n",
"\n",
"Define your inputs. All that's necessary to define are the image data and ROIs.\n",
"\n",
"\n",
"Images can be defined as a folder with tiff stacks:\n",
"Images can be given as a path to a folder containing tiff stacks:\n",
"```python\n",
"images = \"folder\"\n",
"```\n",
"Where each tiff stack in the folder is a trial with several frames.\n",
"Each of these tiff stacks in the folder (e.g. `\"folder/trial_001.tif\"`) is a trial with many frames.\n",
"\n",
"Or the data can also be given as a list of arrays if not stored as tiffs:\n",
"Alternatively, the image data can be given as a list of paths to tiffs:\n",
"```python\n",
"images = [\"folder/trial_001.tif\", \"folder/trial_002.tif\", \"folder/trial_003.tif\"]\n",
"```\n",
"or as a list of arrays which you have already loaded into memory:\n",
"```python\n",
"images = [array1, array2, array3, ...]\n",
"```\n",
"\n",
"For ROIs either a set of ROIs across all images should be defined, or a set of ROIs per image. \n",
"For the ROIs input, you can either provide a single set of ROIs, or a set of ROIs for every image.\n",
"\n",
"If the ROIs were defined using ImageJ use ImageJ's export function to save them in a zip. Then, indicate the locations as a list:\n",
"If the ROIs were defined using ImageJ, use ImageJ's export function to save them in a zip.\n",
"Then, provide the ROI filename,\n",
"```python\n",
"rois = \"rois.zip\" # for a single set of ROIs used across all images\n",
"```\n",
"or list of ROI filenames\n",
"```python\n",
"rois = \"rois.zip\" # for a single set of rois across images\n",
"rois = [\"rois1.zip\", \"rois2.zip\", ...] # for a roiset for each image\n",
"rois = [\"rois1.zip\", \"rois2.zip\", ...] # for a unique roiset for each image\n",
"```\n",
"Defining a different roiset per image can be useful if you need to adjust for motion drift for example.\n",
"Defining a different roiset per image can be useful if you need to adjust for motion drift, for example.\n",
"\n",
"Then, we can define our experiment:"
"Then, we can define our experiment as follows."
]
},
{
Expand Down Expand Up @@ -522,11 +536,7 @@
"### df/f<sub>0</sub>\n",
"\n",
"It is often useful to calculate the intensity of a signal relative to the baseline value, df/f<sub>0</sub>, for the traces.\n",
"This can be done as follows.\n",
"\n",
"Note that by default, f<sub>0</sub> is determined as the minimum across all trials (all tiffs) to ensure that results are directly comparable between trials, but you can normalise each trial individually instead if you prefer by setting `across_trials=False`.\n",
"\n",
"Since FISSA is very good at removing contamination from the ROI signals, the minimum value on the decontaminated trace will typically be `0.`. Consequently, we use the minimum value of the (smoothed) raw signal to provide the f<sub>0</sub> from the raw trace for both the raw and decontaminated df/f<sub>0</sub>."
"This can be done with FISSA as follows."
]
},
{
Expand All @@ -540,6 +550,15 @@
"experiment.calc_deltaf(freq=sample_frequency, across_trials=True)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that by default, f<sub>0</sub> is determined as the minimum across all trials (all tiffs) to ensure that results are directly comparable between trials, but you can normalise each trial individually instead if you prefer by setting `across_trials=False`.\n",
"\n",
"Since FISSA is very good at removing contamination from the ROI signals, the minimum value on the decontaminated trace will typically be `0.`. Consequently, we use the minimum value of the (smoothed) raw signal to provide the f<sub>0</sub> from the raw trace for both the raw and decontaminated df/f<sub>0</sub>."
]
},
{
"cell_type": "code",
"execution_count": null,
Expand Down Expand Up @@ -691,7 +710,7 @@
"% Load the FISSA output data\n",
"S = load('fissa-example/separated.mat')\n",
"% Select the third ROI, second trial\n",
"% On Python, this is equivalent to roi = 2; trial = 1;\n",
"% (On Python, this would be roi = 2; trial = 1;)\n",
"roi = 3; trial = 2;\n",
"% Plot the raw and result traces for the ROI signal\n",
"figure; hold on;\n",
Expand Down

0 comments on commit f845a6e

Please sign in to comment.