3. Software Installation/Getting Started

3.1. Introduction

This chapter describes how to install and get started using METdataio. METdataio has been developed and tested on Mac and Linux operating systems. Support for additional platforms may be added in future releases.

METdbload is a Python3 program that requires some extra packages to be available on the user’s computer prior to installation. METdbload is part of the METdataio database package. Additional METdataio programs that work with the data are planned.

3.2. Requirements

METdataio relies on the following tools. These must be installed and tested prior to installing METdataio:

MySQL or MariaDB - download and install the latest version. This can be on a separate computer. Use “SET GLOBAL max_allowed_packet=110000000;” by typing the command in the CLI and/or make the corresponding edit to /etc/my.cnf, so that the change persists after the next reboot.

AuroraDB could alternately be used as a database in the cloud.

3.2.1. Python Requirements

Python 3.12+ - Python 3.12 or higher must be installed.

NOTE Due to the lack of backwards compatibility in pandas 2.x, this code no longer works with Python 3.10

The requirements below come directly from the requirements.txt file at the top level of the repository.

lxml>=5.3.0
numpy>=2.2.2
pandas>=2.2.3
pip>=26.1
PyMySQL>=1.1.1
pytest>=8.3.4
PyYAML>=6.0.2
xarray>=2025.1.2

3.3. Installation

3.3.1. Download

Download the latest release:

git clone https://github.com/dtcenter/METdataio

3.3.1.1. Instructions for installing the METdataio package locally via conda

  • Activate the conda environment, changing <your-conda-env-name> to the correct location.

    conda activate <your-conda-env-name>

  • From within the active conda environment, change directories to be in the METdataio/ directory, where the file pyproject.toml is located.

  • From this directory, run the following on the command line:

    pip install -e .

  • The -e option stands for editable, which is useful to update the user’s METdataio source without reinstalling it.

  • The . indicates that the user should search the current directory for the pyproject.toml file.

  • To use the modules in the METdataio/METdbLoad/ush directory, use the metdataio package via an import statement:

    from metdataio import metdbload.ush

3.3.1.2. Instructions for setting the PYTHONPATH

If pip install is not permitted for the host machine, setting the PYTHONPATH is an alternative. Add the following to the existing PYTHONPATH:

bash:

export PYTHONPATH=${PYTHONPATH}:$SRC/METdataio:$SRC/METdataio/METdbLoad:$SRC/METdataio/METdbLoad/ush:$SRC/METdataio/METreformat:$SRC/METdataio/METreadnc

Or

cshrc:

setenv PYTHONPATH ${PYTHONPATH}:$SRC/METdataio:

This will ensure that all available METdataio code will be loaded.

$SRC - Represents the path to the METdataio code.

${PYTHONPATH} - Corresponds to existing paths that are already defined.

Note

Programs can be run from the METdbLoad/ush subdirectory.