Merge pull request #199 from NOAA-GFDL/add_regrid_xy

Add regrid xy

docs/subtools.rst

@@ -27,7 +27,7 @@ Catalogs are generated by the following command: fre catalog buildcatalog <INPUT
 
 (OUTPUT_PATH should end with the desired output filename WITHOUT a file ending) See example below.
 
-.. code-block:: terminal
+.. code-block:: console
 fre catalog buildcatalog --overwrite /archive/path_to_data_dir ~/output
 
 fre check (not yet implemented)

fre/app/freapp.py

@@ -7,70 +7,118 @@
 
 from .mask_atmos_plevel import mask_atmos_plevel_subtool
 from .generate_time_averages.generate_time_averages import generate
+from .regrid_xy.regrid_xy import _regrid_xy
 
 @click.group(help=click.style(" - access fre app subcommands", fg=(250,154,90)))
 def app_cli():
     ''' entry point to fre app click commands '''
 
+@app_cli.command()
+@click.option("-i", "--input_dir",
+              type = str,
+              help = "`inputDir` / `input_dir` (env var) specifies input directory to regrid, " + \
+                     "typically an untarredv history file archive" ,
+              required = True)
+@click.option("-o", "--output_dir",
+              type = str,
+              help = "`outputDir` / `output_dir` (env var) specifies target location for output" + \
+                     " regridded files",
+              required = True)
+@click.option("-b", "--begin",
+              type = str,
+              help = "`begin` / `begin` (env var) ISO8601 datetime format specification for" + \
+                     " starting date of data, part of input target file name",
+              required = True)
+@click.option("-tmp", "--tmp_dir",
+              type = str,
+              help = "`TMPDIR` / `tmp_dir` (env var) temp directory for location of file " + \
+                     "read/writes",
+              required = True)
+@click.option("-rd", "--remap_dir",
+              type = str,
+              help = "`fregridRemapDir` / `remap_dir` (env var) directory containing remap file" + \
+                     " for regridding",
+              required = True)
+@click.option("-s", "--source",
+              type = str,
+              help = "`source` / `source` (env var) source name for input target file name " + \
+                     "within input directory to target for regridding. the value for `source` " + \
+                     "must be present in at least one component's configuration fields",
+              required = True)
+@click.option("-g", "--grid_spec",
+              type = str,
+              help = "`gridSpec` / `grid_spec` (env var) file containing mosaic for regridding",
+              required = True)
+@click.option("-xy", "--def_xy_interp",
+              type = str,
+              help = "`defaultxyInterp` / `def_xy_interp` (env var) default lat/lon resolution " + \
+                     "for output regridding. (change me? TODO)",
+              required = True)
+@click.pass_context
+def regrid(context,
+              input_dir, output_dir, begin, tmp_dir,
+              remap_dir, source, grid_spec, def_xy_interp ):
+    ''' regrid target netcdf file '''
+    context.forward(_regrid_xy)
 
 @app_cli.command()
 @click.option("-i", "--infile",
-              type=str,
-              help="Input NetCDF file containing pressure-level output to be masked",
-              required=True)
+              type = str,
+              help = "Input NetCDF file containing pressure-level output to be masked",
+              required = True)
 @click.option("-o", "--outfile",
-              type=str,
-              help="Output file",
-              required=True)
-@click.option("-p", "--psfile",
-              help="Input NetCDF file containing surface pressure (ps)",
-              required=True)
+              type = str,
+              help = "Output file",
+              required = True)
+@click.option("-p", "--psfile", # surface pressure... ps? TODO
+              help = "Input NetCDF file containing surface pressure (ps)",
+              required = True)
 @click.pass_context
 def mask_atmos_plevel(context, infile, outfile, psfile):
-    # pylint: disable=unused-argument
+    # pylint: disable = unused-argument
     """Mask out pressure level diagnostic output below land surface"""
     context.forward(mask_atmos_plevel_subtool)
 
 
 @app_cli.command()
 @click.option("-i", "--inf",
-              type=str,
-              required=True,
-              help="Input file name")
+              type = str,
+              required = True,
+              help = "Input file name")
 @click.option("-o", "--outf",
-              type=str,
-              required=True,
-              help="Output file name")
+              type = str,
+              required = True,
+              help = "Output file name")
 @click.option("-p", "--pkg",
-              type=click.Choice(["cdo","fre-nctools","fre-python-tools"]),
-              default="cdo",
-              help="Time average approach")
+              type = click.Choice(["cdo","fre-nctools","fre-python-tools"]),
+              default = "cdo",
+              help = "Time average approach")
 @click.option("-v", "--var",
-              type=str,
-              default=None,
-              help="Specify variable to average")
+              type = str,
+              default = None,
+              help = "Specify variable to average")
 @click.option("-u", "--unwgt",
-              is_flag=True,
-              default=False,
-              help="Request unweighted statistics")
+              is_flag = True,
+              default = False,
+              help = "Request unweighted statistics")
 @click.option("-a", "--avg_type",
-              type=click.Choice(["month","seas","all"]),
-              default="all",
-              help="Type of time average to generate. \n \
-                    currently, fre-nctools and fre-python-tools pkg options\n \
-                    do not support seasonal and monthly averaging.\n")
+              type = click.Choice(["month","seas","all"]),
+              default = "all",
+              help = "Type of time average to generate. \n \
+                     currently, fre-nctools and fre-python-tools pkg options\n \
+                     do not support seasonal and monthly averaging.\n")
 @click.option("-s", "--stddev_type",
-              type=click.Choice(["samp","pop","samp_mean","pop_mean"]),
-              default="samp",
-              help="Compute standard deviations for time-averages as well")
+              type = click.Choice(["samp","pop","samp_mean","pop_mean"]),
+              default = "samp",
+              help = "Compute standard deviations for time-averages as well")
 @click.pass_context
 def gen_time_averages(context, inf, outf, pkg, var, unwgt, avg_type, stddev_type):
-    # pylint: disable=unused-argument
+    # pylint: disable = unused-argument
     """
     generate time averages for specified set of netCDF files. 
     Example: generate-time-averages.py /path/to/your/files/
     """
-    start_time=time.perf_counter()
+    start_time = time.perf_counter()
     context.forward(generate)
     # need to change to a click.echo, not sure if echo supports f strings
     print(f'Finished in total time {round(time.perf_counter() - start_time , 2)} second(s)')

fre/app/regrid_xy/README.md

@@ -0,0 +1,55 @@
+# ABOUT
+
+`regrid_xy.py` remaps scalar and/or vector fields from one kind of lat/lon grid to another.  It can remap between different grids of the same type (e.g. spherical), and between grids of different types (e.g. spherical to tripolar). By default, it uses an O(1) conservative interpolation scheme to accomplish the regridding, except under certain conditions [defined within `fregrid`](https://github.com/NOAA-GFDL/FRE-NCtools/blob/master/tools/fregrid/fregrid.c#L915-L920) the underlying CLI tool which does the heavy lifting.
+
+requires `fre-nctools` and `fregrid` to be in one's `PATH` variable, and `python3` (tested/developed with python 3.9.16). there should be `netCDF4` and `metomi` python modules in one's python environment for imports. `pytest` and `nccmp` is required for tests. `pylint` recommended for future developers working on this tool. 
+
+
+# INPUT PARAMETERS (mandatory, env vars)
+format here is: 
+config field name / python variable name (type) explanation
+
+the following are required to be specified:
+_______________________________________
+`inputDir` / `input_dir` (env var) specifies input directory to regrid, typically an untarredv history file archive
+_______________________________________
+`source` / `source` (env var) source name for input target file name within input directory to target for regridding. the value for `source` must be present in at least one component's configuration fields
+_______________________________________
+`begin` / `begin` (env var) ISO8601 datetime format specification for starting date of data, part of input target file name
+_______________________________________
+`outputDir` / `output_dir` (env var) specifies target location for output regridded files
+_______________________________________
+`TMPDIR` / `tmp_dir` (env var) temp directory for location of file read/writes
+_______________________________________
+`fregridRemapDir` / `remap_dir` (env var) directory containing remap file for regridding
+_______________________________________
+`gridSpec` / `grid_spec` (env var) file containing mosaic for regridding 
+_______________________________________
+`defaultxyInterp` / `def_xy_interp` (env var) default lat/lon resolution for output regridding. (change me? TODO)
+
+
+# INPUT PARAMETERS (configuration fields, mandatory)
+the following parameters are REQUIRED to be specified on a per-component basis wtihin `app/regrid-xy/rose-app.conf`. A component's input parameters are delineated with a `[component_name]`
+_______________________________________
+`inputRealm` / `input_realm` (config field) realm within model from which the input component/source files are derived
+_______________________________________
+`interpMethod` / `interp_method` (config field) interpolation method to use for regridding, it may be changed if it is specified in the target source file's attributes
+_______________________________________
+`inputGrid` / `input_grid` (config field) current grid type of input source files.
+_______________________________________
+`sources` / N/A (config field)
+
+# INPUT PARAMETERS (configuration fields, optional)
+the following parameters are OPTIONAL for specifying on a per-component basis within `app/regrid-xy/rose-app.conf`.
+_______________________________________
+`outputGridType` / `output_grid_type` (config field) used only for output dir to specify grid type, but does not determine actual output grid type for regridding to fregrid
+_______________________________________
+`fregridRemapFile` / `fregrid_remap_file` (config field) remap file name to use for regridding
+_______________________________________
+`fregridMoreOptions` / `more_options` (config field) field for specifying additional options to `fregrid` that have not-yet been officially implemented. use with caution!
+_______________________________________
+`variables` / `regrid_vars` (config field) list of variable data to regrid within target source files. if unspecified, all variables within the target file of dimension 2 or greater will be regridded.
+_______________________________________
+`outputGridLat` / `output_grid_lat` (config field) latitude resolution for regridded output, also used for remap file targeting if there is no remap file specified.
+_______________________________________
+`outputGridLon` / `output_grid_lon` (config field) latitude resolution for regridded output, also used for remap file targeting if there is no remap file specified.