Merge pull request #2 from dgilford/pkg

Pkg merge
dgilford · Aug 14, 2020 · 3a1f6bb · 3a1f6bb
2 parents aefb0df + 775a222
commit 3a1f6bb
Show file tree

Hide file tree

Showing 24 changed files with 171 additions and 123 deletions.
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 </p>
 
 pyPI is a set of scripts and notebooks that compute and validate tropical cyclone (TC) potential intensity (PI) calculations in Python.
-It is a port of the [Bister and Emanuel 2002](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2001JD000776) algorithm (hereafter BE02) which was originally written in FORTRAN---and then MATLAB---by Prof. Kerry Emanuel (MIT).
+It is a fully documented and improved port of the [Bister and Emanuel 2002](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2001JD000776) algorithm (hereafter BE02) which was originally written in FORTRAN---and then MATLAB---by Prof. Kerry Emanuel (MIT).
 Kerry's original MATLAB code (**pcmin.m**) is found at:
 
 * [http://texmex.mit.edu/pub/emanuel/TCMAX](http://texmex.mit.edu/pub/emanuel/TCMAX)
@@ -28,14 +28,24 @@ Gilford, D. M. 2020: pyPI: Potential Intensity Calculations in Python, v1.2, Zen
 
 ## Full pyPI Description
 
-Please read [pyPI_Documentation_v1.2.pdf](pyPI_Documentation_v1.2.pdf) for a full overview and details on pyPI.
+Please read [pyPI_Users_Guide_v1.3.pdf](pyPI_Users_Guide_v1.3.pdf) for a full overview and details on pyPI.
 The description includes the pyPI background, a PI computation derivation, validation against the commonly-used MATLAB algorithm (pcmin), and a set of sample analyses.
 
+A manuscript detailing the development of pyPI is be prepared for submission.
+
 ## Getting Started
 
 pyPI requires **Python version 3.7+** to run. It was written and tested with Python 3.7.6.
 To get pyPI up and running on your system, clone the repository and ensure that you have the required dependencies.
 
+### Installation
+
+Use the python package manager [pip](https://pip.pypa.io/en/stable/) to install pyPI (tcpypi) from the command line:
+
+```bash
+pip install tcpypi
+```
+
 ### pyPI Dependencies
 
 * NumPy 1.18.1
@@ -62,7 +72,7 @@ and examine the outputs locally produced in [full_sample_output.nc](./data/full_
 ## File Descriptions
 
 #### Key files
-* **[pi.py](pi.py)** - The primary function of pyPI, that computes and outputs PI (and associated variables) given atmospheric and ocean state variables.
+* **[pi.py](./pyPI/pi.py)** - The primary function of pyPI, that computes and outputs PI (and associated variables) given atmospheric and ocean state variables.
 * **[run_sample.py](run_sample.py)** - Example script that computes PI and accompanying analyses over the entire sample dataset
 
 #### Data
@@ -77,9 +87,10 @@ and examine the outputs locally produced in [full_sample_output.nc](./data/full_
 * **[sample_output_analyses.ipynb](./notebooks/sample_output_analyses.ipynb)** - Notebook showing examples of pyPI outputs and simple PI analyses
 
 #### Misc.
-* **[utilities.py](utilities.py)** - Set of functions used in the pyPI codebase
+* **[utilities.py](./pyPI/utilities.py)** - Set of functions used in the pyPI codebase
+* **[constants.py](./pyPI/constants.py)** - Set of meteorological constants used in the pyPI codebase
 * **[reference_calculations.m](./matlab_scripts/reference_calculations.m)** - Script used to generate sample BE02 MATLAB outout data from original MERRA2 files monthly mean; included for posterity and transperancy
-* **[pc_min.m](pc_min.m)** - Original BE02 algorithm from MATLAB, adapted and used to produce analyses of Gilford et al. ([2017](https://journals.ametsoc.org/doi/abs/10.1175/JCLI-D-16-0827.1); [2019](https://journals.ametsoc.org/doi/10.1175/MWR-D-19-0021.1))
+* **[pc_min.m](./matlab_scripts/pc_min.m)** - Original BE02 algorithm from MATLAB, adapted and used to produce analyses of Gilford et al. ([2017](https://journals.ametsoc.org/doi/abs/10.1175/JCLI-D-16-0827.1); [2019](https://journals.ametsoc.org/doi/10.1175/MWR-D-19-0021.1))
 * **[clock_pypi.ipynb](./notebooks/clock_pypi.ipynb)** - Notebook estimating the time it takes to run pyPI on a laptop
 
 ## Author

diff --git a/data/full_sample_output.nc b/data/full_sample_output.nc
diff --git a/data/mdr.pk1 b/data/mdr.pk1
diff --git a/data/raw_sample_output.nc b/data/raw_sample_output.nc
diff --git a/figures/2004_picorr.pdf b/figures/2004_picorr.pdf
diff --git a/figures/annualavg_maps.pdf b/figures/annualavg_maps.pdf
diff --git a/figures/seas_cycle_amp_decomp.pdf b/figures/seas_cycle_amp_decomp.pdf
diff --git a/figures/seas_cycles.pdf b/figures/seas_cycles.pdf
diff --git a/figures/sept04_diffpimap.pdf b/figures/sept04_diffpimap.pdf
diff --git a/figures/sept04_pimaps.pdf b/figures/sept04_pimaps.pdf
diff --git a/figures/sept2004_missmap.pdf b/figures/sept2004_missmap.pdf
diff --git a/pc_min.m → matlab_scripts/pc_min.m b/pc_min.m → matlab_scripts/pc_min.m
diff --git a/notebooks/clock_pypi.ipynb b/notebooks/clock_pypi.ipynb
diff --git a/notebooks/sample_output_analyses.ipynb b/notebooks/sample_output_analyses.ipynb
@@ -28,7 +28,9 @@
     "import matplotlib.pyplot as plt\n",
     "import time\n",
     "# load PI calculation module\n",
-    "from pi import pi"
+    "from pyPI import pi\n",
+    "# imports utility functions\n",
+    "from pyPI.utilities import *"
    ]
   },
   {
@@ -96,7 +98,7 @@
     "    result = xr.apply_ufunc(\n",
     "        pi,\n",
     "        ds['sst'], ds['msl'], ds['p'], ds['t'], ds['q'],\n",
-    "        kwargs=dict(CKCD=CKCD, ascent_flag=0, diss_flag=1, miss_handle=1),\n",
+    "        kwargs=dict(CKCD=CKCD, ascent_flag=0, diss_flag=1, ptop=50, miss_handle=1),\n",
     "        input_core_dims=[\n",
     "            [], [], ['p', ], ['p', ], ['p', ],\n",
     "        ],\n",
@@ -158,16 +160,6 @@
    "execution_count": 6,
    "metadata": {},
    "outputs": [],
-   "source": [
-    "# import the function to convert longitudes from 0-360E to 180W-180E\n",
-    "from utilities import convert_lon_to180"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 7,
-   "metadata": {},
-   "outputs": [],
    "source": [
     "# find grid spacing and set bounds from central points according with it\n",
     "xl=np.abs(ds.lon[1]-ds.lon[0])/2\n",
@@ -214,7 +206,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 7,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -268,19 +260,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# import the functions to calculate TC efficiency, air-sea thermodynamic disequilibrium, and PI decomposition\n",
-    "from utilities import pi_effiency\n",
-    "from utilities import pi_diseq_resid\n",
-    "from utilities import decompose_pi"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -351,7 +331,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -368,7 +348,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -417,7 +397,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 11,
    "metadata": {},
    "outputs": [
     {
@@ -460,7 +440,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 12,
    "metadata": {},
    "outputs": [
     {
@@ -495,7 +475,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 13,
    "metadata": {},
    "outputs": [
     {
@@ -530,7 +510,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": 14,
    "metadata": {},
    "outputs": [
     {
@@ -565,7 +545,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 15,
    "metadata": {},
    "outputs": [
     {
@@ -600,7 +580,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 18,
+   "execution_count": 16,
    "metadata": {},
    "outputs": [
     {
@@ -651,7 +631,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": 17,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -664,7 +644,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": 18,
    "metadata": {},
    "outputs": [
     {
@@ -711,7 +691,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 21,
+   "execution_count": 19,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -741,7 +721,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 22,
+   "execution_count": 20,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -776,7 +756,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 23,
+   "execution_count": 21,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -806,7 +786,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 24,
+   "execution_count": 22,
    "metadata": {},
    "outputs": [
     {
@@ -835,7 +815,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 25,
+   "execution_count": 23,
    "metadata": {},
    "outputs": [
     {
@@ -864,7 +844,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 26,
+   "execution_count": 24,
    "metadata": {},
    "outputs": [
     {
@@ -893,7 +873,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 27,
+   "execution_count": 25,
    "metadata": {},
    "outputs": [
     {
@@ -922,7 +902,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 28,
+   "execution_count": 26,
    "metadata": {},
    "outputs": [
     {
@@ -951,7 +931,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 29,
+   "execution_count": 27,
    "metadata": {},
    "outputs": [
     {
@@ -987,7 +967,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 30,
+   "execution_count": 28,
    "metadata": {
     "scrolled": true
    },
@@ -1019,7 +999,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 31,
+   "execution_count": 29,
    "metadata": {},
    "outputs": [
     {