Purpose of Oocount:

OoCount is a high throughput open-source pipeline we have developed with the specific aim of using whole-mount immunofluorescence and 3D imaging techniques to label all oocytes in the mouse ovary. Using tools such as Napari,  DL4MicEverywhere, StarDist, and APOC, we assembled a machine learning-based workflow to automate oocyte counts and classification.

Our hope is that researchers in the field of ovarian biology utilize this tool as a more definitive and accurate methodology than traditional serial sectioning for evaluating ovarian homeostasis in an in toto context.

To get started the user will want to refer to “OoCount: A Machine-Learning Based Approach to Mouse Ovarian Follicle Counting and Classification”, Folts et al., 2024 which contains the protocol for clearing, staining and imaging mouse ovaries. Once the images have been obtained this pipeline can be used for oocyte segmentation and follicle classification.

What is included here:

We have included the StarDist models for segmenting oocytes from adult and perinatal mouse ovaries, as well as code for either resampling your data to get better segmentation of oocytes or to generate a histogram based APOC classification. Additionally, we have added example data for both the adult and perinatal mouse ovary to familiarize the user with the output from each step of the pipeline. 

File Structure:

1. OocountDeliverables
   1. Code
      1. Napari_OoCountResult.py
         • (Code for APOC classification results and turning it into a histogram.)
      2. Resample_tiffs.py
         • (Code for resampling your images to better match our settings, down sampling may make it easier for StarDist to segment oocytes)
   2. Example Data
      • (Contains example data for the adult and perinatal mouse ovary. “DDX4” & “NR5A2” are Z-stack immunofluorescent images of the ovary whole perinatal or adult ovary; “StarDist labels” are the oocytes which have labeled using their respective StarDist model; “APOC” files are classified oocytes based on StarDist segmentation and sparse user annotation, and the “Results” file is a histogram summarizing results from APOC classification)
        1. Adult
           1. Adult-APOCOoCount_Prediction-CORR.tif
           2. Adult-APOCOoCount_Prediction.tif
           3. Adult-DDX4.tif
           4. Adult-NR5A2.tif
           5. Adult-Results.png
           6. Adult-StarDistOoCount_LABELS-Corr.tif
           7. Adult-StarDistOoCount_LABELS.tif
        2. Perinatal
           1. P3-APOCPrediction.tif
           2. P3-DDX4
           3. P3-NR5A2.tif
           4. P3-Results.png
           5. P3-StardistOocountLabels.tif 
   3. Oocount-StarDist
      1. StarDist Models

      2. (Contains our StarDist models for classifying oocytes from either the adult or perinatal ovary. “weights”, “configuration” and DLRmic files are outputs from running StarDist. The training report provides a summarized report from model training. “Logs” contains a log for images, training, and validation. “Quality Control” contains model quality control files indicating the robustness of the model.)

         Stardist-Oocount_Adult-V1.2

         1.  ”config.json”
         2. StarDist_3D_ZeroCostDL4Mic.html
         3. StarDist_3D_ZeroCostDL4Mic.ipynb
         4. StarDist_3D_ZeroCostDL4Mic.zip
         5. Stardist-OoCount_Adult-V1.2_training_report.pdf
         6. thresholds.json
         7. weights_best.h5
         8. weights_last.h5
         9. Logs
         10. Quality Control

         OoCount_Perinatal-V1.4

         1. config.json
         2. logs
         3. Quality Control
         4. StardistOoCount_Perinatal-V1.4_training_report.pdf
         5. thresholds.json
         6. weights_best.h5
         7. weights_last.h5

How to get started: 

1. Download (https://www.anaconda.com/anaconda-navigator) and open Anaconda Navigator. Click on the ‘Environments’ tab located below the ‘Home’ tab. Create a new environment by clicking the ‘create’ button and name it OoCount, use python version 3.9.7. This should now be available in the environments tab. Click the play button on the OoCount environment, this should open a terminal.
2. Enter the following commands one-by-one into the terminal: 

• $ pip install tensorflow==2.12
• $ pip install matplotlib==3.8.2
• $ pip install tifffile==2023.9.26
• $ pip install tqdm==4.66.1
• $ pip install imageio==2.33.0
• $ pip install numba==0.58.1
• $ pip install scikit-image==0.22.0
• $ pip install napari==0.4.18
• $ pip install stardist-napari==2022.12.6
• $ pip install napari-accelerated-pixel-and-object-classification==0.14.1
• $ pip install devbio-napari==0.10.1

• If using a computer with CUDA-compatible GPU and you want to use GPU acceleration install CUDAtoolkit with:      
  • $ pip install cudatoolkit=10.2

1. Following installation, close and reopen the Oocount terminal. When the terminal opens type ‘napari’ and hit enter. The Napari window will open.
2. Open images by either dragging & dropping or by using File > open. Single channel tiffs or multichannel tiffs can be opened but the multi-channels will need to be split which can also be done by Napari.
3. Before continuing, download the OoCount deliverables located in the files section of this upload.

Segmenting mouse oocytes using StarDist-OoCount: 

1. For each experiment make a folder and name it with the relevant title. Then make two subfolders therein one labeled ‘images’ the other labeled ‘masks’.
   • ‘images’ will contain images you want to segment 
   • ‘masks’ will contain the labels layer; the output from running StarDist-Oocount.
2. Using the image with DDX4 labeled oocytes, click Plugins > Napari-StarDist. This should open on the right side of the Napari window. Change the following settings:
   • Perinatal Ovary Settings
     • Image Axis –> ZXY
     • Model Type –> Custom 2D/3D Model
     • Custom Model –> ‘your file name’
     • Number of tiles –> 1,6,6
   • Adult Ovary Settings 
     • Image Axis –> ZXY
     • Model Type –> 2D/3D Model
     • Custom Model –> ‘your file name’
     • Number of Tiles –> 1,10,10
   • Note: If StarDist crashes you will need to adjust the tile sizes try 2,12,12 to reduce the computational load.
   • Note: our scaling voxel size, z = 0.996um, y=0.603um, x=0.603um for perinatal and z=3um, y=0.241um, x=0.241um for the adult. For optimal segmentation your scaling should match as closely as possible to these values. The scaling settings should be scaled to fit this closer, see section 6.3 of Folts et al., 2024.
3. You are now ready to click ‘Run’
4. This should result in a labels layer, save this in the masks folder. If segmentation needs to be corrected these layers can be altered. See video 6 of Folts et al., 2024. 

Training Accelerated Pixel and Object Classifier (APOC) to Classify Oocytes:

1. Once all oocytes are segmented they can be classified based on their growth stage using APOC. APOC uses machine learning to train based on user input which can be iteratively refined to achieve high resolution separation between classes of oocytes. See this user guide for more information.
   1. For our workflow, DDX4 was used to segment all oocytes while NR5A2 was used to mark active follicles, but any distinguishing marker can be used in place of NR5A2. 
2. Open Napari using the steps outlined above and open both the NR5A2 channel (or other marker of interest) and the corresponding mask generated from StarDist (the file with all of the labeled oocytes). 
3. Open APOC in Napari by clicking Plugin > Napari-accelerated-pixel-and-object-classification > object classification. The APOC panel should appear to the right of the screen.
4. Create a new labels layer and name it ‘annotation’. This layer will hold all of your annotations for each user relevant class. Use the paintbrush tool with the layers set to 2D and assign each class to a number (i.e. number one green will be primary follicles with number two yellow being secondary follicles ect.)
   1. APOC works with sparse annotation so only label a few oocytes of each class. Make sure these are at different layers of the Z-stack and that they are at different locations in the ovary. Repeat this annotation for each user relevant class of oocyte.
   2. Note: change the ‘contour’ value to 1 or 2 to toggle contour view instead of fill, this allows one to see the underlying NR5A2 (or other differentiating marker) staining along with the segmented oocytes themselves.
5. Change the settings as follows: 
   1. Set tree depth to 5
   2. Set number of trees to 100
   3. Use: Mean intensity, pixel count, standard deviation intensity, shape, centroid position, touching neighbor count, and average distance to touching neighbors. 
      • Note: you may need to try out different combinations to get optimal results based on the markers you are using. 
6. Once all follicles of interest have been sparsely annotated, run APOC. Save the classifier where it will be accessible for future use.
7. Click ‘Train’.
8. Inspect classification for errors, this is where the iterative refinement comes in. If you see errors, correct only a few of them at different depths then retrain (Important: do NOT correct every erroneous annotation, a few will suffice to retrain APOC; this is the beauty of using this method. Correct by painting the correct stage using the same methodology as step 4.
9. When optimal classification is achieved save the final APOC prediction output layer. 
   1. Note: APOC will not classify with 100% accuracy.
10. Classifier files in APOC can be reliably used for all images in a single batch imaged on the same settings in the same experiment. APOC will however, need to be retrained for new batches of images.

Getting Total Counts 

1. Open the Napari terminal by clicking the button in the lower left hand corner which looks like: ‘>_”.
2. Copy the code from our github called: NapariOocountResutlts.py and paste it into the Napari terminal. 
   • A series of user inputs will be needed, simply follow the instructions. The user inputs need to identically match the file names used in Napari.
3. Click enter after each prompt and once more at the end to generate a histogram with each of the different classifications plotted alongside total follicle counts. The data is generated in a comma-separated format which can also be copied and pasted into a spreadsheet for alternate data display. 

Creating a Custom StarDist Model:

If our pipeline is not optimal for your research question of the markers available to you or if the imaging has resulted in incompatible resolutions compared with what we used you may want to make your own StarDist model. We recommend that you see Folts et a., 2024 sections 9.1.1 to 9.2.5 which details this process for the interested user. 

Final Remarks: 

We would like to encourage any users who have generated images and results utilizing this pipeline to share their results and/or images with us so we can improve the current model for future users. If you would like to do so, please email us your files at: TeamOvary@McKeylab.com. 

Oocount Files

A zipped file containing all of the OoCount Deliverables is included in the files section of this upload, but here are also some links to the data as well. Similar links are located on our lab website: McKeyLab.com.

OoCount - StarDist Models:

Here are the two models we generated to segment oocytes in the adult and perinatal mouse ovary. StarDist segmentation was performed utilizing DDX4 as marker of all germ cells in the mouse ovary.

• For perinatal mouse ovaries: StardistOoCount_Perinatal-V1.4
• For adult mouse ovaries: Stardist - Oocount_Adult-V1.2 

Example Data:

This example data can be used in conjunction with the methods paper linked above to familiarize the user with the image analysis pipeline. If you proceed with first looking at the example data, choose either the fetal or the perinatal datasets and use the methods paper to go through the segmentation and the classification process. This should serve as a good foundation for the analysis of your own data.

The code below can be entered into the terminal in the Napari window in order to either generate a resampled data set which may aid in program segmentation (resampling_Code.py) or can be used to generate a histogram with the classifications as an output (Napari_OoCountResult.py). 

• Perinatal Ovary (Postnatal Day 3)
  • P3-DDX4-Image.tif
  • P3-NR5A2-Image.tif 
  • P3-StarDistOocountLabels.tif
  • P3-APOC Classes
  • Results
• Adult Ovary (3 Months)
  • Adult-DDX4Image.tif
  • Adult-NR5A2 Image.tif
  • Adult-StarDistOoCountLabels.tif
  • Adult-APOC-Oocount_Prediction.tif 
  • Adult-Results.png
• Code 
  • Resampling Code.py
  • Napari_OoCountResult.py