diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..501e5de --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,49 @@ +Contribution Guide +======================= + +Contributions to ``pycoare`` of all forms are welcome! + +Please follow these guidelines for contributing to this project: + +* `Fork the pycoare repository into your local GitHub repository `_ +* Clone your forked repository to your local machine + +.. code-block:: bash + + $ git clone + $ cd coare + +* Install the development requirements in a new environment + +.. code-block:: bash + + $ conda create -n pycoare + $ conda activate pycoare + $ pip install -r requirements-dev.txt + +* Create a new branch for your feature + +.. code-block:: bash + + $ git checkout -b my-new-feature + +* Install the pre-commit hooks for code formatting + +.. code-block:: bash + + $ pre-commit install + +* Make your changes and commit them + +.. code-block:: bash + + $ git commit -am 'Add some feature' + +* Push to the branch + +.. code-block:: bash + + $ git push origin my-new-feature + +* Create a new Pull Request on GitHub (a good title and description are helpful!) +* A maintainer will review your changes and merge them into the main branch! diff --git a/docs/index.rst b/docs/index.rst index 2f5b5bf..3813029 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,3 +34,7 @@ For more information on the people and publications that developed the COARE alg c35_api util_api + +.. toctree:: + + contributing diff --git a/docs/usage.rst b/docs/usage.rst index 11b97ba..8998095 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,20 +1,15 @@ Usage ===== -.. _Usage: - -.. |fairall2003| replace:: COARE 3.0 code -.. _fairall2003: https://doi.org/10.1175/1520-0442(2003)016<0571:BPOASF>2.0.CO;2 -.. |edson2013| replace:: CLIMODE, MBL and CBLAST experiments -.. _edson2013: https://doi.org/10.1175/JPO-D-12-0173.1 - -The COARE v3.5 algorithm is based on the |fairall2003|_ with modifications from the results of the |edson2013|_. +This package is designed around an object oriented approach, since the number of parameters that the COARE algorithm outputs can be quite unwieldy otherwise. +Therefore, the first step in using the COARE algorithm is to create an instance of the ``coare_35`` class: -.. attention:: + >>> from pycoare import coare_35 # import the coare_35 class + >>> c = coare_35([0.0, 0.5, 1.0, 1.5, 2.0, 2.5]) # create instance of coare_35 class - Default values are included for the optional parameters (i.e., other than wind speed), but it is better to use available data for as many variables as possible. - If you must use a single measurement for any of the variables, try to use averages that are representative of the region of interest. - `See the API for more details `_. +Note that this (and other examples in this documentation) uses *only* wind speed as input. +This is bad practice, and ideally you should use as many input variables as possible. +See :class:`~pycoare.coare_35` for a complete list of input variables. .. note:: @@ -22,35 +17,38 @@ The COARE v3.5 algorithm is based on the |fairall2003|_ with modifications from It is not yet designed to work with ``xarray`` objects (support coming soon). Please convert any ``xarray.DataArray`` to ``numpy.ndarray`` using the ``.values`` attribute before passing them to the COARE algorithm. -This package is designed around an object oriented approach, since the number of parameters that the COARE algorithm outputs can be quite unwieldy otherwise. -Therefore, the first step in using the COARE algorithm is to create an instance of the ``coare_35`` class. -This instance takes wind speed as the primary argument, but can (and likely should) also take a myriad of additional parameters as keyword arguments. -Here we show an example of how to use the COARE algorithm with only wind speed as input: - - >>> from pycoare import coare_35 # import the coare_35 class - >>> c = coare_35([0.0, 0.5, 1.0, 1.5, 2.0, 2.5]) # create instance of coare_35 class - Once the ``coare_35`` object is created, the algorithm will automatically be ran. -The output of the algorithm is stored in several subclasses, which can be accessed as attributes from the ``coare_35`` class. -These subclasses should only ever be accessed from within a ``coare_35`` instance (as shown in the examples below). -These classes contain "subattributes" that store the output of the algorithm, neatly divided into categories. +The output of the algorithm is stored in several "output classes", which can be accessed as attributes from the ``coare_35`` class. +Output classes contain "subattributes" that store the output of the algorithm, neatly divided into categories. -For example, the ``fluxes`` attribute contains the output of the algorithm related to air-sea fluxes. -To access the wind stress (i.e. the air-sea momentum flux), the you can use the ``tau`` subattribute of the ``fluxes`` attribute of the ``coare_35`` object: +For example, the ``fluxes`` output class contains the output of the algorithm related to air-sea fluxes. +To access the wind stress (i.e. the air-sea momentum flux), you can use the ``tau`` subattribute of the ``fluxes`` attribute of the ``coare_35`` object: >>> from pycoare import coare_35 - >>> c = coare_35([0.0, 0.5, 1.0, 1.5, 2.0, 2.5]) # same as above example, algorithm is run only once + >>> c = coare_35([0.0, 0.5, 1.0, 1.5, 2.0, 2.5]) # create instance of coare_35 class >>> c.fluxes.tau # access the wind stress array([0. , 0.00060093, 0.00165957, 0.00319516, 0.00520412, 0.00768739]) -As another example, the ``transfer_coefficients`` attribute contains the output of the algorithm related, unsurprisingly, to transfer coefficients. +.. important:: + + These "output classes" should only ever be accessed from within a ``coare_35`` instance (as shown in the examples). + +As another example, the ``transfer_coefficients`` output class contains the output of the algorithm related, unsurprisingly, to transfer coefficients. To access the neutral wind stress transfer coefficient (i.e., neutral drag coefficient), you can use the ``cdn_rf`` subattribute of the ``transfer_coffiencient`` attribute of the ``coare_35`` object: >>> from pycoare import coare_35 - >>> c = coare_35([0.0, 0.5, 1.0, 1.5, 2.0, 2.5]) # same as above example, algorithm is run only once - >>> c.transfer_coefficients.cdn_rf # access the wind stress + >>> c = coare_35([0.0, 0.5, 1.0, 1.5, 2.0, 2.5]) # create instance of coare_35 class + >>> c.transfer_coefficients.cdn_rf # access the drag coefficient array([1.2360058 , 1.12526078, 1.04170881, 0.98860156, 0.95127555, 0.92438611]) -The available attribute classes accesseible from a ``coare_35`` instance are: -:class:`fluxes`, :class:`transfer_coefficients`, :class:`stability_functions`, :class:`velocities`, :class:`temperatures`, and :class:`humidities`. -A full list of the available subattributes and a brief description of them can be found in the complete `COARE v3.5 API documentation `_. +The available output classes accessible from a :class:`~pycoare.coare_35` instance are: + +* :class:`~pycoare.coare_35.fluxes` +* :class:`~pycoare.coare_35.transfer_coefficients` +* :class:`~pycoare.coare_35.stability_functions` +* :class:`~pycoare.coare_35.velocities` +* :class:`~pycoare.coare_35.temperatures` +* :class:`~pycoare.coare_35.humidities` + +The links above will take you to the documentation for each of these output classes. +This contains information on the subattributes that are available in each output class. diff --git a/pycoare/coare_35.py b/pycoare/coare_35.py index 8e5ef3e..01b5c18 100644 --- a/pycoare/coare_35.py +++ b/pycoare/coare_35.py @@ -21,6 +21,19 @@ class coare_35: """ + .. |fairall2003| replace:: COARE 3.0 code + .. _fairall2003: https://doi.org/10.1175/1520-0442(2003)016<0571:BPOASF>2.0.CO;2 + .. |edson2013| replace:: CLIMODE, MBL and CBLAST experiments + .. _edson2013: https://doi.org/10.1175/JPO-D-12-0173.1 + + The COARE v3.5 algorithm is based on the |fairall2003|_ with modifications from the results of the |edson2013|_. + + Usage example using only wind speed as an input (see note above):: + + from pycoare import coare_35 + # creating a coare_35 instance + c = coare_35([1]) + :param u: ocean surface wind speed (m/s) at height zu :type u: ArrayLike :param t: bulk air temperature (degC) at height zt