IOAPIpytools package

Release:1.0
Date:18 January 2017

Submodules

IOAPIpytools.ioapi_pytools module

functions useful for manipulating Models-3 I/O API data files in python. Models-3 I/O API are built on netCDF, but I have found that performing these tasks using Python’s netCDF4 module results in strange, hard-to-debug errors. For example, metadata strings that appear to be I/O API-legal and that are readable with ncdump are not readable by the Models-3 I/O API Fortran API. Performing those same tasks using these python wrappers around m3tools seems to avoid these problems.

IOAPIpytools.ioapi_pytools.boundaries_from_csv(fname_csv, fname_bdy, fname_griddesc, gridname, nlevs, file_desc='boundary data')

Create lateral boundary conditions file from data in CSV file

Run M3FAKE to create a boundary condition file from a specified csv file containing the boundaries data. Models-3 I/O API “Logical names” are defined internally, allowing the user to specify paths to the physical files to be manipulated.

Currently only time-independent boundary files are supported.

Currently can only use the default vertical sigma-P coordinates suggested by M3FAKE.

Parameters:
  • fname_csv (string) – full path to the comma-separated variable data file containing the boundary conditions.
  • fname_bdy (string) – full path to the Models-3 I/O API boundaries file to create. Will be overwritten if the file already exists.
  • fname_griddesc (string) – full path to the Models-3 I/O API GRIDDESC file describing the model grid.
  • gridname (string) – name of the grid to create boundaries for (must be an entry in the GRIDDESC file).
  • nlevs (int) – number of vertical levels.
  • file_desc (string) – string to populate the FDESC3D metadata field in the boundary condition file. Defaults to “boundary data”.

RETURNS: None

IOAPIpytools.ioapi_pytools.calculate_regrid_matrix(fname_griddesc, fname_matrix, fname_mattxt, in_grid, out_grid, col_refinement=1000, row_refinement=1000)

run mtxcalc (from the Models-3 I/O API) to calculate a regrid matrix for a specified grid-to-grid transformation. Models-3 I/O API “Logical names” (see Models-3 I/O API documentation) are defined internally, allowing the user to specify paths to the physical files to be manipulated.

Parameters:
  • fname_griddesc (string) – full path to the GRIDDESC file
  • fname_matrix (string) – full path to the binary matrix file to be created
  • fname_mattxt (string) – full path to the ASCII matrix file to be created
  • in_grid (string) – name of the source grid in the GRIDDESC file
  • out_grid (string) – name of the destination grid in the GRIDDESC file
  • col_refinement (integer) – col_refinement argument to pass to mtxcalc
  • row_refinement (integer) – row_refinement argument to pass to mtxcalc

See also

Models-3 I/O API mtxcalc documentation

IOAPIpytools.ioapi_pytools.concat(file1, file2)

concatenate file2 to file1 using m3xtract

IOAPIpytools.ioapi_pytools.delete_if_exists(fname)

remove a file if it exists, with a message to stdout

Parameters:fname (string) – full path to the file to be removed
IOAPIpytools.ioapi_pytools.dummy_top_bounds(fname_bdy, fname_griddesc, gridname, file_desc='boundary data')

Create lateral boundary conditions file from data in CSV file

Run M3FAKE to create a top boundary condition file containing 0.0 at all locations. Models-3 I/O API “Logical names” are defined internally, allowing the user to specify paths to the physical files to be manipulated.

Currently only time-independent boundary files are supported.

Parameters:
  • fname_bdy (string) – full path to the Models-3 I/O API boundaries file to create. Will be overwritten if the file already exists.
  • fname_griddesc (string) –

    full path to the Models-3 I/O API GRIDDESC file describing the model grid.

  • gridname (string) – name of the grid to create boundaries for (must be an entry in the GRIDDESC file).
  • file_desc (string) –

    string to populate the FDESC3D metadata field in the boundary condition file. Defaults to “boundary data”.

RETURNS: None

IOAPIpytools.ioapi_pytools.ioapi_const_multiply(fname_in, fname_out, in_varname, out_varname, constant_factor, new_units, new_desc)

Multiply a variable in a Models-3 I/O API file by a constant using M3COMBO and place result in a new I/O API file. Update the file headers for the new file with user-specified information. Models-3 I/O API “Logical names” are defined internally, allowing the user to specify paths to the physical files to be manipulated.

Parameters:
  • fname_in (string) – full path to the input Models-3 I/O API file
  • fname_out (string) – full path to the output Models-3 I/O API file
  • in_varname (string) – the variable to be multiplied by a constant
  • out_varname (string) – the name of the multiplied variable in the output file
  • constant_factor (scalar) – the constant factor by which to multiply in_varname
  • new_units (string) – units of the variable named in_varname in the output file
  • new_desc (string) – description text to populate the “desc” field of the multiplied variable in the output file
Returns:

None
IOAPIpytools.ioapi_pytools.run_bcwndw(fname_gridded, fname_bdy, LOROW=1, HIROW=123, LOCOL=1, HICOL=123)

Run bcwndw (from the Models-3 I/O API) to create a boundary condition file from a specified Models-3 I/O API file containing gridded data. Models-3 I/O API “Logical names” (see Models-3 I/O API documentation) are defined internally, allowing the user to specify paths to the physical files to be manipulated.

IOAPIpytools.ioapi_pytools.run_regrid(fname_raw, fname_regridded, fname_matrix, fname_mattxt)

perform mass-conservative regrid of Models-3 I/O API data using mtxcple

run mtxcple (from the Models-3 I/O API) to regrid a specified dataset from a Models-3 I/O API file.

Models-3 I/O API Logical names are defined internally, allowing the user to specify paths to the physical files to be manipulated.

Parameters:
  • fname_raw (string) – full path for the Models-3 I/O API data file containing data on the source grid.
  • fname_regridded (string) – full path for the regridded Models-3 I/O API file to create. fname_regridded is overwritten if it exists.
  • fname_matrix (string) – full path for the matrix file (see :mod:ioapi_tools.calculate_regrid_matrix)
  • fname_mattxt (string) – full path for the mattxt file (see :mod:ioapi_tools.calculate_regrid_matrix)
IOAPIpytools.ioapi_pytools.run_regrid_NN(fname_raw, fname_regridded, fname_griddesc, out_grid_name)

Nearest neighbor regrid using Models-3 I/O API tools. Run m3interp (from the Models-3 I/O API) to regrid a specified dataset from a Models-3 I/O API file. Models-3 I/O API “Logical names” (see Models-3 I/O API documentation) are defined internally, allowing the user to specify paths to the physical files to be manipulated.

IOAPIpytools.ioapi_pytools.window_to_NorthAmerica(fname_in, fname_out, fname_griddesc, grid_name)

window SiB I/O API file to one quarter of the globe.

Uses the Models-3 I/O API utility m3wndw to extract data from an I/O API file to a specified subgrid.

The window_to_NorthAmerica reflects the function’s original use to extract data that are North of the equator and between 0 W and 180 W longitude. Considering this subset (25%) of a global data set speeds calculation of regridding matrices considerably.

Models-3 I/O API Logical names are defined internally, allowing the user to specify paths to the physical files to be manipulated.

Parameters:
  • fname_in (string) – full path to the global SiB Models-3 I/O API file
  • fname_out (string) – full path for the windowed Models-3 I/O API file to create. fname_out is overwritten if it exists.
  • fname_griddesc (string) – full path the Models-3 I/O API GRIDDESC file describing the destination grid.
  • grid_name (string) – the name of the destination grid in the GRIDDESC file.

Module contents