added NWM analysis data assimilation streamflow product within fimserv

Author: supathdhitalGEO

README.md

@@ -41,7 +41,8 @@ FIMserv/
 │       │   ├── nwmretrospectivedata.py   # Processes NWM retrospective data
 │       │   ├── geoglows.py   # Module to retrieve geoglows streamflow data 
 │       │   ├── usgsdata.py   # Retrieve USGS gauge station data
-│       │   └── forecasteddata.py        # Processes all range forecasted streamflow data
+│       │   ├── forecasteddata.py        # Processes all range forecasted streamflow data
+│       │   └── nwmanalysisassim.py      # Processes NWM Analysis and Assimilation (AnA) data
 │       ├── plots/          # Vizualization functionalities
 │       ├── FIMsubset/      # Subsetting functionalities for FIM
 │       │   ├── xycoord.py  # Subset using Lat, Lon 
@@ -134,6 +135,12 @@ Users can retrieve NWM forecasted and retrospective data for a specified date ra
 ```bash
 fm.getNWMretrospectivedata(start_date, end_date, huc, value_time)
 ```
+NWM Analysis and Assimilation (AnA) streamflow, the gauge assimilated best estimate of past conditions, is also available for events from 2018-09-17 onwards. It is indexed by valid time, so users pass a start and end date (with or without an hour, in UTC) and get either one aggregated discharge file or a continuous hourly series.
+```bash
+fm.getNWManalysisAssim(huc, start_date, end_date)                            #One file aggregated over the range
+fm.getNWManalysisAssim(huc, start_date, end_date, continuous_discharge=True) #One file per hour
+fm.getNWManalysisAssim(huc, start_date, end_date, value_times=value_times)     #Only the event day or timestep
+```
 **Step 3. Generate the Flood Inundation Mapping**
 
 This functionality automatically uses the recently downloaded and stored streamflow to generate FIM. This automation is based on the HUCID.

dist/.gitignore

@@ -834,6 +834,62 @@
     "fm.getNWMForecasteddata(huc, forecast_range=\"longrange\", sort_by=\"maximum\")    #This is an example of getting longrange data  with minimum sorting"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### **STEP 6.2 Downloading the NWM Analysis and Assimilation (AnA) Streamflow data**\n",
+    "\n",
+    "**Unlike the forecasts, AnA is the NWM best estimate of what already happened. It is run every hour with observed forcing and is nudged towards the observed USGS streamflow, so it is indexed by valid time rather than by a forecast cycle. This makes it the configuration to use when mapping a past event or validating FIM against an observed flood extent.**\n",
+    "\n",
+    "**The user provides a start and an end date (with or without an hour, in UTC). By default a single aggregated discharge file is saved for the whole range. NWM AnA is available from 2018-09-17 onwards; for older events use ```getNWMretrospectivedata```.**"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# One aggregated discharge file for the whole range (maximum by default)\n",
+    "fm.getNWManalysisAssim(huc, start_date=\"2024-09-26\", end_date=\"2024-09-28\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### **STEP 6.2.1 Continuous hourly, single event day or single timestep AnA streamflow**\n",
+    "\n",
+    "**Setting ```continuous_discharge=True``` saves one discharge CSV per hour, which generates an hourly FIM series for the event. Passing ```value_times``` inside the range instead saves only those timesteps, using the same parameter name as ```getNWMretrospectivedata```. A plain day saves that whole day aggregated with ```sort_by```, while a timestamp with an hour saves that exact hour.**"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Continuous hourly discharge, one CSV per timestep\n",
+    "fm.getNWManalysisAssim(huc, \"2024-09-26\", \"2024-09-28\", continuous_discharge=True)\n",
+    "\n",
+    "# Only the event day within the range, aggregated with sort_by\n",
+    "fm.getNWManalysisAssim(huc, \"2024-09-26\", \"2024-09-28\", value_times=\"2024-09-27\")\n",
+    "\n",
+    "# Only a single timestep within the range\n",
+    "fm.getNWManalysisAssim(\n",
+    "    huc, \"2024-09-26\", \"2024-09-28\", value_times=\"2024-09-27 12:00:00\"\n",
+    ")\n",
+    "\n",
+    "# Several value_times at once, same as getNWMretrospectivedata accepts\n",
+    "fm.getNWManalysisAssim(\n",
+    "    huc,\n",
+    "    \"2024-09-26\",\n",
+    "    \"2024-09-28\",\n",
+    "    value_times=[\"2024-09-27 06:00:00\", \"2024-09-27 18:00:00\"],\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

dist/fimserve-0.2.0-py3-none-any.whl

@@ -1,6 +1,6 @@
 [project]
 name = "fimserve"
-version = "0.2.1"
+version = "0.2.11"
 description = "Framework which is developed with the purpose of quickly generating Flood Inundation Maps (FIM) for emergency response and risk assessment. It is developed under Surface Dynamics Modeling Lab (SDML)."
 authors = [
     { name = "Surface Dynamics Modeling Lab (SDML)" },