From e5fe2211bbbf305b1939908ff12669f53520e638 Mon Sep 17 00:00:00 2001 From: Max Grover Date: Wed, 20 Sep 2023 10:03:55 -0500 Subject: [PATCH] DOC: Update outdated installation instructions (#1462) * FIX: Add isinstance checks to improve linting * FIX: Update the installation instructions * FIX: Update python versions * FIX: Update master to main in contributors guide --- CONTRIBUTING.rst | 13 +- INSTALL.rst | 6 +- doc/source/conf.py | 4 +- doc/source/index.rst | 6 +- doc/source/userguide/INSTALL.rst | 157 +------ doc/source/userguide/contributors_guide.rst | 429 +----------------- .../userguide/setting_up_an_environment.rst | 2 +- 7 files changed, 18 insertions(+), 599 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 2df62f2769..ab3f488d9e 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -160,7 +160,7 @@ documentation style. For more on the NumPy documentation style: -- https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt +- https://github.com/numpy/numpy/blob/main/doc/HOWTO_DOCUMENT.rst.txt An example: @@ -340,9 +340,9 @@ GitHub When contributing to pyart, the changes created should be in a new branch under your forked repository. Let's say the user is adding a new map display. -Instead of creating that new function in your master branch. Create a new +Instead of creating that new function in your main branch. Create a new branch called ‘cartopy_map’. If everything checks out and the admin -accepts the pull request, you can then merge the master branch and +accepts the pull request, you can then merge the main branch and cartopy_map branch. To delete a branch both locally and remotely, if done with it:: @@ -362,16 +362,15 @@ To create a new branch:: If you have a branch with changes that have not been added to a pull request but you would like to start a new branch with a different task in mind. It -is recommended that your new branch is based on your master. First:: - - git checkout master +is recommended that your new branch is based on your main. First:: + git checkout main Then:: git checkout -b This way, your new branch is not a combination of your other task branch and -the new task branch, but is based on the original master branch. +the new task branch, but is based on the original main branch. Typing `git status` will not only inform the user of what files have been modified and untracked, it will also inform the user of which branch they diff --git a/INSTALL.rst b/INSTALL.rst index 26d88c99f4..7975fa24b9 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -49,10 +49,10 @@ without these packages. * `Basemap `_ But Cartopy is recommended as basemap will no longer have support. -* `xarray `_ +* `pyproj `_ -* `pytest `_ Obtaining the latest source =========================== diff --git a/doc/source/conf.py b/doc/source/conf.py index bc612a5b16..0a6380bfb6 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -266,10 +266,10 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), - "numpy": ("https://docs.scipy.org/doc/numpy/", None), + "numpy": ("https://numpy.org/doc/stable", None), "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None), "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None), - "matplotlib": ("https://matplotlib.org", None), + "matplotlib": ("https://matplotlib.org/stable", None), } # Add myst extensions diff --git a/doc/source/index.rst b/doc/source/index.rst index 257014053e..af5800da72 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -161,6 +161,8 @@ Short Courses Various short courses on Py-ART and open source radar software have been given which contain tutorial like materials and additional examples. +* `2023 AMS, Open Source Radar Short Course `_ +* `2022 ERAD, Open Source Radar Short Course `_ * `2015 AMS, Open Source Radar Short Course `_ * `2015 ARM/ASR Meeting, PyART, the Python ARM Radar Toolkit `_ * `2014 ARM/ASM Meeting, Py-ART tutorial `_ @@ -183,7 +185,7 @@ environment based on the `environment.yml `_ - -* `CyLP `_ or - `PyGLPK `_ or - `CVXOPT `_ and their dependencies. - -* `Cartopy `_ or -* `Basemap `_ But Cartopy is recommended as - basemap will no longer have support. - -* `xarray `_ -* `pyproj `_ - -* `pytest `_ - -Obtaining the latest source -=========================== - -The latest source code for Py-ART can be obtained from the GitHub repository, -https://github.com/ARM-DOE/pyart. - -The latest source can be checked out using - -:: - - $ git clone https://github.com/ARM-DOE/pyart.git - - -Installing from Source -====================== - -The path to the TRMM RSL library must be provided during install. This can -either be done by setting the ``RSL_PATH`` environmentation variable. In bash -this can be done using ``export RSL_PATH=/path/to/rsl/``. If this location is -not specified, some common locations will be searched. Note that the location -provided should be the root TRMM RSL path, under which both a `lib` and -`include` directory are contained, the default location is ``/lib/local/trmm``. -If using CyLP, a path for the coincbc directory is needed. This can be done -using ``export COIN_INSTALL_DIR=/path/to/coincbc/``. When using CyLP, on some -systems, installing the Anaconda compilers is needed. These can be found here: -https://docs.conda.io/projects/conda-build/en/latest/resources/compiler-tools.html - -After specifying the TRMM RSL path Py-ART can be installed globally using - -:: - - $ python setup.py install - -of locally using - -:: - - $ python setup.py install --user - -If you prefer to use Py-ART without installing, simply add the this path to -your ``PYTHONPATH`` (directory or with a .pth file) and compile the extension -in-place. - -:: - - $ python setup.py build_ext -i - -You can also install Py-ART in development mode by using - -:: - - $ pip install -e . - -Frequently asked questions -========================== - -* I'm getting a no 'io' module after installing pyart with pip. - - There is a pyart on pip that is a different package. Make sure to do:: - - pip install arm_pyart - - and not:: - - pip install pyart - -* I'm getting a segfault or compile error with CyLP in newer Python versions - when installing in an environment. - - Anaconda has its own compilers now on conda-forge. Theres can be found here: - https://docs.conda.io/projects/conda-build/en/latest/resources/compiler-tools.html - Once the proper compilers are installed, reinstall CyLP. - -* I'm getting a segfault or another error in python when using - ``pyart.io.read_rsl()`` with IRIS/other files. - - This is due to a bug in RSL, and can be remedied by adding - ``-fno-stack-protector -D_FORTIFY_SOURCE=0`` to the CFLAGS parameter of the - makefile of RSL. This issue has been fixed with the release of rsl-v1.44. - -* I'm having trouble getting PyGLPK to compile on my 64-bit operating system. - - Change the line in the setup.py file from - - :: - - define_macros = macros, extra_compile_args=['-m32'], extra_link_args=['-m32'], - - to - - :: - - define_macros = macros, extra_compile_args=['-m64'], extra_link_args=['-m64'], - - Then build and install PyGLPK as recommended in the PYGLPK README.txt file. - -* When running basemap, I get an error 'KeyError: PROJ_LIB'. - - Basemap is not being supported beyond 2020, some of these errors relate - to it not playing nicely with newer versions of packages. We recommend using - Cartopy instead, but some users have been able to use: - import os - os.environ['PROJ_LIB'] = 'C:/Users/xx Username xxx/Anaconda3/Lib/site-packages/mpl_toolkits/basemap' - To get basemap working, but again Cartopy should be used instead of Basemap. +.. include:: ../../../INSTALL.rst diff --git a/doc/source/userguide/contributors_guide.rst b/doc/source/userguide/contributors_guide.rst index 219af44e08..b1cd2f37dc 100644 --- a/doc/source/userguide/contributors_guide.rst +++ b/doc/source/userguide/contributors_guide.rst @@ -1,428 +1 @@ -Contributor's Guide -=================== - - -The Python ARM Radar Toolkit (Py-ART) -------------------------------------- - -The Python ARM Radar Toolkit, Py-ART, is an open source Python module -containing a growing collection of weather radar algorithms and utilities -build on top of the Scientific Python stack and distributed under the -3-Clause BSD license. Py-ART is used by the -`Atmospheric Radiation Measurement (ARM) Climate Research Facility -`_ for working with data from a number of precipitation -and cloud radars, but has been designed so that it can be used by others in -the radar and atmospheric communities to examine, processes, and analyze -data from many types of weather radars. - - -Important Links ---------------- - -- Official source code repository: https://github.com/ARM-DOE/pyart -- HTML documentation: https://arm-doe.github.io/pyart -- Examples: https://arm-doe.github.io/pyart/examples/ -- Mailing List: http://groups.google.com/group/pyart-users/ -- Issue Tracker: https://github.com/ARM-DOE/pyart/issues - - -Citing ------- - -If you use the Python ARM Radar Toolkit (Py-ART) to prepare a publication -please cite: - - Helmus, J.J. & Collis, S.M., (2016). The Python ARM Radar Toolkit - (Py-ART), a Library for Working with Weather Radar Data in the Python - Programming Language. Journal of Open Research Software. 4(1), p.e25. - DOI: http://doi.org/10.5334/jors.119 - -Py-ART implements many published scientific methods which should *also* be -cited if you make use of them. Refer to the **References** section in the -documentation of the functions used for information on these citations. - - -Install -------- - -The easiest method for installing Py-ART is to use the conda packages from -the latest release. To do this you must download and install -`Anaconda `_ or -`Miniconda `_. -Then use the following command in a terminal or command prompt to install -the latest version of Py-ART:: - - conda install -c conda-forge arm_pyart - -To update an older version of Py-ART to the latest release use:: - - conda update -c conda-forge arm_pyart - - -Resources ---------- - -Pyart: - -- https://github.com/openradar/AMS-Short-Course-on-Open-Source-Radar-Software -- https://github.com/EVS-ATMOS/pyart_short_course -- https://www.youtube.com/watch?v=diiP-Q3bKZw -- http://arm-doe.github.io/pyart/dev/auto_examples/index.html - -Git: - -- https://git-scm.com/book/en/v2 - - -Code Style ----------- - -Py-ART follows pep8 coding standards. To make sure your code follows the -pep8 style, you can use a variety of tools that can check for you. Two -popular pep8 check modules are pycodestyle and pylint. - -For more on pep8 style: - -- https://www.python.org/dev/peps/pep-0008/ - -To install pycodestyle:: - - conda install pycodestyle - -To use pycodestyle:: - - pycodestyle filename - -To install pylint:: - - conda install pylint - -To get a detailed pylint report:: - - pylint filename - -If you want to just see what line number and the issue, just use:: - - pylint -r n filename - -Both of these tools are highly configurable to suit a user's taste. Refer to -the tools documentation for details on this process. - -- https://pycodestyle.readthedocs.io/en/latest/ -- https://www.pylint.org/ - - -Python File Setup ------------------ - -In a new .py file, the top of the code should have a brief introduction to -the module. - -An example: - -.. code-block:: python - - """ - Retrieval of VADs from a radar object. - - """ - -Following the introduction code, modules are then added. To follow pep8 -standards, modules should be added in the order of: - - 1. Standard library imports. - 2. Related third party imports. - 3. Local application/library specific imports. - -For example: - -.. code-block:: python - - import glob - import os - - import numpy as np - import numpy.ma as ma - from scipy.interpolate import interp1d - - from ..core import HorizontalWindProfile - -Following the main function def line, but before the code within it, a doc -string is needed to explain arguments, returns, references if needed, and -other helpful information. These documentation standards follow the NumPy -documentation style. - -For more on the NumPy documentation style: - -- https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt - -An example: - -.. code-block:: python - - def velocity_azimuth_display( - radar, velocity=None, z_want=None, valid_ray_min=16, - gatefilter=False, window=2): - - """ - Velocity azimuth display. - - Parameters - ---------- - radar : Radar - Radar object used. - velocity : string - Velocity field to use for VAD calculation. - If None, the default velocity field will be used. - - Other Parameters - ---------------- - z_want : array - Height array user would like for the VAD - calculation. None will result in a z_want of - np.linspace and use of _inverse_dist_squared - and _Average1D functions. Note, height must have - same shape as expected u_wind and v_wind if user - provides z_want. - valid_ray_min : int - Amount of rays required to include that level in - the VAD calculation. - gatefilter : GateFilter - Used to correct the velocity field before its use - in the VAD calculation. Uses Py-ART's region dealiaser. - window : int - Value to use for window calculation in _Averag1D - function. - - Returns - ------- - height : array - Heights in meters above sea level at which horizontal - winds were sampled. - speed : array - Horizontal wind speed in meters per second at each height. - direction : array - Horizontal wind direction in degrees at each height. - u_wind : array - U-wind mean in meters per second. - v_wind : array - V-wind mean in meters per second. - - Reference - ---------- - K. A. Browning and R. Wexler, 1968: The Determination - of Kinematic Properties of a Wind Field Using Doppler - Radar. J. Appl. Meteor., 7, 105–113 - - """ - -As seen, each argument has what type of object it is, an explanation of -what it is, mention of units, and if an argument has a default value, a -statement of what that default value is and why. - -Private or smaller functions and classes can have a single line explanation. - -An example: - -.. code-block:: python - - def u_wind(self): - """ U component of horizontal wind in meters per second. """ - - -Testing -------- - -When adding a new function to pyart it is important to add your function to -the __init__.py file under the corresponding pyart folder. - -Create a test for your function and have assert from numpy testing test the -known values to the calculated values. If changes are made in the future to -pyart, pytest will use the test created to see if the function is still valid and -produces the same values. It works that, it takes known values that are -obtained from the function, and when pytest is ran, it takes the test -function and reruns the function and compares the results to the original. - -An example: - -.. code-block:: python - - def test_vad(): - test_radar = pyart.testing.make_target_radar() - height = np.arange(0, 1000, 200) - speed = np.ones_like(height) * 5 - direction = np.array([0, 90, 180, 270, 45]) - profile = pyart.core.HorizontalWindProfile( - height, speed, direction) - sim_vel = pyart.util.simulated_vel_from_profile( - test_radar, profile) - - test_radar.add_field('velocity', sim_vel, - replace_existing=True) - - velocity = 'velocity' - z_start = 0 - z_end = 10 - z_count = 5 - - vad_height = ([0., 2.5, 5., 7.5, 10.]) - vad_speed = ([4.98665725, 4.94020686, 4.88107152, - 4.81939374, 4.75851962]) - vad_direction = ([359.84659496, 359.30240553, 358.58658589, - 357.81073051, 357.01353486]) - u_wind = ([0.01335138, 0.06014712, 0.12039762, - 0.18410404, 0.24791911]) - v_wind = ([-4.98663937, -4.9398407, -4.87958641, - -4.81587601, -4.75205693]) - - vad = pyart.retrieve.velocity_azimuth_display(test_radar, - velocity, - z_start, z_end, - z_count) - - assert_almost_equal(vad.height, vad_height, 3) - assert_almost_equal(vad.speed, vad_speed, 3) - assert_almost_equal(vad.direction, vad_direction, 3) - assert_almost_equal(vad.u_wind, u_wind, 3) - assert_almost_equal(vad.v_wind, v_wind, 3) - -Pytest is used to run unit tests in pyart. - -It is recommended to install pyart in “editable” mode for pytest testing. -From within the main pyart directory:: - - pip install -e . - -This lets you change your source code and rerun tests at will. - -To install pytest:: - - conda install pytest - -To run all tests in pyart with pytest from outside the pyart directory:: - - pytest --pyargs pyart - -All test with increase verbosity:: - - pytest -v - -Just one file:: - - pytest filename - -Note: When an example shows filename as such:: - - pytest filename - -filename is the filename and location, such as:: - - pytest /home/user/pyart/pyart/io/tests/test_cfradial.py - -Relative paths can also be used:: - - cd pyart - pytest ./pyart/retrieve/tests/test_vad.py - -For more on pytest: - -- https://docs.pytest.org/en/latest/ - - -GitHub ------- - -When contributing to pyart, the changes created should be in a new branch -under your forked repository. Let's say the user is adding a new map display. -Instead of creating that new function in your master branch. Create a new -branch called ‘cartopy_map’. If everything checks out and the admin -accepts the pull request, you can then merge the master branch and -cartopy_map branch. - -To delete a branch both locally and remotely, if done with it:: - - git push origin --delete - git branch -d - -or in this case:: - - git push origin --delete cartopy_map - git branch -d cartopy_map - - -To create a new branch:: - - git checkout -b - -If you have a branch with changes that have not been added to a pull request -but you would like to start a new branch with a different task in mind. It -is recommended that your new branch is based on your master. First:: - - git checkout master - -Then:: - - git checkout -b - -This way, your new branch is not a combination of your other task branch and -the new task branch, but is based on the original master branch. - -Typing `git status` will not only inform the user of what files have been -modified and untracked, it will also inform the user of which branch they -are currently on. - -To switch between branches, simply type:: - - git checkout - -When commiting to GitHub, start the statement with a acronym such as -‘ADD:’ depending on what your commiting, could be ‘MAINT:’ or -‘BUG:’ or more. Then following should be a short statement such as -“ADD: Adding cartopy map display.”, but after the short statement, before -finishing the quotations, hit enter and in your terminal you can then type -a more in depth description on what your commiting. - -A set of recommended acronymns can be found at: - -- https://docs.scipy.org/doc/numpy/dev/gitwash/development_workflow.html - -If you would like to type your commit in the terminal and skip the default -editor:: - - git commit -m "STY: Removing whitespace from vad.py pep8." - -To use the default editor(in Linux, usually VIM), simply type:: - - git commit - -One thing to keep in mind is before doing a pull request, update your -branches with the original upstream repository. - -This could be done by:: - - git fetch upstream - -After fetching, a git merge is needed to pull in the changes. - -This is done by:: - - git merge upstream/master - -To prevent a merge commit:: - - git merge --ff-only upstream/master - -After creating a pull request through GitHub, two outside checkers, -Appveyor and TravisCI will determine if the code past all checks. If the -code fails either tests, as the pull request sits, make changes to fix the -code and when pushed to GitHub, the pull request will automatically update -and TravisCI and Appveyor will automatically rerun. - -Blog Posts ----------- - -You can also contribute by adding blog posts. To get started with -blog posts, check out the blog post notebook template in the -`doc/source/blog_posts/` directory. Move the blog post to a -directory with the corresponding year (ex. `2022`), and follow the -contribution process outlined above. +.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/userguide/setting_up_an_environment.rst b/doc/source/userguide/setting_up_an_environment.rst index 814d32ab14..0fbb90804e 100644 --- a/doc/source/userguide/setting_up_an_environment.rst +++ b/doc/source/userguide/setting_up_an_environment.rst @@ -73,7 +73,7 @@ if you want Jupyter Notebook to run in that enviroment with those packages:: while that environment is activated. Another way to create a conda environment is by doing it from scratch using the conda create command. An example of this:: - conda create -n pyart_env -c conda-forge python=3.6 arm_pyart netCDF4 + conda create -n pyart_env -c conda-forge arm_pyart netCDF4 cartopy scipy numpy matplotlib This will also create an environment called pyart_env that can be activate the