Overview: Why aospy?

Use cases

If you’ve ever found yourself saying or thinking anything along these lines, then aospy may be a great tool for you:

  • “What is this precip01.dat file in my home directory that I vaguely remember creating a few weeks ago? Better just delete it and re-do the calculation to be sure.”
  • “I really need to analyze variable X. But the models/observational products I’m using don’t provide it. They do provide variables Y and Z, from which I can compute quantity X.”
  • “I need to calculate quantity X from 4 different simulations repeated in 5 different models; computing monthly, seasonal, and annual averages and standard deviations; gridpoint-by-gridpoint and averaged over these 10 regions. That’s impractical – I’ll just do a small subset.”

Each of these common problems is easily solved by using aospy.

Design philosophy

aospy’s ability to automate calculations (while properly handling model- and simulation-level idiosyncrasies) relies on separating your code into three distinct categories.

  1. Code characterizing the data you want to work with: “Where is your data and what does it represent?”
  2. Code describing abstract physical quantities and geographical regions you eventually want to examine: “What things are you generally interested in calculating?”
  3. Code specifying the exact parameters of calculations you want to perform right now: “Ok, time to actually crunch some numbers. Exactly what all do you want to compute from your data, and how do you want to slice and dice it?”

How you’ll actually interact with aospy in order to achieve each of these three steps is described in the Using aospy section of this documentation, and explicit examples using included sample data are in the Examples section.

Open Science & Reproducible Research

This separation of your code into three categories promotes open science and reproducible research in multiple ways:

  • By separating code that describes where your data is from the code used to compute particular physical quantities, the latter can be written in a generic form that closely mimics the physical form of the particular expression. The resulting code is easier to read and debug and therefore to share with others.
  • By enabling automation of calculations across an arbitrary number of parameter combinations, aospy facilitates more rigorous analyses and/or analyses encompassing a larger span of input data than would otherwise be possible.
  • By outputting the results of calculations as netCDF files in a highly organized directory structure with lots of metadata embued within the file path, file name, and the netCDF file itself, aospy facilitates the sharing of results with others (including your future self that has forgotten the myriad details of how you have computed things right now).