POP-tools Documentation Release 2021.5.28.post11+dirty pop-tools developers 2021-09-20 USER GUIDE 1 Installation 3 2 Get in touch 5 2.1 Installing.................................................5 2.2 Examples.................................................6 2.3 API Reference.............................................. 73 2.4 Contributing Guide............................................ 78 2.5 Changelog................................................ 81 Index 83 i ii POP-tools Documentation, Release 2021.5.28.post11+dirty CI Docs Package License USER GUIDE 1 POP-tools Documentation, Release 2021.5.28.post11+dirty 2 USER GUIDE CHAPTER ONE INSTALLATION pop-tools can be installed from PyPI with pip: python -m pip install pop-tools pop-tools is also available from conda-forge for conda installations: conda install -c conda-forge pop-tools See documentation for more information. 3 POP-tools Documentation, Release 2021.5.28.post11+dirty 4 Chapter 1. Installation CHAPTER TWO GET IN TOUCH • If you encounter any errors or problems with pop-tools, please open an issue at the GitHub main repository. • If you have a question like “How do I compute x?”, ask on GitHub discussions. Please include a self-contained reproducible example if possible. 2.1 Installing You can install pop-tools with pip, conda, or by installing from source. 2.1.1 Pip Pip can be used to install pop-tools: python -m pip install pop-tools 2.1.2 Conda To install the latest version of pop-tools from the conda-forge channel using conda: conda install -c conda-forge pop-tools 2.1.3 Install from Source To install pop-tools from source, clone the repository from Github git clone https://github.com/NCAR/pop-tools.git cd pop-tools python -m pip install -e . You can also install directly from git master branch:: python -m pip install git+https://github.com/NCAR/pop-tools 5 POP-tools Documentation, Release 2021.5.28.post11+dirty 2.2 Examples 2.2.1 Sample Data pop-tools provides some sample data through the pop_tools.datasets module. Where are the sample data files? The sample data files are downloaded automatically by pooch the first time you load them. import xarray as xr import pop_tools To find which data files are available via pop_tools, you can run the following: pop_tools.DATASETS.registry_files ['tend_zint_100m_Fe.nc', 'iron_tracer.nc', 'daily_surface_potential_temperature.nc', 'monthly_dissolved_oxygen.nc', 'cesm_pop_monthly.T62_g17.nc', 'lateral_fill_np_array_filled_ref.npz', 'lateral_fill_np_array_tripole_filled_ref.npz', 'lateral_fill_np_array_tripole_filled_ref.20200818.npz', 'lateral_fill_np_array_filled_SOR_ref.20200820.npz', 'lateral_fill_np_array_tripole_filled_SOR_ref.20200820.npz', 'POP_gx3v7.nc', 'g.e20.G.TL319_t13.control.001_hfreq.nc', 'g.e20.G.TL319_t13.control.001_hfreq-coarsen.nc', 'Pac_POP0.1_JRA_IAF_1993-12-6-test.nc', 'Pac_grid_pbc_1301x305x62.tx01_62l.2013-07-13.nc', 'comp-grid.tx9.1v3.20170718.zarr.zip'] Once you know which file you are interested in, you can pass the name to the pop_tools.DATASETS.fetch() function. This function will download the file if it does not exist already on your local system. After the file has been downloaded, the fetch function returns the path: filepath= pop_tools.DATASETS.fetch('cesm_pop_monthly.T62_g17.nc') print(filepath) Downloading file 'cesm_pop_monthly.T62_g17.nc' from 'ftp://ftp.cgd.ucar.edu/archive/ ,!aletheia-data/cesm-data/ocn/cesm_pop_monthly.T62_g17.nc' to '/home/docs/.pop_tools/ ,!data'. /home/docs/.pop_tools/data/cesm_pop_monthly.T62_g17.nc Now, we can pass the file path to the appropriate I/O package for loading the content of the file: ds= xr.open_dataset(filepath) ds 6 Chapter 2. Get in touch POP-tools Documentation, Release 2021.5.28.post11+dirty <xarray.Dataset> Dimensions: (time: 1, z_t: 60, nlat: 384, nlon: 320, lat_aux_grid: 395, d2: 2) Coordinates: TLAT (nlat, nlon) float64 ... TLONG (nlat, nlon) float64 ... ULAT (nlat, nlon) float64 ... ULONG (nlat, nlon) float64 ... * lat_aux_grid (lat_aux_grid) float32 -79.49 -78.95 -78.42 ... 89.47 90.0 * time (time) object 0173-01-01 00:00:00 * z_t (z_t) float32 500.0 1.5e+03 2.5e+03 ... 5.125e+05 5.375e+05 Dimensions without coordinates: nlat, nlon, d2 Data variables: SALT (time, z_t, nlat, nlon) float32 ... TEMP (time, z_t, nlat, nlon) float32 ... UVEL (time, z_t, nlat, nlon) float32 ... VVEL (time, z_t, nlat, nlon) float32 ... time_bound (time, d2) object ... Attributes: title: g.e21.G1850ECOIAF.T62_g17.004 history: Sun May 26 14:13:02 2019: ncks -4 -L 9 cesm_pop_monthl... Conventions: CF-1.0; http://www.cgd.ucar.edu/cms/eaton/netcdf/CF-cu... time_period_freq: month_1 model_doi_url: https://doi.org/10.5065/D67H1H0V contents: Diagnostic and Prognostic Variables source: CCSM POP2, the CCSM Ocean Component revision: $Id: tavg.F90 90507 2019-01-18 20:54:19Z altuntas@ucar... calendar: All years have exactly 365 days. start_time: This dataset was created on 2019-05-26 at 11:20:07.5 cell_methods: cell_methods = time: mean ==> the variable values are ... NCO: netCDF Operators version 4.7.4 (http://nco.sf.net) %load_ext watermark %watermark -d -iv -m -g -h Compiler : GCC 9.4.0 OS : Linux Release : 5.4.0-1035-aws Machine : x86_64 Processor : x86_64 CPU cores : 2 Architecture: 64bit Hostname: build-14766403-project-451810-pop-tools Git hash: 4a346e950481d8efbbd525d98107e2b925ac7c91 pop_tools: 2021.5.28.post11+dirty xarray : 0.19.0 2.2. Examples 7 POP-tools Documentation, Release 2021.5.28.post11+dirty 2.2.2 Get grid The get_grid method returns an xarray.Dataset containing grid variables for a given model grid. It relies on a checkout of binary horizontal grid and topography files from the CESM inputdata repository. The vertical grid files are in the POP2-CESM repository in the input_templates directory; they are maintained separately as part of the pop-tools repository. %matplotlib inline import xarray as xr import pop_tools Get a dataset for the POP_tx0.v3 tripole grid. ds= pop_tools.get_grid('POP_tx0.1v3') ds.info() Downloading file 'inputdata/ocn/pop/tx0.1v3/grid/horiz_grid_200709.ieeer8' from ,!'https://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/ocn/pop/tx0.1v2/grid/horiz_ ,!grid_200709.ieeer8' to '/home/docs/.pop_tools'. /home/docs/checkouts/readthedocs.org/user_builds/pop-tools/conda/latest/lib/python3.8/ ,!site-packages/urllib3/connectionpool.py:1013: InsecureRequestWarning: Unverified ,!HTTPS request is being made to host 'svn-ccsm-inputdata.cgd.ucar.edu'. Adding ,!certificate verification is strongly advised. See: https://urllib3.readthedocs.io/ ,!en/1.26.x/advanced-usage.html#ssl-warnings warnings.warn( 0%| | 0.00/484M [00:00<?, ?B/s] 0%| | 66.6k/484M [00:00<16:54, 477kB/s] 0%| | 481k/484M [00:00<03:27, 2.33MB/s] 0%| | 1.56M/484M [00:00<01:21, 5.89MB/s] 1%| | 4.46M/484M [00:00<00:33, 14.5MB/s] 2%| | 7.29M/484M [00:00<00:27, 17.6MB/s] 2%| | 10.1M/484M [00:00<00:22, 20.8MB/s] 3%| | 13.2M/484M [00:00<00:19, 23.9MB/s] 3%| | 16.1M/484M [00:00<00:18, 25.7MB/s] 4%| | 19.3M/484M [00:00<00:16, 27.5MB/s] 5%| | 22.1M/484M [00:01<00:17, 25.8MB/s] 5%| | 25.0M/484M [00:01<00:17, 26.7MB/s] 8 Chapter 2. Get in touch POP-tools Documentation, Release 2021.5.28.post11+dirty 6%| | 27.7M/484M [00:01<00:17, 26.4MB/s] 6%| | 30.4M/484M [00:01<00:17, 26.5MB/s] 7%| | 33.5M/484M [00:01<00:17, 25.8MB/s] 8%| | 36.4M/484M [00:01<00:16, 26.8MB/s] 8%| | 39.3M/484M [00:01<00:16, 27.5MB/s] 9%| | 42.4M/484M [00:01<00:15, 28.4MB/s] 9%| | 45.2M/484M [00:01<00:16, 26.0MB/s] 10%| | 48.2M/484M [00:02<00:16, 27.1MB/s] 11%| | 51.4M/484M [00:02<00:15, 28.3MB/s] 11%| | 54.4M/484M [00:02<00:14, 29.0MB/s] 12%| | 57.3M/484M [00:02<00:15, 26.9MB/s] 12%| | 60.4M/484M [00:02<00:15, 28.1MB/s] 13%| | 63.6M/484M [00:02<00:14, 29.1MB/s] 14%| | 66.7M/484M [00:02<00:14, 29.7MB/s] 15%| | 70.2M/484M [00:02<00:14, 29.0MB/s] 15%| | 73.6M/484M [00:02<00:13, 30.4MB/s] 16%| | 77.1M/484M [00:03<00:12, 31.8MB/s] 17%| | 80.7M/484M [00:03<00:12, 32.9MB/s] 17%| | 84.0M/484M [00:03<00:12, 32.9MB/s] 18%| | 87.5M/484M [00:03<00:11, 33.5MB/s] 19%| | 90.9M/484M [00:03<00:12, 31.6MB/s] 20%| | 94.4M/484M [00:03<00:11, 32.6MB/s] 20%| | 97.9M/484M [00:03<00:11, 33.0MB/s] 21%| | 101M/484M [00:03<00:11, 33.1MB/s] 2.2. Examples 9 POP-tools Documentation, Release 2021.5.28.post11+dirty 22%| | 105M/484M [00:03<00:11, 33.6MB/s] 22%| | 108M/484M [00:03<00:11, 32.0MB/s] 23%| | 112M/484M [00:04<00:11, 32.7MB/s] 24%| | 115M/484M [00:04<00:11, 33.3MB/s] 24%| | 118M/484M [00:04<00:11, 32.9MB/s] 25%| | 122M/484M [00:04<00:10, 33.5MB/s] 26%| | 125M/484M [00:04<00:11, 32.4MB/s] 27%| | 129M/484M [00:04<00:10, 32.6MB/s] 27%| | 132M/484M [00:04<00:10, 33.2MB/s] 28%| | 136M/484M [00:04<00:10, 32.9MB/s] 29%| | 139M/484M [00:04<00:10, 33.3MB/s] 29%| | 142M/484M [00:04<00:10, 33.7MB/s] 30%| | 146M/484M [00:05<00:10, 32.7MB/s] 31%| | 149M/484M [00:05<00:10, 32.6MB/s] 32%| | 153M/484M [00:05<00:10, 32.7MB/s] 32%| | 156M/484M [00:05<00:10, 32.7MB/s] 33%| | 159M/484M [00:05<00:09, 32.9MB/s] 34%| | 163M/484M [00:05<00:09, 33.5MB/s] 34%| | 166M/484M [00:05<00:10, 30.2MB/s] 35%| | 169M/484M [00:05<00:11, 27.9MB/s] 36%| | 172M/484M [00:05<00:10, 28.6MB/s] 36%| | 175M/484M [00:06<00:10, 29.4MB/s] 37%| | 178M/484M [00:06<00:11, 27.2MB/s] 37%| | 181M/484M [00:06<00:10, 28.0MB/s] 10 Chapter 2.