ocstrack 0.1.3.post1.dev0__tar.gz → 0.1.4.post0__tar.gz

ocstrack-0.1.4.post0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: ocstrack
+Version: 0.1.4.post0
+Summary: Satellite data download, crop, and collocation with model outputs
+Author-email: Felicio Cassalho <felicio.cassalho@noaa.gov>
+License: MIT
+Project-URL: Homepage, https://github.com/noaa-ocs-modeling/OCSTrack
+Project-URL: Repository, https://github.com/noaa-ocs-modeling/OCSTrack
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: xarray
+Requires-Dist: scipy
+Requires-Dist: tqdm
+Requires-Dist: requests
+Requires-Dist: netcdf4
+Requires-Dist: h5netcdf
+Requires-Dist: dask
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Dynamic: license-file
+
+# OCSTrack
+OCSTrack is an object-oriented Python package for the along-track collocation of satellite (2D) and ArgoFloat (3D) data with ocean circulation and wave model outputs.
+It simplifies the process of aligning diverse datasets, making it easier to compare and analyze satellite observations against model simulations.
+
+## Key Features
+### Satellite Altimetry Data Support
+
+Seamlessly integrates with NOAA [CoastalWatch](https://coastwatch.noaa.gov/cwn/products/along-track-significant-wave-height-wind-speed-and-sea-level-anomaly-multiple-altimeters.html) altimetry data, providing access to a wide range of missions:
+ * Jason-2
+ * Jason-3
+ * Sentinel-3A
+ * Sentinel-3B
+ * Sentinel-6A
+ * CryoSat-2
+ * SARAL
+ * SWOT
+
+
+ ### Satellite Altimetry Data Support
+
+It also integrates the Euro Argo dataset [ifremmer](https://fleetmonitoring.euro-argo.eu/dashboard?Status=Active&Country=France) for 3D temperature and salinity collocation.
+
+### Ocean Model Data Support
+ Supports outputs from various ocean circulation and wave models:
+ * [SCHISM](https://github.com/schism-dev/schism) and its coupled verison with WWMIII
+ * [ADCIRC+SWAN](https://adcirc.org/)
+ * WaveWatch3 (to be implemented)
+
+
+## Installation
+
+1.  **Create new conda environment:**
+    This command creates an environment named `ocstrack` and installs all dependencies from `conda-forge`.
+    ```bash
+    conda create -n ocstrack -c conda-forge python=3.10 numpy xarray scipy tqdm requests netcdf4 h5netcdf dask
+    conda activate ocstrack
+    ```
+
+2.  **Install `ocstrack`:**
+    Finally, install this package using `pip`.
+    ```bash
+    pip install ocstrack
+    ```
+
+    If you want to install the latest dev version, using this instead:
+    ```bash
+    pip install "git+[https://github.com/noaa-ocs-modeling/OCSTrack.git](https://github.com/noaa-ocs-modeling/OCSTrack.git)"
+    ```
+
+## Usage
+See examples directory.
+
+## Contributing
+We welcome contributions to OCSTrack! If you have ideas for improvements, new features, or find a bug, please don't hesitate to open an issue or submit a pull request on our GitHub repository. Your input helps make OCSTrack better for everyone.
+
+### Contact
+<sup>Contact: felicio.cassalho@noaa.gov </sup>
+
+![NOAA logo](https://user-images.githubusercontent.com/72229285/216712553-c1e4b2fa-4b6d-4eab-be0f-f7075b6151d1.png)
+
+
+#### Acknowledgements:
+*OCSTrack was inspired by the MATLAB-based [WW3-tools](https://github.com/NOAA-EMC/WW3-tools) and [wave-tools](https://github.com/erdc/wave-tools) collocation tools developed for WaveWatch3.*

ocstrack-0.1.4.post0/README.md

@@ -0,0 +1,63 @@
+# OCSTrack
+OCSTrack is an object-oriented Python package for the along-track collocation of satellite (2D) and ArgoFloat (3D) data with ocean circulation and wave model outputs.
+It simplifies the process of aligning diverse datasets, making it easier to compare and analyze satellite observations against model simulations.
+
+## Key Features
+### Satellite Altimetry Data Support
+
+Seamlessly integrates with NOAA [CoastalWatch](https://coastwatch.noaa.gov/cwn/products/along-track-significant-wave-height-wind-speed-and-sea-level-anomaly-multiple-altimeters.html) altimetry data, providing access to a wide range of missions:
+ * Jason-2
+ * Jason-3
+ * Sentinel-3A
+ * Sentinel-3B
+ * Sentinel-6A
+ * CryoSat-2
+ * SARAL
+ * SWOT
+
+
+ ### Satellite Altimetry Data Support
+
+It also integrates the Euro Argo dataset [ifremmer](https://fleetmonitoring.euro-argo.eu/dashboard?Status=Active&Country=France) for 3D temperature and salinity collocation.
+
+### Ocean Model Data Support
+ Supports outputs from various ocean circulation and wave models:
+ * [SCHISM](https://github.com/schism-dev/schism) and its coupled verison with WWMIII
+ * [ADCIRC+SWAN](https://adcirc.org/)
+ * WaveWatch3 (to be implemented)
+
+
+## Installation
+
+1.  **Create new conda environment:**
+    This command creates an environment named `ocstrack` and installs all dependencies from `conda-forge`.
+    ```bash
+    conda create -n ocstrack -c conda-forge python=3.10 numpy xarray scipy tqdm requests netcdf4 h5netcdf dask
+    conda activate ocstrack
+    ```
+
+2.  **Install `ocstrack`:**
+    Finally, install this package using `pip`.
+    ```bash
+    pip install ocstrack
+    ```
+
+    If you want to install the latest dev version, using this instead:
+    ```bash
+    pip install "git+[https://github.com/noaa-ocs-modeling/OCSTrack.git](https://github.com/noaa-ocs-modeling/OCSTrack.git)"
+    ```
+
+## Usage
+See examples directory.
+
+## Contributing
+We welcome contributions to OCSTrack! If you have ideas for improvements, new features, or find a bug, please don't hesitate to open an issue or submit a pull request on our GitHub repository. Your input helps make OCSTrack better for everyone.
+
+### Contact
+<sup>Contact: felicio.cassalho@noaa.gov </sup>
+
+![NOAA logo](https://user-images.githubusercontent.com/72229285/216712553-c1e4b2fa-4b6d-4eab-be0f-f7075b6151d1.png)
+
+
+#### Acknowledgements:
+*OCSTrack was inspired by the MATLAB-based [WW3-tools](https://github.com/NOAA-EMC/WW3-tools) and [wave-tools](https://github.com/erdc/wave-tools) collocation tools developed for WaveWatch3.*

ocstrack-0.1.4.post0/examples/ADCIRCSWAN_SatAlt.py

@@ -0,0 +1,63 @@
+import numpy as np
+from ocstrack.Model.model import ADCSWAN
+from ocstrack.Observation.satellite import SatelliteData
+from ocstrack.Observation import get_sat
+from ocstrack.Collocation.collocate import Collocate
+# from ocstrack.utils import convert_longitude
+
+
+# 1. Download Satellite Data
+  #  Specify your desired date range, list of satellites, output directory, and geographical bounding box.
+print("get_sat begin")
+get_sat.get_multi_sat(start_date="2020-12-13",
+                      end_date="2020-12-31",
+                      sat_list=['sentinel3a','sentinel3b','jason2','jason3','cryosat2','saral','swot','sentinel6a'],
+                      output_dir=r"Your/Path/where to save the sat altimetry/Here/",
+                      lat_min=7,
+                      lat_max=46,
+                      lon_min=-98,
+                      lon_max=-60,
+                     )
+print("get_sat end")
+
+print("load sat begin")
+# 2. Define File Paths
+#    Set the paths for your downloaded satellite data, model run, and where you want to save the collocated output.
+sat_path = r"Your/Path/to/Downloaded Satellite Data/Here/",
+model_path = r"Your/Path/to/ADCIRC+SWAN run dir/Here/",
+output_path =  r"Your/Path/Here/adcswn_collocated.nc",
+s_time,e_time = "2019-07-30", "2019-08-03"
+
+# 3. Load Satellite Data
+#    Initialize the SatelliteData object with your satellite data file.
+sat_data = SatelliteData(sat_path)
+#    It's crucial to ensure longitude conventions match between satellite and model data.
+#    Use convert_longitude if needed (mode=1 for converting to 0-360 degrees).
+# sat_data.lon = convert_longitude(sat_data.lon, mode=1)
+
+print("load model begin")
+# 4. Load Model Data
+#    Instantiate the SCHISM model object, specifying the run directory and model variable details.
+model_run = ADCSWAN(
+                    rundir=model_path,
+                    model_dict={'var': 'swan_HS',
+                                'startswith': 'swan_HS.63.nc',
+                                # 'var_type': '2D',
+                                'model': 'ADCSWAN'},
+                    start_date=np.datetime64(s_time),
+                    end_date=np.datetime64(e_time)
+                  )
+
+print("Collocation begin")
+# 5. Perform Collocation
+#    Create a Collocate object, providing the loaded model and satellite data.A 
+# dist_coast = xr.open_dataset(r'Your/Path/to/OPTIONAL/distFromCoast.nc')
+coll = Collocate(
+                 model_run=model_run,
+                 observation=sat_data,
+                #  dist_coast=dist_coast,
+                 n_nearest=3,
+                 # search_radius = 3000,
+                 temporal_interp=True
+                 )
+ds_coll = coll.run(output_path=output_path) # Execute the collocation and save the results

{ocstrack-0.1.3.post1.dev0 → ocstrack-0.1.4.post0}/examples/Plot_Collocated.ipynb

@@ -34,10 +34,10 @@
    "source": [
     "# Slice the file as you wish\n",
     "mask = (\n",
-    "    (collocated_data[\"sat_swh\"] <= 7.5) &\n",
-    "    (collocated_data[\"model_swh_weighted\"] <= 7.5) &\n",
-    "    (collocated_data[\"dist_coast\"] >= 100) &\n",
-    "    (collocated_data[\"dist_coast\"] >= 100) &\n",
+    "    (collocated_data[\"obs_swh\"] <= 7.5) &\n",
+    "    (collocated_data[\"model_sigWaveHeight_weighted\"] <= 7.5) &\n",
+    "    # (collocated_data[\"dist_coast\"] >= 100) &\n",
+    "    # (collocated_data[\"dist_coast\"] >= 100) &\n",
     "    (collocated_data[\"model_dpt\"] <=-100).all(dim=\"nearest_nodes\") &\n",
     "    # (abs(ds[\"time_deltas\"]) <= 1800) &\n",
     "    (collocated_data[\"dist_deltas\"] <= 0.05).all(dim=\"nearest_nodes\") \n",
@@ -53,14 +53,14 @@
    "outputs": [],
    "source": [
     "# Extract the model and the satellite data\n",
-    "x = collocated_data.sat_swh.values\n",
-    "y = collocated_data.model_swh_weighted.values #.model_swh.values.mean(axis=1)\n",
+    "x = collocated_data.obs_swh.values\n",
+    "y = collocated_data.model_sigWaveHeight_weighted.values #.model_swh.values.mean(axis=1)\n",
     "xy_max = y.max()"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 46,
+   "execution_count": null,
    "id": "1a62c4a6-f6dc-495c-aec6-be59496a85a2",
    "metadata": {},
    "outputs": [],
@@ -84,12 +84,12 @@
     "        \"vmin\": -5000, \"vmax\": 0,\n",
     "        \"cmap\": \"jet\"\n",
     "    },\n",
-    "    {\n",
-    "        \"z\": collocated_data.dist_coast.values,\n",
-    "        \"label\": \"Distance from the Coast (km)\",\n",
-    "        \"vmin\": 0, \"vmax\": 500,\n",
-    "        \"cmap\": \"jet_r\"\n",
-    "    } \n",
+    "    # {\n",
+    "    #     \"z\": collocated_data.dist_coast.values,\n",
+    "    #     \"label\": \"Distance from the Coast (km)\",\n",
+    "    #     \"vmin\": 0, \"vmax\": 500,\n",
+    "    #     \"cmap\": \"jet_r\"\n",
+    "    # } \n",
     "]"
    ]
   },
@@ -121,7 +121,7 @@
     }
    ],
    "source": [
-    "source_cats, source_codes = np.unique(collocated_data.source_sat.values, return_inverse=True)\n",
+    "source_cats, source_codes = np.unique(collocated_data.source_obs.values, return_inverse=True)\n",
     "cmap_cat = plt.get_cmap(\"tab10\")\n",
     "\n",
     "norm = mcolors.BoundaryNorm(boundaries=np.arange(-0.5, len(source_cats)+0.5), ncolors=len(source_cats))\n",

ocstrack-0.1.4.post0/examples/SCHISMWWM_SatAlt.py

@@ -0,0 +1,64 @@
+import numpy as np
+from ocstrack.Model.model import SCHISM
+from ocstrack.Observation.satellite import SatelliteData
+from ocstrack.Observation import get_sat
+from ocstrack.Collocation.collocate import Collocate
+from ocstrack.utils import convert_longitude
+
+
+# 1. Download Satellite Data
+#    Specify your desired date range, list of satellites, output directory, and geographical bounding box.
+print("get_sat begin")
+get_sat.get_multi_sat(start_date="2019-07-30",
+                      end_date="2019-08-04",
+                      sat_list=['sentinel3a','sentinel3b','jason2','jason3','cryosat2','saral','swot','sentinel6a'],
+                      output_dir=r"Your/Path/where to save the sat altimetry/Here/",
+                      lat_min=50,
+                      lat_max=59,
+                      lon_min=165,
+                      lon_max=-165,
+                     )
+print("get_sat end")
+
+print("load sat begin")
+# 2. Define File Paths
+#    Set the paths for your downloaded satellite data, model run, and where you want to save the collocated output.
+sat_path = r"Your/Path/to/Downloaded Satellite Data/Here/",
+model_path = r"Your/Path/to/SCHISM+WWM run dir/Here/",
+output_path =  r"Your/Path/Here/schism_collocated.nc",
+s_time,e_time = "2019-07-30", "2019-08-03"
+
+# 3. Load Satellite Data
+#    Initialize the SatelliteData object with your satellite data file.
+sat_data = SatelliteData(sat_path)
+#    It's crucial to ensure longitude conventions match between satellite and model data.
+#    Use convert_longitude if needed (mode=1 for converting to 0-360 degrees).
+sat_data.lon = convert_longitude(sat_data.lon, mode=1)
+
+print("load model begin")
+# 4. Load Model Data
+#    Instantiate the SCHISM model object, specifying the run directory and model variable details.
+model_run = SCHISM(
+                    rundir=model_path,
+                    model_dict={'var': 'sigWaveHeight',
+                                'startswith': 'out2d_', # File name prefix for 2D outputs
+                                'var_type': '2D',
+                                'model': 'SCHISM'},
+                    start_date=np.datetime64(s_time),
+                    end_date=np.datetime64(e_time)
+                  )
+
+print("coll begin")
+
+# 5. Perform Collocation
+#    Create a Collocate object, providing the loaded model and satellite data.
+# dist_coast = xr.open_dataset(r'Your/Path/to/OPTIONAL/distFromCoast.nc')
+coll = Collocate(
+                 model_run=model_run,
+                 observation=sat_data,
+                 n_nearest=3,
+                 # search_radius = 3000,
+                #  dist_coast=dist_coast,
+                 temporal_interp=True
+                 )
+ds_coll = coll.run(output_path=output_path) # Execute the collocation and save the results

ocstrack-0.1.4.post0/examples/SCHISM_ArgoFloat.py

@@ -0,0 +1,81 @@
+import numpy as np
+from ocstrack.Model.model import SCHISM
+from ocstrack.Observation.argofloat import ArgoData
+from ocstrack.Observation import get_argo
+from ocstrack.Collocation.collocate import Collocate
+from ocstrack.utils import convert_longitude
+
+
+# Download Argo Data
+# Specify your desired date range, region, output directory, and geographical bounding box.
+print("get_argo begin")
+get_argo.get_argo(start_date="2019-08-29",
+                      end_date="2019-10-05",
+                      region = "pacific_ocean",
+                      output_dir=r"Your/Path/where to save the sat altimetry/Here/",
+                      lat_min=50,
+                      lat_max=59,
+                      lon_min=165,
+                      lon_max=-165,
+                     )
+print("get_argo end")
+
+print("load argo begin")
+# Define File Paths
+argo_path = r"Your/Path/to/Downloaded/pacific_ocean/processed/"
+model_path = r"Your/Path/to/SCHISM run dir/Here/",
+output_path =  r"Your/Path/Here/schism_collocated_argo.nc",
+s_time,e_time = "2019-09-15", "2019-09-30"
+print("load data begin")
+
+print("load argo begin")
+argo_data = ArgoData(argo_path)
+print("Argo data loaded.")
+#    Use convert_longitude if needed (mode=1 for converting to 0-360 degrees).
+argo_data.lon = convert_longitude(argo_data.lon, mode=1)
+
+print("load model begin")
+model_config_3d = {
+    'var': 'temperature',
+    'startswith': 'temperature_',
+    'var_type': '3D_Profile',
+    'zcor_var': 'zCoordinates',
+    'zcor_startswith': 'zCoordinates_'
+}
+model_run = SCHISM(
+    rundir=model_path,
+    model_dict=model_config_3d,
+    start_date=np.datetime64(s_time),
+    end_date=np.datetime64(e_time)
+)
+
+# print("Converting model mesh longitudes...")
+# model_run.mesh_x = convert_longitude(model_run.mesh_x, mode=2) 
+# print("Model loaded.")
+
+print(f"Argo LONS --- min: {argo_data.lon.min()}, max: {argo_data.lon.max()}")
+print(f"Model LONS --- min: {model_run.mesh_x.min()}, max: {model_run.mesh_x.max()}")
+
+print("Initializing Collocate class...")
+# dist_coast = xr.open_dataset(r'Your/Path/to/OPTIONAL/distFromCoast.nc')
+try:
+    collocator = Collocate(
+        model_run=model_run,
+        observation=argo_data,
+        # dist_coast=dist_coast,
+        n_nearest=3,
+        temporal_interp=True
+    )
+    print("Collocate class initialized.")
+except Exception as e:
+    print(f"Error during Collocator initialization: {e}")
+print("Starting collocation run...")
+
+try:
+    collocated_data = collocator.run(output_path=output_path)
+    print("Collocation run complete.")
+    print(f"Collocation finished. Output saved to: {output_path}")
+    print("\n--- Collocated Dataset ---")
+    print(collocated_data)
+except Exception as e:
+    print(f"Error during collocation run: {e}")