Add README and improve docstrings and WEL update logic

Added a new README for the Dash app with setup and usage instructions. Added or improved docstrings throughout dash_app.py and ckan_publish.py for better code clarity. Updated flopy_wel_map.py to handle dtype preservation in WEL stress period data updates, ensuring correct array types and empty period handling.

Author: wmobley

dash/README.md

@@ -0,0 +1,43 @@
+# FloPy Dash App
+
+Dash dashboard for visualizing WEL/RCH data, selecting cells on a map, applying rate updates, and publishing updated WEL files back to CKAN with provenance metadata.
+
+## Quick start
+
+1. Create a virtual environment.
+2. Install dependencies:
+
+```
+pip install -r dash/requirements-dash.txt
+```
+
+3. Run the app:
+
+```
+python dash/dash_app.py
+```
+
+The app listens on http://localhost:8050 by default.
+
+## Environment variables
+
+- `FLOPY_DATA_DIR`: Directory where CKAN resources are downloaded (default: `ckan_data`).
+- `FLOPY_OUTPUT_WEL`: Default output WEL path (default: `barton_springs_updated.wel`).
+- `FLOPY_CKAN_URL`: CKAN base URL (default: `https://ckan.tacc.utexas.edu`).
+- `FLOPY_CKAN_JWT`: CKAN JWT to skip login flow.
+- `FLOPY_TAPIS_USERNAME`: Tapis username (used if `FLOPY_CKAN_JWT` is not set).
+- `FLOPY_TAPIS_PASSWORD`: Tapis password (used if `FLOPY_CKAN_JWT` is not set).
+
+## App flow
+
+- Select a dataset, flux source (WEL or RCH), and stress periods.
+- Lasso or click cells on the map to build a selection.
+- Set a rate update mode (set or scale) and apply changes.
+- Provide a dataset name, output filename, and change summary.
+- Click Apply + Save to write the updated WEL and publish to CKAN.
+
+## Files
+
+- `dash/dash_app.py`: Dash UI and callbacks.
+- `dash/ckan_publish.py`: CKAN/Tapis helpers and publish logic.
+- `dash/assets/style.css`: Dash styling.

dash/ckan_publish.py

@@ -21,17 +21,20 @@
 
 
 def _now_iso() -> str:
+    """Return current UTC time in ISO8601 Zulu format."""
     return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
 
 
 def _slugify(value: str) -> str:
+    """Normalize a string for CKAN dataset/resource naming."""
     value = value.strip().lower().replace(" ", "-")
     value = re.sub(r"[^a-z0-9\-_.]", "-", value)
     value = re.sub(r"-{2,}", "-", value)
     return value.strip("-") or "dataset"
 
 
 def _extras_to_dict(extras: Iterable[Dict]) -> Dict[str, str]:
+    """Convert CKAN extras list into a key/value dict."""
     result: Dict[str, str] = {}
     for item in extras or []:
         if not isinstance(item, dict):
@@ -44,12 +47,14 @@ def _extras_to_dict(extras: Iterable[Dict]) -> Dict[str, str]:
 
 
 def _merge_extras(existing: Iterable[Dict], additions: Dict[str, str]) -> List[Dict]:
+    """Merge extras with updates, returning CKAN list-of-dict format."""
     merged = _extras_to_dict(existing)
     merged.update({k: v for k, v in additions.items() if v is not None})
     return [{"key": key, "value": value} for key, value in merged.items()]
 
 
 def _extract_mint_svo(extras: Iterable[Dict]) -> Optional[str]:
+    """Find the MINT SVO value from known extras keys."""
     candidates = [
         "MINT_SVO",
         "MINT Standard Variables",
@@ -64,6 +69,7 @@ def _extract_mint_svo(extras: Iterable[Dict]) -> Optional[str]:
 
 
 def _resolve_mint_svo(resource: Dict, dataset: Dict) -> Optional[str]:
+    """Resolve the MINT SVO from resource or dataset metadata."""
     mint_svo = _extract_mint_svo(resource.get("extras", []))
     if mint_svo:
         return mint_svo
@@ -79,12 +85,14 @@ def _resolve_mint_svo(resource: Dict, dataset: Dict) -> Optional[str]:
 
 
 def get_tapis_token(username: str, password: str) -> str:
+    """Authenticate to Tapis and return the access token."""
     tapis = Tapis(base_url="https://portals.tapis.io", username=username, password=password)
     tapis.get_tokens()
     return tapis.access_token.access_token
 
 
 def get_jwt_token() -> str:
+    """Return a CKAN JWT from env or Tapis credentials."""
     jwt_token = os.environ.get("FLOPY_CKAN_JWT", "").strip()
     if jwt_token:
         return jwt_token
@@ -96,10 +104,12 @@ def get_jwt_token() -> str:
 
 
 def _headers(jwt_token: str) -> Dict[str, str]:
+    """Build auth headers for CKAN API requests."""
     return {"Authorization": f"Bearer {jwt_token}"}
 
 
 def package_show(jwt_token: str, dataset_name: str) -> Dict:
+    """Fetch CKAN dataset metadata by name."""
     url = f"{CKAN_URL}/api/3/action/package_show"
     response = requests.get(url, params={"id": dataset_name}, headers=_headers(jwt_token), timeout=60)
     response.raise_for_status()
@@ -110,6 +120,7 @@ def package_show(jwt_token: str, dataset_name: str) -> Dict:
 
 
 def create_dataset(jwt_token: str, dataset_dict: Dict) -> Dict:
+    """Create a new CKAN dataset."""
     url = f"{CKAN_URL}/api/3/action/package_create"
     response = requests.post(url, json=dataset_dict, headers=_headers(jwt_token), timeout=60)
     if response.status_code == 409:
@@ -127,6 +138,7 @@ def create_resource_upload(
     file_path: Path,
     resource_dict: Dict,
 ) -> Dict:
+    """Upload a file as a CKAN resource."""
     url = f"{CKAN_URL}/api/3/action/resource_create"
     data = {
         "package_id": dataset_id,
@@ -156,6 +168,7 @@ def build_dataset_payload(
     change_summary: str | None = None,
     maintainer_username: str | None = None,
 ) -> Dict:
+    """Create a dataset payload derived from a source dataset."""
     copy_fields = [
         "title",
         "notes",
@@ -206,6 +219,7 @@ def build_resource_payload(
     source_url: str | None = None,
     change_summary: str | None = None,
 ) -> Dict:
+    """Create a resource payload derived from a source resource."""
     extras = source_resource.get("extras", [])
     extras = _merge_extras(
         extras,
@@ -243,6 +257,7 @@ def publish_updated_wel(
     change_summary: Optional[str] = None,
     maintainer_username: Optional[str] = None,
 ) -> Dict:
+    """Create or update a derived dataset and upload the updated WEL file."""
     jwt_token = jwt_token or get_jwt_token()
     source_dataset = package_show(jwt_token, source_dataset_name)
     resources = source_dataset.get("resources", [])

dash/dash_app.py

@@ -30,10 +30,12 @@
 
 @lru_cache(maxsize=1)
 def get_datasets() -> List[Dict]:
+    """Fetch CKAN datasets cached for the app session."""
     return fwm._search_ckan_datasets()
 
 
 def _get_dataset_or_none(name: str | None) -> Dict | None:
+    """Return dataset metadata matching a name, if present."""
     if not name:
         return None
     datasets = get_datasets()
@@ -45,6 +47,7 @@ def _get_dataset_or_none(name: str | None) -> Dict | None:
 
 @lru_cache(maxsize=8)
 def load_dataset(name: str) -> Dict:
+    """Download CKAN resources and assemble WEL/RCH/grid inputs."""
     dataset = _get_dataset_or_none(name)
     if not dataset:
         raise ValueError(f"Dataset not found: {name}")
@@ -89,6 +92,7 @@ def load_dataset(name: str) -> Dict:
 def _collect_wel_cells_for_periods(
     wel, gdf, periods: Sequence[int]
 ) -> Dict[int, float]:
+    """Aggregate WEL flux by cell across selected periods."""
     cell_id_lookup = dict(zip(zip(gdf["ROW"], gdf["COL"]), gdf["CELL_ID"]))
     if not periods:
         spd = getattr(wel, "stress_period_data", None)
@@ -122,6 +126,7 @@ def _build_map_figure(
     force_linear: bool,
     selected_ids: Iterable[int],
 ) -> go.Figure:
+    """Build the Plotly map figure with grid and selection overlays."""
     gdf_map = gdf[["CELL_ID", "ROW", "COL", "geometry"]].copy()
     grid_geojson = gdf_map.set_index("CELL_ID").__geo_interface__
     center_lat = float(gdf["_lat"].median())
@@ -246,6 +251,7 @@ def _build_map_figure(
 
 
 def _dataset_options() -> List[Dict[str, str]]:
+    """Build dataset dropdown options from CKAN search."""
     try:
         datasets = get_datasets()
     except Exception:
@@ -254,6 +260,7 @@ def _dataset_options() -> List[Dict[str, str]]:
 
 
 def _owned_gam_datasets(username: str, jwt_token: str) -> List[Dict[str, str]]:
+    """List datasets owned by a user for suggestion dropdowns."""
     if not username or not jwt_token:
         return []
     options: List[Dict[str, str]] = []
@@ -273,6 +280,7 @@ def _owned_gam_datasets(username: str, jwt_token: str) -> List[Dict[str, str]]:
     return options
 
 def _slugify(value: str) -> str:
+    """Normalize a string for use in dataset naming."""
     value = value.strip().lower().replace(" ", "-")
     value = re.sub(r"[^a-z0-9\-_.]", "-", value)
     value = re.sub(r"-{2,}", "-", value)
@@ -483,6 +491,7 @@ def _slugify(value: str) -> str:
     Input("loaded-dataset", "data"),
 )
 def update_dataset_controls(loaded_dataset: str | None):
+    """Populate stress period and layer controls for the dataset."""
     if not loaded_dataset:
         return [], []
     data = load_dataset(loaded_dataset)
@@ -505,6 +514,7 @@ def update_dataset_controls(loaded_dataset: str | None):
     prevent_initial_call=False,
 )
 def load_selected_dataset(n_clicks, selected_dataset, load_counter):
+    """Load dataset resources and update load state messages."""
     if not selected_dataset:
         return None, "No dataset selected.", load_counter
     try:
@@ -528,6 +538,7 @@ def load_selected_dataset(n_clicks, selected_dataset, load_counter):
 def update_periods_layers(
     loaded_dataset, select_periods_clicks, select_layers_clicks, period_options, layer_options
 ):
+    """Handle select-all interactions for periods and layers."""
     triggered = ctx.triggered_id
     if triggered == "select-all-periods":
         period_values = [opt["value"] for opt in (period_options or [])]
@@ -569,6 +580,7 @@ def update_periods_layers(
     prevent_initial_call=True,
 )
 def login_ckan(n_clicks, username, password):
+    """Authenticate with Tapis and store the CKAN JWT."""
     if not n_clicks:
         raise dash.exceptions.PreventUpdate
     if not username or not password:
@@ -589,6 +601,7 @@ def login_ckan(n_clicks, username, password):
     Input("loaded-dataset", "data"),
 )
 def update_category_controls(color_by, loaded_dataset):
+    """Show or hide category selection controls by color mode."""
     if not loaded_dataset or color_by == "flux":
         return [], None, {"display": "none"}, True
     data = load_dataset(loaded_dataset)
@@ -608,6 +621,7 @@ def update_category_controls(color_by, loaded_dataset):
     Input("ckan-jwt", "data"),
 )
 def update_dataset_suggestions(username, jwt_token):
+    """Return dataset suggestions owned by the logged-in user."""
     return _owned_gam_datasets(username or "", jwt_token or "")
 
 
@@ -653,6 +667,7 @@ def suggest_names(
     current_source_url,
     current_change_summary,
 ):
+    """Generate dataset/output names and change summary from UI state."""
     if not loaded_dataset:
         return current_dataset_name, current_output_name, current_source_url, current_change_summary
     if suggested_name:
@@ -724,6 +739,7 @@ def update_selection(
     color_by,
     category_value,
 ):
+    """Update selected cell IDs based on map interactions."""
     selected_ids = [int(cid) for cid in (selected_ids or [])]
     triggered = ctx.triggered_id
     if triggered == "clear-selection":
@@ -765,6 +781,7 @@ def update_selection(
     Input("selection-warning", "data"),
 )
 def update_selection_status(selected_ids, selection_warning):
+    """Update selection status text and warning styling."""
     count = len(selected_ids or [])
     class_name = "status"
     if selection_warning and count == 0:
@@ -778,6 +795,7 @@ def update_selection_status(selected_ids, selection_warning):
     Input("color-by", "value"),
 )
 def update_category_warning(category_warning, color_by):
+    """Highlight the category selector when a warning is active."""
     base = "category-wrap"
     if color_by != "flux" and category_warning:
         return f"{base} warn-pulse"
@@ -789,6 +807,7 @@ def update_category_warning(category_warning, color_by):
     Input("flux-source", "value"),
 )
 def update_output_label(flux_source):
+    """Switch the output label based on flux source."""
     return "Output RCH filename" if flux_source == "rch" else "Output WEL filename"
 
 
@@ -829,6 +848,7 @@ def apply_rate(
     change_summary,
     tapis_username,
 ):
+    """Apply rate updates and optionally publish to CKAN."""
     if not n_clicks:
         return "", update_counter, False
     if not loaded_dataset:
@@ -924,6 +944,7 @@ def apply_rate(
 def update_map(
     loaded_dataset, _load_counter, flux_source, color_by, periods, selected_ids, _update
 ):
+    """Refresh the map when dataset or settings change."""
     if not loaded_dataset:
         return go.Figure()
     data = load_dataset(loaded_dataset)

flopy_wel_map.py

@@ -802,11 +802,15 @@ def apply_rate_update(
     output_path: Path,
 ) -> int:
     spd = wel.stress_period_data.data
+    spd_dtype = getattr(wel.stress_period_data, "dtype", None)
     cell_lookup = dict(zip(gdf["CELL_ID"], zip(gdf["ROW"], gdf["COL"])))
     selected_cells = {cell_lookup[cid] for cid in selected_ids if cid in cell_lookup}
     new_spd = {}
     for per, recs in spd.items():
-        recs = recs.copy()
+        if spd_dtype is not None:
+            recs = np.array(recs, dtype=spd_dtype)
+        else:
+            recs = np.array(recs)
         if periods_for_update and per not in periods_for_update:
             new_spd[per] = recs
             continue
@@ -837,6 +841,14 @@ def apply_rate_update(
                         idx += 1
                 recs = new_recs
         new_spd[per] = recs
+    if spd_dtype is not None:
+        cleaned = {}
+        for per, recs in new_spd.items():
+            if recs is None or len(recs) == 0:
+                cleaned[per] = np.zeros(0, dtype=spd_dtype)
+            else:
+                cleaned[per] = np.array(recs, dtype=spd_dtype)
+        new_spd = cleaned
     wel.stress_period_data = new_spd
     wel.write_file(str(output_path))
     return len(selected_cells)