update readme

README.md

@@ -1,5 +1,5 @@
 # Geospatial Time Series Analysis
-Methods to stack geospatial rasters and run memory-efficient computations. 
+Conveninet methods to stack geospatial rasters and run memory-efficient computations along the spatial or temporal axes. 
 
 ## Installation
 
@@ -19,72 +19,93 @@ $ conda activate gtsa
 $ pip install -e .
 ```
 
-## Examples
+## Command Line examples
+
+See `command --help` for more information about each command listed below.
 
 ### Processing
 
-#### Stack single band rasters and chunk along the time dimension for efficient data retrieval
-From command line
+#### Download sample Digital Elevation Model (DEM) data
 ```
-create_stack --help
+download_data --site south-cascade \
+              --outdir data \
+              --product dem \
+              --include_refdem \
+              --workers 8 \
+              --overwrite        
 ```
-Python examples in 
+
+#### Stack single-band rasters and chunk along the time dimension
 ```
-notebooks/processing/01_create_stacks.ipynb`
+create_stack --datadir data/dems/south-cascade \
+             --date_string_format %Y%m%d \
+             --date_string_pattern _........_ \
+             --date_string_pattern_offset 1 \
+             --outdir data/dems/south-cascade \
+             --dask_enabled \
+             --overwrite
 ```
 
 #### Run memory-efficient time series analysis methods using dask
-From command line
-```
-gtsa --help
-```
-Python examples in 
+
 ```
-notebooks/processing/02_time_series_computations.ipynb`
+c=count # count, mean, std, min, max, median, sum or nmad
+gtsa --input_file data/dems/south-cascade/temporal/stack.zarr \
+     --compute $c \
+     --outdir data/dems/south-cascade/outputs \
+     --workers 8\
+     --dask_enabled \
+     --overwrite \ 
+     --test_run
+
+# Linear regression
+gtsa --input_file data/dems/south-cascade/temporal/stack.zarr \
+     --compute polyfit \
+     --degree 1 \
+     --frequency 1Y \
+     --outdir data/dems/south-cascade/outputs \
+     --dask_enabled
+
+# Higher order polynomial fits
+d=3 
+gtsa --input_file data/dems/south-cascade/temporal/stack.zarr \
+     --compute polyfit \
+     --degree $d \
+     --frequency 1Y \
+     --outdir data/dems/south-cascade/outputs \
+     --dask_enabled
 ```
 
 ### Visualization
 
-
-#### Convert single band rasters to Cloud Optimized GeoTIFFs (COGs)
-From command line
-```
-create_cogs --help
-```
-
-Python examples in 
+#### Download sample orthoimage data
 ```
-notebooks/visualization/01_create_cogs.ipynb
+download_data --site south-cascade \
+              --outdir data \
+              --product ortho \
+              --workers 8 \
+              --overwrite        
 ```
 
-#### Create interactive folium map for efficient visualization
-From command line
+#### Convert single-band rasters to Cloud Optimized GeoTIFFs (COGs)
 ```
-create_cog_map --help
+create_cogs --datadir data/orthos/south-cascade \
+            --outdir data/orthos/south-cascade/cogs \
+            --workers 8 \
+            --overwrite
 ```
 
-Python examples in 
-```
-notebooks/visualization/02_create_cog_map.ipynb
-```
 
-## Download sample data
-From command line
+#### Create interactive folium map for efficient visualization
 ```
-download_data --help
+create_cog_map --pipeline notebooks/visualization/pipeline.json \
+               --output_file map.html \
+               --zoom_start 11 \ 
+               --overwrite
 ```
 
-Example
-
-```
-download_data --site south-cascade \
-              --outdir data \
-              --product dem \
-              --include_refdem \
-              --max_workers 8 \
-              --verbose \
-              --overwrite
-```
+## Python examples
+See Jupyter Notebooks in `notebooks/`
 
 ## Data citations
 

gtsa/cli/create_cog_map.py

@@ -18,23 +18,30 @@
     "-of",
     "--output_file",
     default="map.html",
-    help="Output HTML file name.",
+    help="Output HTML file name. Default is 'map.html'.",
 )
 @click.option(
     "-z",
     "--zoom_start",
     prompt=False,
     default=11,
-    help="Zoom start for map",
+    help="Zoom start for map. Default is 11.",
+)
+@click.option(
+    "-ow",
+    "--overwrite",
+    is_flag=True,
+    default=False,
+    help="Set to overwrite.",
 )
 @click.option(
     "-si",
     "--silent",
     is_flag=True,
     default=False,
-    help="Set to silence stdout. Default is False.",
+    help="Set to silence stdout.",
 )
-def main(pipeline, output_file, zoom_start, silent):
+def main(pipeline, output_file, zoom_start, silent, overwrite):
     verbose = not silent
 
     with open(pipeline) as json_file:
@@ -45,10 +52,12 @@ def main(pipeline, output_file, zoom_start, silent):
         zoom_start=zoom_start,
         verbose=verbose,
     )
-    m.save(output_file)
-    if verbose:
-        print("map saved to", output_file)
-
+    if not Path(output_file).exists() or overwrite:
+        m.save(output_file)
+        if verbose:
+            print("map saved to", output_file)
+    elif Path(output_file).exists() and not overwrite:
+        print(f"{output_file} exists. Set --overwrite to overwrite.")
     return
 
 

gtsa/cli/create_cogs.py

@@ -1,5 +1,6 @@
 import click
 from pathlib import Path
+import psutil
 import gtsa
 
 
@@ -10,35 +11,36 @@
     "-dd",
     "--datadir",
     prompt=True,
-    default="data",
-    help="Path to directory containing GeoTIFFs.",
+    default="data/orthos/south-cascade",
+    help="Path to directory containing single-band 8-bit GeoTIFFs. Default is 'data/orthos/south-cascade'.",
 )
 @click.option(
     "-od",
     "--outdir",
     prompt=True,
-    default="data/cogs",
-    help="Output directory path.",
+    default="data/orthos/south-cascade/cogs",
+    help="Output directory path. Default is 'data/orthos/south-cascade/cogs'.",
 )
 @click.option(
     "-mw",
     "--workers",
     default=None,
-    help="Set to integer matching cores to be used.",
+    type=int,
+    help="Number of cores. Default is logical cores -1.",
 )
 @click.option(
-    "-si",
-    "--silent",
+    "-ow",
+    "--overwrite",
     is_flag=True,
-    default=True,
-    help="Set to silence stdout. Default is False.",
+    default=False,
+    help="Set to overwrite.",
 )
 @click.option(
-    "-ow",
-    "--overwrite",
+    "-si",
+    "--silent",
     is_flag=True,
     default=False,
-    help="Set to overwrite. Default is False.",
+    help="Set to silence stdout.",
 )
 def main(
     datadir,
@@ -47,6 +49,10 @@ def main(
     silent,
     overwrite,
 ):
+    verbose = not silent
+
+    if not workers:
+        workers = psutil.cpu_count(logical=True) - 1
     files = [x for x in sorted(Path(datadir).glob("*.tif"))]
 
     out = gtsa.utils.create_cogs(
@@ -55,7 +61,7 @@ def main(
         crs="EPSG:4326",  # currently required for visualization with folium and titiler
         overwrite=overwrite,
         workers=workers,
-        verbose=silent,
+        verbose=verbose,
     )
     print("DONE")
 

gtsa/cli/create_stack.py

@@ -8,7 +8,7 @@
 
 
 @click.command(
-    help="Stack single-band GeoTIFFs as Zarr file for memory-efficient data retrieval and processing."
+    help="Stack single-band GeoTIFFs for memory-efficient data retrieval and processing."
 )
 @click.option(
     "-dd",
@@ -27,8 +27,8 @@
     "-od",
     "--outdir",
     prompt=True,
-    default="data/stacks",
-    help="Output directory path. Default is 'data/stacks'.",
+    default="data/dems/south-cascade",
+    help="Output directory path. Default is 'data/dems/south-cascade'.",
 )
 @click.option(
     "-dsf",
@@ -128,15 +128,6 @@ def main(
 
     files = [x.as_posix() for x in sorted(Path(datadir).glob("*.tif"))]
 
-    if not reference_tif:
-        reference_tif = files[-1]
-        if verbose:
-            print(
-                'Using last GeoTIFF in datadir as reference grid: "{}"'.format(
-                    reference_tif
-                )
-            )
-
     date_strings = [
         x[date_string_pattern_offset:-date_string_pattern_offset]
         for x in gtsa.io.parse_timestamps(
@@ -148,6 +139,15 @@ def main(
     date_strings, files = list(zip(*sorted(zip(date_strings, files))))
     date_times = [pd.to_datetime(x, format=date_string_format) for x in date_strings]
 
+    if not reference_tif:
+        reference_tif = files[-1]
+        if verbose:
+            print(
+                'Using most recent GeoTIFF as reference grid: "{}"'.format(
+                    reference_tif
+                )
+            )
+
     ds = gtsa.io.xr_stack_geotifs(
         files,
         date_times,

gtsa/cli/download_data.py

@@ -35,8 +35,8 @@
     "-ref",
     "--include_refdem",
     is_flag=True,
-    default=True,
-    help="Set to download reference DEM for site. Default is False.",
+    default=False,
+    help="Set to download reference DEM for site.",
 )
 @click.option(
     "-mw",
@@ -56,7 +56,7 @@
     "-si",
     "--silent",
     is_flag=True,
-    default=True,
+    default=False,
     help="Set to silence stdout. Default is False.",
 )
 def main(