Update documentation

Author: e-marshall

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: bb0945d3c7fa4c7a6bc2ef05821ab00a
+config: ab2a3ecbfd242a2254483b188fe759df
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/background/context_motivation.md

@@ -1,8 +1,8 @@
-# Context & Motivation
+# 2.1 Context & Motivation
 
 This book demonstrates scientific workflows using publicly-available, cloud-optimized geospatial datasets and open-source scientific software tools in order to address the need for educational resources related to new technologies and reduce barriers to entry to working with earth observation data. The tutorials in this book focus on the complexities inherent to working with n-dimensional, gridded datasets and use the core stack of software packages built on and around the Xarray data model.
 
-### *I. Moving away from the 'download model' of scientific data analysis*
+### *Moving away from the 'download model' of scientific data analysis*
 
 Technological developments in recent decades have engendered fundamental shifts in the nature of scientific data and how it is used for analysis.
 
@@ -11,7 +11,7 @@ Technological developments in recent decades have engendered fundamental shifts
 -- {cite}`abernathey_2021_cloud`
 ```
 
-### *II. Increasingly large, cloud-optimized data means new tools and approaches for data management*
+### *Increasingly large, cloud-optimized data means new tools and approaches for data management*
 
 The increase in publicly available earth observation data has transformed scientific workflows across a range of fields, prompting analysts to gain new skills in order to work with larger volumes of data in new formats and locations, and to use distributed cloud-computational resources in their analysis ({cite:t}`abernathey_2021_cloud,gentemann_2021_science,mathieu_2017_esas,ramachandran_2021_open,Sudmanns_2020_big,wagemann_2021_user`). 
 
@@ -21,7 +21,7 @@ The increase in publicly available earth observation data has transformed scient
 Volume of NASA Earth Science Data archives, including growth of existing-mission archives and new missions, projected through 2029. Source: [NASA EarthData - Open Science](https://www.earthdata.nasa.gov/about/open-science).
 ```
 
-### *III. Asking questions of complex datasets*
+### *Asking questions of complex datasets*
 
 Scientific workflows involve asking complex questions of diverse types of data. Earth observation and related datasets often contain two types of information: measurements of a physical observable (e.g. temperature) and metadata that provides auxiliary information that required in order to interpret the physical observable (time and location of measurement, information about the sensor, etc.). With the increasingly complex and large volume of earth observation data that is currently available, storing, managing and organizing these types of data can very quickly become a complex and challenging task, especially for students and early-career analysts {cite}`mathieu_esas_2017,palumbo_2017_building,Sudmanns_2020_big,wagemann_2021_user`. 
 

_sources/background/data_cubes.md

@@ -1,8 +1,8 @@
-# Data cubes
+# 2.2 Data cubes
 
 The term **data cube** is used frequently throughout this book. This page contains an introduction of ***what*** a data cube is and ***why*** it is useful. 
 
-## *I. Anatomy of a data cube*
+## *Anatomy of a data cube*
 
 The key object of analysis in this book is a [raster data cube](https://openeo.org/documentation/1.0/datacubes.html). Raster data cubes are n-dimensional objects that store continuous measurements or estimates of physical quantities that exist along given dimension(s). Many scientific workflows involve examining how a variable (such as temperature, windspeed, relative humidity, etc.) varies over time and/or space. Data cubes are a way of organizing geospatial data that let us ask these questions.
 
@@ -55,7 +55,7 @@ A data cube should be organized out of these building blocks adhering to the fol
 **Attributes** - Metadata that can be assigned to a given `xr.Dataset` or `xr.DataArray` that is ***static*** along that object's dimensions.   
 :::
 
-## *II. 'Analysis-ready' data*
+## *'Analysis-ready' data*
 The process described above is an example of preparing data for analysis. Thanks to development and collaboration across the earth observation community, analysis-ready for earth observation has a specific, technical definition:
 
 ```{epigraph}
@@ -67,15 +67,15 @@ The development and increasing adoption of analysis-ready specifications for sat
 
 However, many legacy datasets still require significant effort in order to be considered 'analysis-ready'. Furthermore, for analysts, 'analysis-ready' can be a subjective and evolving label. Semantically, from a user-perspective, analysis-ready data can be thought of as data whose structure is conducive to scientific analysis.
 
-## *III. Analysis-ready data cubes & this book*
+## *Analysis-ready data cubes & this book*
 The tutorials in this book contain examples of data at various degrees of 'analysis-ready'. [Tutorial 1: ITS_LIVE](../itslive/itslive_intro.md) uses a dataset of multi-sensor observations that is already organized as a `(x,y,time)` cube with a common grid. In [Tutorial 2: Sentinel-1](../sentinel1/s1_intro.md), we will see an example of a dataset that has undergone intensive processing to make it 'analysis-ready' but requires further manipulation to arrive at the `(x,y,time)` cube format that will be easist to work with. 
 
 ### References
 - {cite:t}`montero_2024_EarthSystemData`
 - {cite:t}`appel_2019_ondemand`
 - {cite:t}`giuliani_2019_EarthObservationOpen`
 - {cite:t}`truckenbrodt_2019_Sentinel1ARD`
-## Additional data cube resources
+### Additional data cube resources*
 - [OpenEO - Data Cubes](https://openeo.org/documentation/1.0/datacubes.html)
 - [Open Data Cube initiative](https://www.opendatacube.org/about-draft)
 - [The Datacube Manifesto](http://www.earthserver.eu/tech/datacube-manifesto/The-Datacube-Manifesto.pdf)

_sources/background/relevant_concepts.md

@@ -1,4 +1,4 @@
-# Relevant concepts
+# 2.6 Relevant concepts
 
 ## *Larger than memory data, parallelization and Dask*
 

_sources/background/software.md

@@ -0,0 +1,34 @@
+# 2.5 Software and computing environment
+
+On this page you'll find information about the computing environment and datasets that will be used in both of the tutorials in this book.
+
+## *Running tutorial materials locally*
+
+There are two options for creating a software environment: [pixi](https://pixi.sh/latest/) or [mamba](https://mamba.readthedocs.io/en/latest/) / [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html). We recommend using pixi to create a consistent environment on different operating systems. If you have pixi installed, follow the steps below, otherwise, follow the steps for conda/mamba below.
+
+### To use pixi
+1. Clone the book's GitHub repository:   
+    ```git clone https://github.com/e-marshall/cloud-open-source-geospatial-datacube-workflows.git```
+
+2. Navigate into the repo environment:
+```cd cloud-open-source-geospatial-datacube-workflows```
+
+3. Execute `pixi run` for each tutorial:
+```pixi run itslive```
+```pixi run sentinel1```
+
+### To use conda/mamba
+
+1. Clone this book's GitHub repository:  
+```git clone https://github.com/e-marshall/cloud-open-source-geospatial-datacube-workflows.git```
+
+2. Navigate into the `book` sub-directory:  
+```cd cloud-open-source-geospatial-datacube-workflows/book```
+
+3. Create and activate a conda environment from the `environment.yml` file located in the repo:  
+```conda env create -f .binder/environment.yml```
+
+4. Start Jupyterlab and navigate to the directories containing the Jupyter notebooks (`itslive/nbs` and `s1/nbs`):  
+```jupyterlab```
+
+Both tutorials use functions that are stored in scripts associated with each dataset. You can find these scripts here: [`itslive_tools.py`](../itslive/nbs/itslive_tools.py) and [`s1_tools.py`](../s1/nbs/s1_tools.py).

_sources/background/tutorial_data.md

@@ -1,4 +1,4 @@
-# Data used in tutorials
+# 2.4 Data used in tutorials
 
 We use a many different datasts throughout these tutorials. While each tutorial is focused on a different raster time series (ITS_LIVE ice velocity data and Sentinel-1 imagery), we also use vector data to represent points of interest. 
 

_sources/background/tutorials_overview.md

@@ -1,4 +1,4 @@
-# Tutorials overview
+# 2.3 Tutorials overview
 
 This book contains two distinct tutorials, each of which focuses on a different cloud-optimized geospatial dataset and different cloud-computing resources. Read more about the datasets used [here](tutorial_data.md).
 

_sources/conclusion/datacubes_revisited.md

@@ -1,4 +1,4 @@
-# Data Cubes Revisited
+# 5.3 Data Cubes Revisited
 
 In this book, we saw a range of real-world datasets and the steps required to prepare them for analysis. Several guiding principles for assembling and using analysis-ready data cubes in Xarray can be drawn from these examples.
 

_sources/conclusion/summary.md

@@ -1,4 +1,4 @@
-# Tutorials summary
+# 5.2 Tutorials summary
 
 In this book, we worked through tutorials accessing two satellite remote sensing datasets, preparing them for analysis and performing exploratory data analysis and visualization. 
 

_sources/conclusion/wrapping_up.md

@@ -1,36 +1,27 @@
-# Wrapping up
+# 5.1 Wrapping up
 
 It is a popular refrain, and a sentiment many analysts can likey relate to, "that 80% of data analysis is spent on the cleaning and preparing of data" {cite:t}`Wickham_2014_Tidy,Dasu_2003_Exploratory`. This book focuses on the data cleaning and preparation steps of an analytical workflow that ingests satellite remote sensing time series datasets. We draw on the wealth of knowledge and research that attends to this topic in order to produce tutorials that demonstrate and explain these concepts in the context of cloud-optimized, publicly available array data and the software ecosystem built around the Xarray data model in Python. 
 
-In this chapter, you will find summaries of the concepts covered throughout the Jupyter Notebooks included in this book, a return to the introduction's [discussion of data cubes](../background/data_cubes.md) with synthesis and lessons learned from the tutorials, and a short discussion of the broader context of this book and next steps for interested readers. 
+In this chapter, you will find summaries of the concepts covered throughout the Jupyter Notebooks included in this book and a return to the introduction's [discussion of data cubes](../background/data_cubes.md) that synthesizes lessons learned in the tutorials. 
 
-## Tutorials Summary[$\tiny \nearrow$](summary.md)
-
-This book features two tutorials, each focuses on a different earth observation dataset and containing five notebooks that cover different steps of a typical workflow such as data access, manpiulation and organizatoin and visualization and exploratory analysis. In this section, you will find a few of the common topics throughout these notebooks and links to where they are addressed in each tutorial. 
-
-## Data cubes revisited [$\tiny \nearrow$](datacubes_revisited.md)
-
-Synthesizing lessons from tutorial examples to enumerate guidance and best-practices for working Xarray geospatial data cubes.
-
-## Broader context [$\tiny \nearrow$]()
-
-It is a popular refrain, and a sentiment many analysts can likey relate to, "that 80% of data analysis is spent on the cleaning and preparing of data" {cite:t}`Wickham_2014_Tidy,Dasu_2003_Exploratory`. This book focuses on the data cleaning and preparation steps of an analytical workflow. We draw on the wealth of knowledge and research that attends to this topic in order to produce tutorials that demonstrate and explain these topics in the context of satellite remote sensing earth observation datasets and the software ecosystem built around the Xarray data model in Python.  
+### Broader context [$\tiny \nearrow$]()
+ 
 This book largely focused on the beginning steps of scientific workflows where data is prepared for analysis and manipulated to support different types of analysis. 
 
-### Open source tools and packages
-In this book, we mainly focused on Xarray and several tools within the Xarray ecosystem and that integrate with Xarray to streamline data cube workflows such as:
-- Xvec  
-- cf_xarray   
-- Dask   
-- PySTAC   
-- stackstac   
-- GeoPandas  
-- holoviz
-
-There are many exciting open-source projects and tools related to Xarray data cubes that were not highlighted in this book. A few are:
+#### Open source tools and packages
+We mainly use Xarray and tools within the Xarray ecosystem. There are many exciting open-source projects and tools related to Xarray data cubes that were not highlighted in this book. A few are:
 - [XRLint](https://github.com/bcdev/xrlint)
 - [LexCube](https://www.lexcube.org/)
 - [xcube](https://xcube.readthedocs.io/en/latest/)
 - [cubo](https://github.com/ESDS-Leipzig/cubo)
 - [Open Data Cube](https://opendatacube.readthedocs.io/en/latest/index.html)
 
+
+## 5.2 Tutorials Summary[$\tiny \nearrow$](summary.md)
+
+This book features two tutorials, each focuses on a different earth observation dataset and containing five notebooks that cover different steps of a typical workflow such as data access, manpiulation and organizatoin and visualization and exploratory analysis. In this section, you will find a few of the common topics throughout these notebooks and links to where they are addressed in each tutorial. 
+
+## 5.3 Data cubes revisited [$\tiny \nearrow$](datacubes_revisited.md)
+
+Synthesizing lessons from tutorial examples to enumerate guidance and best-practices for working Xarray geospatial data cubes.
+