Skip to content

Commit

Permalink
Feature 172 documentation (#205)
Browse files Browse the repository at this point in the history 
* replaced incorrectly hard-coded path to data to reflect new location of data

* Issue #172 update and corrections

* #172 add sample hovmoeller plot

* #172 add difficulty index to toc

* #172 initial version of difficulty index doc

* #172 fixed formatting

* #172 update yaml file

* updating actions

* #172 content for difficulty index

* #172 new content for ECLV plot

* #172 added ECLV to toc

* #172 added references for ECLV

* fixed import, looks like some parts got accidentally removed

* replaced missing portion of import statements

* fixed import statement, looks like some of it was removed

* still missing some portion of import

* replace wind_rose_default.png with wind_rose_custom.png for plot_filename so it is consistent with the other plots' user instructions

* replaced name of output plot to reflect change of output plot name in the wind_rose_custom.yaml config file

* update the METPLOTPY_BASE to reflect changes made to base_plot.py in beta6

* added wind rose to toc

* #172 added files for wind rose documentation

* update the METPLOTPY_BASE to reflect changes to base_plot.py in beta6

* #172 missing instructions for csh

* #172 additional config file for User's Guide

* #172 missed one place to update the METPLOTPY_BASE

* updated METPLOTPY_BASE in test setup, allowing all tests to be run.

* updated imports to reflect changes made in beta6 to base_plot.py and fixed code that wasn't working

* Update unit_tests.yaml

adding the relative frequency, rank, and probability histogram tests.

* skip the image comparison tests, these are unreliable when run on different hosts/environments

* fixed incorrect syntax for skipping tests

* #172 add histogram to the toc

* #172 files needed for histogram documentation

* #172 updates to line plot documentation for users that downloaded the source code, rather than forking or cloning.  The base/root directory of the METplotpy package will be different

* #172 clean up repetitive text and reformat

* #172 replace METPLOTPY_SOURCE/METplotpy with METPLOTPY_BASE and update instructions to reflect this change

* #172 update config files to include the points_path (commented out) to be consistent with the other plots that have intermediate points and to be consistent with the instructions in the user documentation

* #172 added the points_path setting to the custom config

* #172 add points_path

* #172 updates to instructions, replacing METPLOTPY_SOURCE with METPLOTPY_BASE due to changes to base_plot.py

* #172 fix imports

* #172 updates to histogram_2d documentation

* #172 updates to hovmoeller path

* #172 updates to paths

* #172 update to path

* update path to read the docs

* add stat_input and points_path settings to config file to work for the user documentation

* updates to paths

* add config file and support to indicate where to put input data file and output data

* updates from another issue to fix histogram plots

* #172 added support to indicate where to store output plots

* skip image comparison tests, these fail in the Github actions container

* update with latest changes

* #172 try using metplotpy.plots instead of relative paths for imports

* Update unit_tests.yaml

troubleshooting histogram tests

* fix METPLOTPY_BASE

* change path to METPLOTPY_BASE, remove one level

* clean up imports

* clean up METPLOTPY_BASE paths

* uncomment remaining two histogram tests

* update reason for skip tests

* Added polar plot documentation with images

* added missing items to TOC

* added wind-rose plot to TOC

* Spelled ice correctly

* Removed incorrectly spelled file

* added terminating *

* added histogram to TOC

* #172 remove extraneous character

* #172 include path to the example_difficulty_index.py script

* #172 replace METPLOTPY_SOURCE with METPLOTPY_BASE

* #172 replace METPLOTPY_SOURCE with METPLOTPY_BASE

* #172 Replace METPLOTPY_BASE_DIR wieh METPLOTPY_BASE

* #172 replace METPLOTPY_SOURCE with METPLOTPY_BASE

* #172 replaced Polar Plot plot with Polar Ice plot and fixed some other rst syntax

* #170 fixed header for polar ice plot

* #172 removed redundant histogram entry in TOC

* #172 fixed title overline length to polar plot

* #172 update instructions for users that need to save output to another location

* #172 fixed name of the polar plot yaml name

* fixed path to config file

* #172 modify the command line to not specify another config file

* #172 update instruction on METPLOTPY_BASE

* #172 replace incorrect yaml name with correct one, polar_ice.yaml

* #172 modify instructions to change to WORKING_DIR and to run from that dir

* #172 fix formatting for code block

* #172 removed reference to a default config file and more clarification about what the polar_ice_plot.py plot is using for config

* #172 add entry for the points_path since dump_points is set to True in the default config file

* #172 added more explicit directions for replacing the METPLOTPY_BASE with the explicit path

Co-authored-by: Minna Win <[email protected]>
Co-authored-by: Hank Fisher <[email protected]>
  • Loading branch information
@bikegeek @hankenstein2
3 people authored Mar 11, 2022
1 parent a2435ef commit 3f630ea
Show file tree
Hide file tree
Showing 52 changed files with 1,658 additions and 293 deletions.
9 changes: 3 additions & 6 deletions .github/workflows/unit_tests.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,11 +95,8 @@ jobs:
cd ../wind_rose
pytest test_wind_rose.py
cd ../histogram
pytest test_prob_hist.py
pytest test_rank_hist.py
pytest test_rel_hist.py
pytest test_prob_hist.py
pytest test_rank_hist.py
pytest test_rel_hist.py

67 changes: 36 additions & 31 deletions docs/Users_Guide/bar.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,19 @@ ___________
The sample data used to create an example bar plot is available in the
METplotpy repository, where the bar plot tests are located:

*$METPLOTPY_SOURCE/METplotpy/metplotpy/test/bar/bar.data*
*$METPLOTPY_BASE/metplotpy/test/bar/bar.data*

*$METPLOTPY_SOURCE* is the directory where the METplotpy code is saved.
*$METPLOTPY_BASE* is the directory where the METplotpy code is saved.
The data is text output from MET in columnar format.

e.g.

*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository

or

*/usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of
the Github repository. The *x.y.z* is the release number.


Configuration Files
Expand All @@ -52,15 +60,12 @@ language". It is commonly used for configuration files and in applications
where data is being stored or transmitted. Two configuration files are
required. The first is a default configuration file, **bar_defaults.yaml**,
which is found in the
*$METPLOTPY_SOURCE/METplotpy/metplotpy/plots/config* directory. All default
*$METPLOTPY_BASE/metplotpy/plots/config* directory. All default
configuration files are located in the
*$METPLOTPY_SOURCE/METplotpy/metplotpy/plots/config* directory.
Default configuration files are automatically loaded by the plotting code
and do not need to be explicitly specified when generating a plot.
$METPLOTPY_SOURCE is the user-specified directory
where the METplotpy source code has been saved. **Default configuration
files are automatically loaded by the plotting code and do not
need to be explicitly specified when generating a plot**.
*$METPLOTPY_BASE/metplotpy/plots/config* directory. *$METPLOTPY_BASE* is base directory where the
METplotpy source code has been saved. **Default configuration files are
automatically loaded by the plotting code and do not need to be explicitly
specified when generating a plot**.

The second required configuration file is a user-supplied “custom”
configuration file. This file is used to customize/override the default
Expand Down Expand Up @@ -98,31 +103,31 @@ saved to the working directory:

.. code-block:: ini
cp $METPLOTPY_SOURCE/test/bar/custom_bar.yaml $WORKING_DIR/custom_bar.yaml
cp $METPLOTPY_BASE/test/bar/custom_bar.yaml $WORKING_DIR/custom_bar.yaml
Modify the *stat_input* setting in the
**$METPLOTPY_SOURCE/METplotpy/test/bar/custom_bar.yaml**
file to explicitly point to the $METPLOTPY_SOURCE/METPlotpy/test/bar
directory by replacing
the relative paths (e.g. *./bar.data*) with the full path (e.g.
*/yourdir/METplotpy/test/bar.data*). Modify the *plot_filename* setting
to explicitly point to the directory of the plot, using the full path,
including the name of the plot.
**$METPLOTPY_BASE/test/bar/custom_bar.yaml**
file to explicitly point to the $METPLOTPY_BASE/test/bar
directory by replacing the relative paths (e.g. *./bar.data*) with the full path
*$METPLOTPY_BASE/test/bar/bar.data* (including replacing *$METPLOTPY_BASE*
with the full path to the METplotpy installation on the system). Modify the
*plot_filename* setting to explicitly point to the directory of the plot,
using the full path, including the name of the plot.

For example:

*stat_input: /username/myworkspace/METplotpy/test/bar.data*

*plot_filename: /username/working_dir/output_plots/bar.png*

This is where */username/myworkspace/* is $METPLOTPY_SOURCE and
*/username/working_dir* is $WORKING_DIR. Make sure that the
This is where */username/myworkspace/METplotpy* corresponds to $METPLOTPY_BASE and
*/username/working_dir* corresponds to $WORKING_DIR. Make sure that the
$WORKING_DIR directory that is specifed exists and has the appropriate
read and write permissions.
The path listed for *plot_filename* may be changed to the output directory
of one’s choosing. If this is not set, then the *plot_filename* setting
specified in the
*$METPLOTPY_SOURCE/METplotpy/metplotpy/plots/config/bar_defaults.yaml*
*$METPLOTPY_BASE/metplotpy/plots/config/bar_defaults.yaml*
configuration file will be used.

To save the intermediate **.points1** file (used by METviewer and useful
Expand All @@ -139,10 +144,10 @@ the **.points1** file is saved.
If points_path is commented out (indicated by a '#' symbol in front of it),
remove the '#' symbol to uncomment
the points_path so that it will be used by the code. Make sure that this
directory exists and has the
appropriate read and write permissions. **NOTE**: the *points_path* setting
is **optional** and does not need to be defined in the configuration file
unless saving the intermediate **.points1** file is desired.
directory exists and has the appropriate read and write permissions.
**NOTE**: the *points_path* setting is **optional** and does not need to be
defined in the configuration file unless saving the intermediate **.points1**
file is desired.


Run from the Command Line
Expand All @@ -153,37 +158,37 @@ The **custom_bar.yaml** configuration file, in combination with the

.. image:: bar.png

Perform the following:
To generate the above bar plot, perform the following:

* If using the conda environment,
verify the conda environment is running and has has the required
Python packages outlined in the `requirements section
<https://metplotpy.readthedocs.io/en/latest/Users_Guide/installation.html#python-requirements>`_.

* Set the METPLOTPY_BASE environment variable to point to
*$METPLOTPY_SOURCE/METplotpy/metplotpy*
*$METPLOTPY_BASE*

For the ksh environment:

.. code-block:: ini
export METPLOTPY_BASE=$METPLOTPY_SOURCE/METplotpy/metplotpy
export METPLOTPY_BASE=$METPLOTPY_BASE
For the csh environment:

.. code-block:: ini
setenv METPLOTPY_BASE $METPLOTPY_SOURCE/METplotpy/metplotpy
setenv METPLOTPY_BASE $METPLOTPY_BASE
Replacing the $METPLOTPY_SOURCE with the directory where the METplotpy
Recall that $METPLOTPY_BASE is the directory path indicating where the METplotpy
source code was saved.


* Enter the following command:

.. code-block:: ini
python $METPLOTPY_SOURCE/METplotpy/metplotpy/plots/bar/bar.py $WORKING_DIR/custom_bar.yaml
python $METPLOTPY_BASE/metplotpy/plots/bar/bar.py $WORKING_DIR/custom_bar.yaml
* A **bar.png** output file will be created in the directory that was
specified in the *plot_filename* configuration setting in the
Expand Down
68 changes: 42 additions & 26 deletions docs/Users_Guide/box.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,14 +32,24 @@ Example
Sample Data
___________


The data is text output from MET in columnar format.
The sample data used to create an example box plot is available in the
METplotpy repository, where the box plot tests are located:

*$METPLOTPY_SOURCE/METplotpy/metplotpy/test/box/box.data*
*$METPLOTPY_BASE/metplotpy/test/box/box.data*

*$METPLOTPY_BASE* is the directory where the METplotpy code is saved

e.g.

*/usr/path/to/METplotpy* if the source code was cloned or forked from the Github repository

or

*/usr/path/to/METplotpy-x.y.z* if the source code was downloaded as a zip or gzip'd tar file from the Release link of
the Github repository. The *x.y.z* is the release number.

*$METPLOTPY_SOURCE* is the directory where the METplotpy code is saved
(e.g. */username/myworkspace*). The data is text output from MET in
columnar format.

Configuration Files
___________________
Expand All @@ -53,10 +63,10 @@ it is a "human-friendly data serialization language". It is commonly used for
configuration files and in applications where data is being stored or
transmitted. Two configuration files are required. The first is a default
configuration file, **box_defaults.yaml**, which is found in the
*$METPLOTPY_SOURCE/METplotpy/metplotpy/plots/config* directory. All default
*$METPLOTPY_BASE/metplotpy/plots/config* directory. All default
configuration files are located in the
*$METPLOTPY_SOURCE/METplotpy/metplotpy/plots/config* directory.
*$METPLOTPY_SOURCE* is the user-specified directory where the
*$METPLOTPY_BASE/metplotpy/plots/config* directory.
*$METPLOTPY_BASE* is the user-specified directory where the
METplotpy source code has been saved. **Default configuration files
are automatically loaded by the plotting code and do not need to be
explicitly specified when generating a plot**.
Expand Down Expand Up @@ -94,14 +104,16 @@ saved to the working directory:

.. code-block:: ini
cp $METPLOTPY_SOURCE/METplotpy/test/box/custom_box.yaml $WORKING_DIR/custom_box.yaml
cp $METPLOTPY_BASE/test/box/custom_box.yaml $WORKING_DIR/custom_box.yaml
Modify the *stat_input* setting in the
*$METPLOTPY_SOURCE/METplotpy/test/box/custom_box.yaml*
file to explicitly point to the *$METPLOTPY_SOURCE/METplotpy/test/box*
*$METPLOTPY_BASE/test/box/custom_box.yaml*
file to explicitly point to the *$METPLOTPY_BASE/test/box*
directory (where the custom config files and sample data reside).
Replace the relative path *./box.data*
with the full path *$METPLOTPY_SOURCE/METplotpy/test/box/box.data*.
with the full path *$METPLOTPY_BASE/test/box/box.data*
(including replacing *$METPLOTPY_BASE* with the full path to the METplotpy
installation on the system).
Modify the *plot_filename* setting to point to the output path where the
plot will be saved, including the name of the plot.

Expand All @@ -111,15 +123,15 @@ For example:

*plot_filename: /username/working_dir/output_plots/box.png*

This is where */username/myworkspace/* is *$METPLOTPY_SOURCE* and
This is where */username/myworkspace/METplotpy* is *$METPLOTPY_BASE* and
*/username/working_dir* is *$WORKING_DIR*. Make sure that the
*$WORKING_DIR* directory that is specified exists and has the appropriate
read and write permissions.

The path listed for *plot_filename* may be
changed to the output directory of one's choosing. If this is not set,
then the *plot_filename* setting specified in the
*$METPLOTPY_SOURCE/METplotpy/metplotpy/plots/config/box_defaults.yaml*
*$METPLOTPY_BASE/metplotpy/plots/config/box_defaults.yaml*
configuration file will be used.

To save the intermediate **.points1** file (used by METviewer and useful
Expand Down Expand Up @@ -159,17 +171,17 @@ Copy this file to the working directory:

.. code-block:: ini
cp $METPLOTPY_SOURCE/METplotpy/test/box/minimal_box.yaml $WORKING_DIR/minimal_box.yaml
cp $METPLOTPY_BASE/test/box/minimal_box.yaml $WORKING_DIR/minimal_box.yaml
Add the *stat_input* (input data) and *plot_filename* (output file/plot path)
settings to the **$WORKING_DIR/minimal_box.yaml**
file (anywhere below the comment block). The *stat_input* setting
explicitly indicates where the sample data and custom configuration
files are located. Set the *stat_input* to
*$METPLOTPY_SOURCE/METplotpy/test/box/box.data* and set the
*$METPLOTPY_BASE/test/box/box.data* and set the
*plot_filename* to **$WORKING_DIR/output_plots/box_default.png**:

*stat_input: $METPLOTPY_SOURCE/METplotpy/test/box/box.data*
*stat_input: $METPLOTPY_BASE/test/box/box.data*

*plot_filename: $WORKING_DIR/output_plots/box_default.png*

Expand All @@ -187,22 +199,28 @@ Run from the Command Line

Perform the following to generate the plots:

* If using the conda environment, verify the conda environment
is running and has the required
`Python packages
<https://metplotpy.readthedocs.io/en/latest/Users_Guide/installation.html#python-requirements>`_
outlined in the requirements section.

* Set the METPLOTPY_BASE environment variable to point to
*$METPLOTPY_SOURCE/METplotpy/metplotpy*.
*$METPLOTPY_BASE*.

For the ksh environment:

.. code-block:: ini
export METPLOTPY_BASE=$METPLOTPY_SOURCE/METplotpy/metplotpy
export METPLOTPY_BASE=$METPLOTPY_BASE
For the csh environment:

.. code-block:: ini
setenv METPLOTPY_BASE $METPLOTPY_SOURCE/METplotpy/metplotpy
setenv METPLOTPY_BASE $METPLOTPY_BASE
Replacing the *$METPLOTPY_SOURCE* with the directory where the
Recall that *$METPLOTPY_BASE* is the directory path indicating where the
METplotpy source code was saved.

The **custom_box.yaml** configuration file, in combination with the
Expand All @@ -214,11 +232,9 @@ Perform the following to generate the plots:
To generate the above plot using the **box_defaults.yaml** and
**custom_box.yaml** config files, perform the following:

* If the conda environment is being used, verify the conda environment
is running and has the required
`Python packages
<https://metplotpy.readthedocs.io/en/latest/Users_Guide/installation.html#python-requirements>`_
outlined in the requirements section.
.. code-block:: ini
python $METPLOTPY_BASE/metplotpy/plots/box/box.py $WORKING_DIR/custom_box.yaml
The **minimal_box.yaml** configuration file, in combination with the
**box_defaults.yaml** configuration file, generates a "default" box plot.
Expand All @@ -236,7 +252,7 @@ Perform the following to generate the plots:

.. code-block:: ini
python $METPLOTPY_SOURCE/METplotpy/metplotpy/plots/box/box.py $WORKING_DIR/minimal_box.yaml
python $METPLOTPY_BASE/metplotpy/plots/box/box.py $WORKING_DIR/minimal_box.yaml
* A **box_default.png** output file will be created in the
directory specified in the *plot_filename* configuration setting in
Expand Down
Loading

0 comments on commit 3f630ea

Please sign in to comment.