Usage

Predicting the ages of a set of menhaden scale images

Running the Menhaden Ageing Model is straightforward and only requires two steps: processing the raw images and then running the age inference model. You will, however, need to modify a configurations.yml file, as described previously.

Basic Users

The easiest way to launch the model is with the provided menhaden-age-model utility, a Windows Batch (.bat) file designed to streamline Python environment management and script execution. Behind the scenes, this utility checks the workstation for an existing Python installation, creates and manages a Python virtual environment and necessary package dependencies, and handles launching the necessary Python scripts that contain the ageing model and associated data processing routines. Virtual environment creation and setup (i.e., package installation) only happens the first time this utility is launched. Each time thereafter, the existing virtual environment is automatically detected and activated.

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.

Advanced Users

Activate the Virtual Environment

Navigate (cd) into the directory containing the predict-ages-multimodal.py script. If you simply cloned the repo and have not moved anything around, this will in the /scripts subdirectory in the cloned repository. For example:

cd "c:/Users/user.name/Documents/ageing/FATES-BLH-ScaleAgeing/scripts"

Activate the virtual environment we previously configured. In a terminal window, type:

pip environment

.scaleageing\Scripts\activate

conda environment

conda activate scaleageing

Tip

If you named your virtual environment something other than “scaleageing”, invoke that name instead.

Process Images

All Python scripts are stored in the /scripts subdirectory in the repo. To process raw scale images:

python scripts/process-images.py --config_path <config_dir>

where <config_dir> is the path to the configuration file containing model settings.

What if cropping fails?

Variations in image coloring, such as different foreground/background contrasts or lighting, can affect how well individual scales are cropped out of the original image. If you encounter issues with this, first try adjusting binary_threshold in your configuration file, which adjusts the foreground/background distinction. If that doesn’t work, or doesn’t work by itself, try adjusting pad (left, top, and right side of the scale) and bottom_pad to add or remove background space around the individual scale. See the configuration page for more details.

Running the model to predict ages

To predict ages, use one of the following:

Image only model

python scripts/predict-ages-images.py --config_path <config_dir>

Image and metadata model

python scripts/predict-ages-multimodal.py --config_path <config_dir>

where <config_dir> is the path to the configuration file containing model settings.

Examples

If your configurations.yml file is stored alongside your model script, your execution commands will simply be:

python scripts/process-images.py --config_path configurations.yml
python scripts/predict-ages-multimodal.py --config_path configurations.yml

Or, if you named your configuration file something unique such as configuration-2024-atl.yml, it might look like this:

python scripts/process-images.py --config_path configuration-2024-atl.yml
python scripts/predict-ages-multimodal.py --config_path configuration-2024-atl.yml

Alternatively, your configurations.yml file is stored alongside your data, you will need to tell the script exactly where that file is located using its full directory path. Be sure to also include the correct file name, if applicable. For example:

python scripts/process-images.py --config_path "c:/Users/user.name/Documents/data/2024/configurations.yml"
python scripts/predict-ages-multimodal.py --config_path "c:/Users/user.name/Documents/data/2024/configurations.yml"

Tip

If you get a “File not found” error when running the script, carefully check your directories and file names, including those contained in the configuration file.

When finished

When you are finished running the model, deactivate the virtual environment to free up resources on your computer:

pip environment

deactivate

conda environment

conda deactivate