Skip to content

Commit

Permalink
update doc
Browse files Browse the repository at this point in the history
  • Loading branch information
GuillaumeLeGoc committed Jan 10, 2025
1 parent a40cab4 commit ac1e3f7
Show file tree
Hide file tree
Showing 9 changed files with 168 additions and 21 deletions.
2 changes: 1 addition & 1 deletion docs/demo_notebooks/cells_distributions.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"\n",
"You should copy this notebook, the configuration file and the atlas-related configuration files (blacklist and fusion) elsewhere and edit them according to your need.\n",
"\n",
"The data was generated from QuPath with stardist cell detection on toy data."
"The data was generated from QuPath with stardist cell detection followed by a pixel classifier \"Classify\" function on toy data."
]
},
{
Expand Down
2 changes: 1 addition & 1 deletion docs/demo_notebooks/density_map.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"source": [
"Draw 2D heatmaps as density isolines.\n",
"\n",
"This notebook does not actually use `histoquant` and relies only on [brainglobe-heatmap](https://brainglobe.info/documentation/brainglobe-heatmap/index.html) to extract brain structures outlines.\n",
"This notebook does not actually use `cuisto` and relies only on [brainglobe-heatmap](https://brainglobe.info/documentation/brainglobe-heatmap/index.html) to extract brain structures outlines.\n",
"\n",
"Only the detections measurements with atlas coordinates exported from QuPath are used.\n",
"\n",
Expand Down
2 changes: 1 addition & 1 deletion docs/demo_notebooks/fibers_coverage.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"The \"area µm^2\" measurement for each annotations can be created in QuPath with a pixel classifier, using the Measure button.\n",
"\n",
"We're going to consider that the \"area µm^2\" measurement generated by the pixel classifier is an object count. \n",
"`histoquant` computes a density, which is the count in each region divided by its aera. \n",
"`cuisto` computes a density, which is the count in each region divided by its aera. \n",
"Therefore, in this case, it will be actually the fraction of area covered by fibers in a given color.\n",
"\n",
"The data was generated using QuPath with a pixel classifier on toy data."
Expand Down
2 changes: 1 addition & 1 deletion docs/demo_notebooks/fibers_length_multi.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"metadata": {},
"source": [
"# Fibers length in multi animals\n",
"This example uses synthetic data to showcase how `histoquant` can be used in a [pipeline](../guide-pipeline.html).\n",
"This example uses synthetic data to showcase how `cuisto` can be used in a [pipeline](../guide-pipeline.html).\n",
"\n",
"Annotations measurements should be exported from QuPath, following the required [directory structure](../guide-pipeline.html#directory-structure).\n",
"\n",
Expand Down
12 changes: 12 additions & 0 deletions docs/guide-pipeline.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# Pipeline
While you can use QuPath and `cuisto` functionalities as you see fit, there exists a pipeline version of those. It requires a specific structure to store files (so that the different scripts know where to look for data). It also requires that you have detections stored as [geojson](tips-formats.md#json-and-geojson-files) files, which can be achieved using a pixel classifier and further segmentation (see [here](guide-qupath-objects.md#probability-map-segmentation)) for example.

In the event you can't or don't want to follow the pipeline depicted below, but still want to be able to batch-process animals, check the [last section](#batch-process-animals).

## Purpose
This is especially useful to perform quantification for several animals at once, where you'll only need to specify the root directory and the animals identifiers that should be pooled together, instead of having to manually specify each detections and annotations files.

Expand Down Expand Up @@ -104,3 +106,13 @@ cuisto.display.plot_2D_distributions(df_coordinates, cfg)

!!! tip
You can see a live example in [this demo notebook](demo_notebooks/fibers_length_multi.ipynb).

## Batch-process animals
It is still possible to process several subjects at once without using the directory structure specified [above](#directory-structure). The `cuisto.process.process_animals()` (plural) method is merely a wrapper around `cuisto.process.process_animal()` (singular). The former fetch the data from the expected locations, the latter is where the analysis actually happens. Therefore, it is possible to fetch your data yourself and feed it to `process_animal()`.

For example, say you used the QuPath `Measure > Export measurements` for each of your animals. For each individual, this builds a single file with all your images. Let's collect those individual files in a single directory called "results", and name the files in a consistent manner that allows you to identify "Annotations" and "Detections", as well as the animal identifier, for instance "animal0_annotations.tsv".

!!! important
The [configuration file](main-configuration-files.md#configtoml) is mandatory, even for single-animal analysis.

The script `batch_process_animals.py` located in `examples` will mimick `process_animals()` functionnality.
45 changes: 32 additions & 13 deletions docs/guide-prepare-qupath.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,47 @@
# Prepare QuPath data

## QuPath basics
`cuisto` uses some QuPath classifications concepts, make sure to be familiar with them with the [official documentation](https://qupath.readthedocs.io/en/stable/docs/concepts/classifications.html#classifications-derived-classifications). Notably, we use the concept of primary classification and derived classification : an object classified as `First: second` is of classification `First` and of derived classification `second`.

## QuPath requirements
`cuisto` assumes a specific way of storing regions and objects information in the TSV files exported from QuPath. Note that only one primary classification is supported, but you can have any number of derived classifications.
In a nutshell, QuPath has two main objects type, Annotations and Detections. The former are flexible, editable and can be easily moved around but are memory-intensive so they are not made to handle thousands of them. They are used to define regions of interest such as brain regions - ABBA imports registered brain regions as Annotations. On the other hand, Detections objects are optimized so that a single image can contain thousands of them without any problem, at the expense of being harder to modify (they can't be moved nor removed from the GUI). Those are used for objects of interest (the things you want to count, cells, fibers...).

### Detections
Detections are the objects of interest. Their information must respect the following :
Both types have an *Object ID* (an unique identifier), a *Name*, a *Classification* and a *Parent*. Those are strings, eg. letters and words. Then comes any number of numeric measurements that can have arbitrary names (that could be the area, length, count...).

+ Atlas coordinates should be in millimetres (mm) and stored as `Atlas_X`, `Atlas_Y`, `Atlas_Z`. They correspond, respectively, to the anterio-posterior (rostro-caudal) axis, the inferio-superior (dorso-ventral) axis and the left-right (medio-lateral) axis.
+ They must have a derived classification, in the form `Primary: second`. Primary would be an object type (cells, fibers, ...), the second one would be a biological marker or a detection channel (fluorescence channel name), for instance : `Cells: some marker`, or `Fibers: EGFP`.
+ The classification must match exactly the corresponding measurement in the annotations (see below).
!!! info
QuPath Annotations include dynamic measurements, eg. measurement that are updated live, such as "Num Detections" and so on. Those can be handy but are not used downstream with `cuisto` - you will need to add your own count with specific measurement names so that it can work with `cuisto`, see [below](#adding-measurements).

## QuPath requirements
`cuisto` assumes a specific way of storing regions and objects information in the TSV files exported from QuPath. Note that only one primary classification is supported, but you can have any number of derived classifications.

### Annotations
Annotations correspond to the atlas regions. Their information must respect the following :
Annotations correspond to the regions of interest, typically the brain regions. They are used to count objects of interest (Detections) within each of them in QuPath, then with `cuisto` to compute and display the measurement (or a derived metric such as the density) per region.
They usually are created importing the registration with the ABBA plugin from the QuPath "Extension" menu or with the `importAbba.groovy` script located in `scripts/qupath-utils/atlas`, but can also be drawn manually, imported from ImageJ ROIs (see the `importImageJRois.groovy` script in `scripts/qupath-utils/tools`) or any other methods, as long as the following requirements are met (note that the *Name* and *Classification* are already correctly set when using the ABBA plugin) :

+ The *Name* should be the atlas acronym, unless you are not using any atlas. In any case, regions are pooled across images and animals based on their *Name* (eg. all Annotations, from all images and all subjects, with the same *Name* are pooled together).
+ The *Classification* must be in the form `Hemisphere: Name`, where `Hemisphere` must be either "Left" or "Right". Even in the case where "Left" and "Right" do not make sense for you, "Left" and "Right" are used internally by `cuisto` to be able to distinguish the two hemispheres. Note that those can be renamed in the display parameters of the [configuration file](main-configuration-files.md#configtoml). `Name` must correspond to the actual Annotation *Name*.
!!! tip
There are some Groovy scripts in `scripts/qupath-utils/tools` showing how to manipulate Annotations' *Name* and *Classification* to make them suitable for `cuisto` when using custom Annotations (eg. not from ABBA).

+ They should be imported with the ABBA extension as acronyms and splitting left/right. Therefore, the annotation name should be the region acronym and its classification should be formatted as `Hemisphere: acronym` (for ex. `Left: PAG`).
+ Measurements names should be formatted as :
`Primary classification: derived classification measurement name`.
`object type: marker measurement name`. `measurement name` is the bit you will report in the [configuration file](main-configuration-files.md#configtoml) as `base_measurement` under the `[regions]` section.
For instance :
+ if one has *cells* with *some marker* and *count* them in each atlas regions, the measurement name would be :
`Cells: some marker Count`.
+ if one segments *fibers* revealed in the *EGFP* channel and measures the cumulated *length* in µm in each atlas regions, the measurement name would be :
`Fibers: EGFP Length µm`.
+ Any number of markers or channels are supported.
`Fibers: EGFP Length µm`.
Any number of markers or channels is supported but only one `object type`.

### Detections
Detections are the objects of interest. They are used in QuPath to count them in each regions, and can be used with `cuisto` to compute and display the spatial distrubutions based on the atlas coordinates.

The measurement you're interested in (count, cumulated fiber length...) will be added to the Annotations objects (brain regions). In order to get the measurement properly formatted (eg. with the correct measurement name so that it is compatible with `cuisto`, see [above](#annotations)), Detections objects need to respect the following :

+ The *Classification* must be a derived classification formatted like so : `object type: marker`. It can't have column other than the one separating the primary classification (`object type`) and the secondary classification (`marker`). `object type` corresponds to the type of objects of interested that are counted (eg. "Cells", "Fibers", ...), `marker` corresponds to a biological marker or a detection channel (eg. "EGFP", "positive", "marker1+", ...).
+ Only one primary classification can be analyzed at once with `cuisto`, eg. only objects classified as `object type: ...` will be taken into account. Examples : `Cells: marker 1` and `Cells: marker 2`, or `Fibers: EGFP` and `Fibers: DsRed`.

Those information are used to perform the quantification in each Annotation within QuPath. `cuisto` can use only the Annotations data afterwards if you're only interested in the quantification in each regions. However, if you also want the spatial distributions of the objects in the atlas space, Detections objects will also need :

+ The atlas coordinates, stored as `Atlas_X`, `Atlas_Y` and `Atlas_Z`, expressed in millimetres (mm). They correspond for the Allen Brain atlas, respectively, to the anterio-posterior (rostro-caudal) axis, the inferio-superior (dorso-ventral) axis and the left-right (medio-lateral) axis. You can add those coordinates to the Detections as a measurement with the `addAtlasCoordinates.groovy` script located in `scripts/qupath-utils/atlas`.

## Measurements

Expand Down Expand Up @@ -53,7 +71,7 @@ The groovy script under `scripts/qupath-utils/measurements/addRegionsLength.groo
#### Custom measurements
Keeping in mind [`cuisto` limitations](#metrics-supported-by-cuisto), you can add any measurements you'd like.

For example, you can run a [pixel classifier](https://qupath.readthedocs.io/en/stable/docs/tutorials/pixel_classification.html) in all annotations (eg. atlas regions). Using the `Measure` button, it will add a measurement of [the area covered by classified pixels](https://qupath.readthedocs.io/en/stable/docs/tutorials/measuring_areas.html#generating-results). Then, you can use the script located under `scripts/qupath-utils/measurements/renameMeasurements.groovy` to rename the generated measurements with a [properly-formatted name](#annotations). Finally, you can [export](#qupath-export) regions measurements.
For example, you can run a [pixel classifier](https://qupath.readthedocs.io/en/stable/docs/tutorials/pixel_classification.html) in all annotations (eg. atlas regions). Using the `Measure` button, it will add a measurement of [the area covered by classified pixels](https://qupath.readthedocs.io/en/stable/docs/tutorials/measuring_areas.html#generating-results) (see [here](guide-qupath-objects.md#measure)). Then, you can use the script located under `scripts/qupath-utils/measurements/renameMeasurements.groovy` to rename the generated measurements with a [properly-formatted name](#annotations). Finally, you can [export](#qupath-export) regions measurements.

Since `cuisto` will compute a "density", eg. the measurement divided by the region area, in this case, it will correspond to the fraction of surface occupied by classified pixels. This is showcased in the [Examples](demo_notebooks/fibers_coverage.ipynb).

Expand All @@ -68,3 +86,4 @@ Once you imported atlas regions registered with ABBA, detected objects in your i

Do this for both Detections and Annotations, you can then use those files with `cuisto` (see the [Examples](main-using-notebooks.md)).

Alternatively, if using QuPath as intended for the [pipeline](guide-pipeline.md), the final script `pipelineImportExport.groovy` will automatically export the data, following the [file structure](guide-pipeline.md#directory-structure) expected by `cuisto` used in "pipeline mode", eg. to easily analyse several animals at once (to do so without using the pipeline, check [this section](guide-pipeline.md#batch-process-animals)).
Loading

0 comments on commit ac1e3f7

Please sign in to comment.