Skip to content

Update pycmap_match_cruise_track_datasets.rst #67

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MSchatzUW wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update pycmap_match_cruise_track_datasets.rst #67

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
67ef587
Update pycmap_match_cruise_track_datasets.rst
MSchatzUW May 20, 2020
f7d2630
Update pycmap_match_cruise_track_datasets.rst
MSchatzUW May 28, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions ..._guide/API_ref/pycmap_api/data_retrieval/pycmap_match_cruise_track_datasets.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@

.. _seaflow dataset: https://cmap.readthedocs.io/en/latest/catalog/datasets/SeaFlow.html#seaflow
.. _SeaFlow dataset: https://cmap.readthedocs.io/en/latest/catalog/datasets/SeaFlow.html#seaflow
.. _Pisces model: https://cmap.readthedocs.io/en/latest/catalog/datasets/Pisces.html#pisces
.. _dataset page: https://cmap.readthedocs.io/en/latest/catalog/datasets/Pisces.html#pisces
.. _`Cruises()`: https://cmap.readthedocs.io/en/latest/user_guide/API_ref/pycmap_api/data_retrieval/pycmap_list_cruises.html
Expand Down Expand Up @@ -32,7 +32,7 @@ Match (colocalize) Cruise Track with Datasets
**cruise: string**
The official cruise name. If applicable, you may also use cruise "nickname" ('Diel', 'Gradients_1' ...). A full list of cruise names can be retrieved using `Cruises()`_ method.
**targetTables: list of string**
Table names of the target datasets to be matched with the source data. Notice source dataset can be matched with multiple target datasets. A full list of table names can be found in the :ref:`Catalog`.
Table names of the target datasets to be matched with the source data. Note source dataset can be matched with multiple target datasets. A full list of table names can be found in the :ref:`Catalog`.
**targetVars: list of string**
Variable short names to be matched with the source variable. A full list of variable short names can be found in the :ref:`Catalog`.
**depth1: float**
Expand All @@ -41,11 +41,11 @@ Match (colocalize) Cruise Track with Datasets
End depth [m]. This parameter sets the upper bound of the depth cut on the target datasets. Note depth is a positive number (depth is 0 at the surface and increases towards the ocean floor).

**temporalTolerance: list of int**
Temporal tolerance values between the cruise trajectory and target datasets. The size and order of values in this list should match those of targetTables. If only a single integer value is given, that would be applied to all target datasets. This parameter is in days except when the target variable represents monthly climatology data in which case it is in months. Notice fractional values are not supported in the current version.
Temporal tolerance values between the cruise trajectory and target datasets. The size and order of values in this list should match those of targetTables. If only a single integer value is given, that would be applied to all target datasets. This parameter is in days except when the target variable represents monthly climatology data in which case it is in months. Note fractional values are not supported in the current version.
**latTolerance: list of float or int**
Spatial tolerance values in meridional direction [deg] between the cruise trajectory and target datasets. The size and order of values in this list should match those of targetTables. If only a single float value is given, that would be applied to all target datasets. A "safe" value for this parameter can be slightly larger than the half of the target variable's spatial resolution.
Spatial tolerance values in meridional direction [deg] between the cruise trajectory and target datasets. The size and order of values in this list should match those of targetTables. If only a single float value is given, that would be applied to all target datasets. A "safe" value for this parameter can be slightly larger than half of the target variable's spatial resolution.
**lonTolerance: list of float or int**
Spatial tolerance values in zonal direction [deg] between the cruise trajectory and target datasets. The size and order of values in this list should match those of targetTables. If only a single float value is given, that would be applied to all target datasets. A "safe" value for this parameter can be slightly larger than the half of the target variable's spatial resolution.
Spatial tolerance values in zonal direction [deg] between the cruise trajectory and target datasets. The size and order of values in this list should match those of targetTables. If only a single float value is given, that would be applied to all target datasets. A "safe" value for this parameter can be slightly larger than half of the target variable's spatial resolution.
**depthTolerance: list of float or int**
Spatial tolerance values in vertical direction [m] between the cruise trajectory and target datasets. The size and order of values in this list should match those of targetTables. If only a single float value is given, that would be applied to all target datasets.

Expand All @@ -55,47 +55,46 @@ Match (colocalize) Cruise Track with Datasets
|


Example 1:
Example 1
----------

This example demonstrates how to colocalize the "Diel" cruise (official name: KM1513) with 2 target variables (lines 8-9):

- 'synecho_abundance' from underway `seaflow dataset`_
- 'synecho_abundance' from underway `SeaFlow dataset`_
- 'NO3' from `Pisces model`_

The last few lines of code (lines 21-24), plot the colocalized synecho_abundance versus NO3 concentration.
|

**Tip1:**
**Tip1**

The official name of this cruise is 'KM1513'. One can use the unofficial name, 'diel', instead (line 7).

**Tip2:**
**Tip2**

A full list of cruise expeditions can be retrieved using the `Cruises()`_ method.

**Tip3:**
**Tip3**

The temporalTolerance parameter is set to [0, 4] (line 12). This means:

- ±0 day temporal tolerance when matching with 'synecho_abundance' (exact date-time matching)
- ±4 day temporal tolerance when matching with 'NO3' (Pisces is a weekly averaged dataset)

**Tip4:**
**Tip4**

The latTolerance and lonTolerance parameters are set to [0, 0.25] (lines 13-14). This means:

- ±0 degree spatial tolerances (in meridional and zonal directions) when matching with 'synecho_abundance' (exact lat/lon matching).
- ±0.25 degrees spatial tolerances (in meridional and zonal directions) when matching with 'NO3'. This dataset has 0.25 degree spatial resolution which means one may reduce the spatial tolerance for this target dataset down to 0.25/2 = 0.125 degrees.

**Tip5:**
**Tip5**

The depthTolerance parameter is set to [5, 5] (line 20). This means:
- ±5 meters vertical tolerances when matching with 'synecho_abundance'
- ±5 meters vertical tolerances when matching with 'NO3'.

Note that the Pisces dataset has several depth levels between surface and 5 m. The spacing
between the depth levels is not have uniform.
between the depth levels is not uniform.



Expand Down Expand Up @@ -127,18 +126,19 @@ between the depth levels is not have uniform.
plt.show()


Example 2:

Example 2
----------

Imagine you would like to colocalize a 'large' number of variables along the track of multiple cruises. Hard-coding the variable names, table names, and tolerance parameters (as shown in Example 1) is an error-prone process. This example show an alternative approach to implement multi-variable colocalization.

Here, we colocalize two open-ocean North-Pacific transect cruises ('KOK1606' [gradient1], 'MGL1704' [gradient2]) with 14 variables from satellite datasets, model outputs, underway cruise measurements, and World-Ocean-Atlas climatology dataset. A full list of variables can be retrieved using the get_catalog() command (COMMENT: Make get_catalog() a hyperlink). Also, please review the tips mentioned Example 1 since they are generally relevant to this example. It takes a few minutes to run this script since we are colocalizing two long cruises with multiple target variables. Reduce the number of cruises (line 12), and/or number of target variables (lines 19-36) to save time.
Here, we colocalize two open-ocean North-Pacific transect cruises ('KOK1606' [gradient1], 'MGL1704' [gradient2]) with 14 variables from satellite datasets, model outputs, underway cruise measurements, and World-Ocean-Atlas climatology dataset. A full list of variables can be retrieved using the get_catalog() command . Also, please review the tips mentioned Example 1 since they are relevant to this example. It takes a few minutes to run this script since we are colocalizing two long cruises with multiple target variables. Reduce the number of cruises (line 12), and/or number of target variables (lines 19-36) to save time.

As a simple show case, the colocalized synechococcus abundance is plotted against latitude and is compared with phosphaste concentration from World Ocean Atlas monthly climatology dataset (line 91). The full colocalized dataset is stored in a csv file on local machine.

|

**Tip:**
**Tip**

Once the colocalization is finished, you may add new "calculated"
columns to the final dataframe:
Expand Down Expand Up @@ -273,7 +273,7 @@ Here is how to achieve the same results using a direct SQL statement. Please ref
'lonTolerance',
'depthTolerance'

**Example:**
**Example**

.. code-block:: sql

Expand Down