Read the Docs

An innovative, state-of-the-art deep learning model for automatically ageing menhaden samples using scale images and fish length, weight, and month of catch

This Menhaden Ageing Model provides an innovative method for automatically estimating Menhaden age using scale images and fish length, weight, and month of catch (hereafter, “metadata”.) Built upon state-of-the-art deep learning algorithms, it enables rapid generation of fish age predictions by simply pointing to a directory containing configuration file that instructs the model where to find the data and metadata, how to preprocess the images, and where to write the output.

About

The internal workflow is as follows:

  1. Raw images are first converted to grayscale such that every image pixel contains a value [0, 255]. These grayscale images are then processed using binary thresholding image processing techniques by which all pixels whose values are above a certain threshold are set to 1 while the rest are set to 0. This allows the fish scale itself to be distinguished from the image background. The threshold value used for menhaden, based on trail and error, is 100.
  2. Imperfections in the new masked images are cleaned up using morphological opening and closing techniques to remove undesired background noise and capture any missed portions of the scale.
  3. The contours of the masked shape are identified in order to extract the fish scale.
  4. The scale is then cropped out of the original image and padded to make it square.
  5. The new square image containing just the scale of interest is passed to a trained custom residual neural network (resnet) deep learning classification model along with (optionally) a metadata CSV file described later. Model output is saved to a CSV file.

Implementation instructions follow. Be sure to set up and configure a Python environment before the first use.

Usage

Predicting menhaden ages requires two steps. First, raw images must be pre-processed in order to crop out the scale of interest from the full image, pad the cropped image to ensure the full scale is captured, and (optionally) normalize the cropped image to facilitate ageing. These new processed images are then passed to an ageing model to generate age inferences. This is all done using the provided menhaden-age-model utility, a Windows Batch (.bat) file designed to streamline Python environment management and script execution. Upon launching menhaden-age-model, the user is asked to select a process from the following options:

  • Process raw images (crop, pad, normalize, etc.): Process raw scale images prior to passing them through an age prediction model. The image processing routine takes an image that may contain multiple scales, identifies and crops the center-most scale, resizes it to square dimensions expected by the model, adds necessary padding around the cropped scale, and optionally applies image pixel normalization or other image processing techniques.
  • Predict ages using images only: Runs the “image-only” ageing model, which predicts ages using only the cropped scale images.
  • Predict ages using images and metadata: Runs the so-called “multimodal” ageing model, which combines sample metadata (e.g., fish length, weight, month of catch) with processed scale images to predict age.

Regardless of which pipeline is selected, the user will then be prompted to select the desired configuration YAML file. See the docs for more information and details on each configuration option.

Command line options for using the Menhaden ageing model are also available. See the Using the Model for more information.

Dependencies

Python: This model is built using Python 3.8 but currently works with versions up to Python 3.10. The user is responsible for downloading, installing, and configuring Python on their system.

The following Python packages are also needed. These will automatically be installed in a virtual environment via the menhaden-age-model utility. Otherwise, they can be retreived manually via command line using the requirements.txt file (pip) or enviornment.yml file (Anaconda).

PyTorch:

  • torch
  • torchaudio
  • torchvision

** Data, vision, and math packages:*

  • numpy
  • pandas
  • opencv-python
  • Pillow
  • PyYAML
  • tqdm
  • beautifulsoup4
  • requests

See requirements.txt or environment.yml for version requirements.

Optional dependencies: * Anaconda (for virtual environment implementation) * Git CLI (for repository cloning)

Recommendations

  • matplotlib (data plotting in Python)
  • jupyter or notebook (viewing Jupyter notebook demonstrations provided in the GitHub repo)

See Getting Started for installation and setup instructions.

Release Notes

Version History
  • 2025.0.1 (BETA) (May 2025): Initial version for testing with the following functionality:
    • Run via command line with image, output, and model directories passed as required arguments
  • 2025.0.2 (July 2025):
    • Adds optional histogram normalization (simple histogram equalization and Contrast Limited Adaptive Histogram Equalization)
    • Separates image pre-processing and scale ageing into two separate scripts
    • Model settings and hyperparameters, including input and output file paths, are now listed in a configuration YAML file passed as a single command line argument to both Python scripts
  • 2025.0.3 (September 2025):
    • Now describes the multimodal model (images plus metadata) and how to use it
  • 2026.1.0 (BETA) (July 2026):
    • Streamlined model setup and usage via a new Windows Batch launcher file
    • Consolidated configuration file with clearer key names
    • Default configuration settings set in model scripts to minimize unneeded clutter in user configuration files
    • Support for all directory path formats (Linux forward slashes, Windows back slashes, and double back slashes)
    • Multimodal model now crashes when metadata are not present instead of silently skipping (user requested behavior)
    • Automatically extract required metadata fields from database CSV file


License

Software code created by U.S. Government employees is not subject to copyright in the United States (17 U.S.C. §105). The United States/Department of Commerce reserve all rights to seek and obtain copyright protection in countries other than the United States for Software authored in its entirety by the Department of Commerce. To this end, the Department of Commerce hereby grants to Recipient a royalty-free, nonexclusive license to use, copy, and create derivative works of the Software outside of the United States.

Disclaimer

This software is a scientific product and is not official communication of the National Oceanic and Atmospheric Administration, or the United States Department of Commerce. All NOAA software and project code is provided on an “as is” basis and the user assumes responsibility for its use. Any claims against the Department of Commerce or Department of Commerce bureaus stemming from the use of this software will be governed by all applicable Federal law. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government.