diff --git a/docs/source/_static/PVDeg-Flow.svg b/docs/source/_static/PVDeg-Flow.svg
new file mode 100644
index 00000000..935de386
--- /dev/null
+++ b/docs/source/_static/PVDeg-Flow.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/docs/source/_static/logo-vectors/PVdeg-Logo-Black.svg b/docs/source/_static/logo-vectors/PVdeg-Logo-Black.svg
new file mode 100644
index 00000000..60087393
--- /dev/null
+++ b/docs/source/_static/logo-vectors/PVdeg-Logo-Black.svg
@@ -0,0 +1,27 @@
+
+
\ No newline at end of file
diff --git a/docs/source/_static/logo-vectors/PVdeg-Logo-Color.svg b/docs/source/_static/logo-vectors/PVdeg-Logo-Color.svg
new file mode 100644
index 00000000..d082f0c3
--- /dev/null
+++ b/docs/source/_static/logo-vectors/PVdeg-Logo-Color.svg
@@ -0,0 +1,56 @@
+
+
\ No newline at end of file
diff --git a/docs/source/_static/logo-vectors/PVdeg-Logo-Horiz-Color.svg b/docs/source/_static/logo-vectors/PVdeg-Logo-Horiz-Color.svg
new file mode 100644
index 00000000..cb6121a9
--- /dev/null
+++ b/docs/source/_static/logo-vectors/PVdeg-Logo-Horiz-Color.svg
@@ -0,0 +1,56 @@
+
+
\ No newline at end of file
diff --git a/docs/source/_static/logo-vectors/PVdeg-Logo-Horiz-black.svg b/docs/source/_static/logo-vectors/PVdeg-Logo-Horiz-black.svg
new file mode 100644
index 00000000..ab3b6480
--- /dev/null
+++ b/docs/source/_static/logo-vectors/PVdeg-Logo-Horiz-black.svg
@@ -0,0 +1,27 @@
+
+
\ No newline at end of file
diff --git a/docs/source/_static/logo-vectors/PVdeg-Logo-Horiz-white.svg b/docs/source/_static/logo-vectors/PVdeg-Logo-Horiz-white.svg
new file mode 100644
index 00000000..22d61d60
--- /dev/null
+++ b/docs/source/_static/logo-vectors/PVdeg-Logo-Horiz-white.svg
@@ -0,0 +1,27 @@
+
+
\ No newline at end of file
diff --git a/docs/source/_static/logo-vectors/PVdeg-Logo-White.svg b/docs/source/_static/logo-vectors/PVdeg-Logo-White.svg
new file mode 100644
index 00000000..cc795b30
--- /dev/null
+++ b/docs/source/_static/logo-vectors/PVdeg-Logo-White.svg
@@ -0,0 +1,27 @@
+
+
\ No newline at end of file
diff --git a/docs/source/_static/pvdeg.ico b/docs/source/_static/pvdeg.ico
new file mode 100644
index 00000000..f36d3275
Binary files /dev/null and b/docs/source/_static/pvdeg.ico differ
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 680216c2..f07206d5 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -147,12 +147,12 @@
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
-html_logo = "../../tutorials_and_tools/pvdeg_logo.png" # logo should work at this path
+html_logo = "./_static/logo-vectors/PVdeg-Logo-Horiz-Color.svg" # logo should work at this path
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
-# html_favicon = None
+html_favicon = "./_static/pvdeg.ico"
html_static_path = ["_static"]
diff --git a/docs/source/index.rst b/docs/source/index.rst
index f9786b8d..5eef84de 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -3,9 +3,10 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-.. image:: ../../tutorials_and_tools/pvdeg_logo.png
- :width: 500
+.. .. image:: ../../tutorials_and_tools/pvdeg_logo.png
+.. :width: 500
+.. image:: ./_static/logo-vectors/PVdeg-Logo-Horiz-Color.svg
Welcome to pvdeg!
@@ -25,35 +26,44 @@ relative humidity in the outside, front and back encapsulant and backsheet,
spectral degradation, and solder fatigue. More functions for standards and
other degradation profiles are in the works.
-The source code for pvdeg is hosted on `github
-`_.
+The source code for pvdeg is hosted on `github `_. Please see the :ref:`installation` page for installation help.
See :ref:`tutorials` to learn how to use and experiment with various functionalities
-Please see the :ref:`installation` page for installation help.
+
+.. image:: ./_static/PVDeg-Flow.svg
+ :alt: PVDeg-Flow diagram.
+
How the Model Works
===================
Coupled with pvlib for module performan and weather/irradiance calculations,
-the PVDegradation Tool estimates degradations, and accelerated factors on
+PVDegradation Tool estimates degradations, and accelerated factors on
user-defined parameters. The `Data Library` is under development as part of the
PVDegradationTool project, compiling literature parameters and functions.
The PVDegradationTool simulatineously reads tens of terabytes of time-series
solar data from state-of-art resource data set National Solar Radiation Database
-(NSRDB), publicly avialable no the cloud, enabling the execution of pvdeg
+(NSRDB), publicly available on the cloud, enabling the execution of pvdeg
beyond the confines of NREL's high-performance computing capabilities.
-
Citing PVDegradation Tools
==========================
If you use this calculator in a published work, please cite:
+.. code-block::
+
+ Holsapple, Derek, Ayala Pelaez, Silvana, Kempe, Michael. "PV Degradation Tools", NREL Github 2020, Software Record SWR-20-71.
+
Please also cite the DOI corresponding to the specific version that you used.
-DOIs are listed at Zenodo.org
+DOIs are listed at Zenodo.org. `linked here `_
+
+.. code-block::
+
+ Martin Springer, Tobin Ford, Matt, MDKempe, Silvana Ovaitt, AidanWesley, joe karas, Mark Campanelli, Derek M Holsapple, and Kevin Anderson. “NREL/PVDegradationTools: 0.4.2.” Zenodo, 2024. doi:10.5281/zenodo.13760911.
.. toctree::
diff --git a/docs/source/user_guide/geospatial-details/ds_res-gid-shape.svg b/docs/source/user_guide/geospatial-details/ds_res-gid-shape.svg
new file mode 100644
index 00000000..61bf52fe
--- /dev/null
+++ b/docs/source/user_guide/geospatial-details/ds_res-gid-shape.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/docs/source/user_guide/geospatial-details/ds_res-gid-time-shape.svg b/docs/source/user_guide/geospatial-details/ds_res-gid-time-shape.svg
new file mode 100644
index 00000000..a6e6f75a
--- /dev/null
+++ b/docs/source/user_guide/geospatial-details/ds_res-gid-time-shape.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/docs/source/user_guide/geospatial-details/geospatial-analysis-horizontal.svg b/docs/source/user_guide/geospatial-details/geospatial-analysis-horizontal.svg
new file mode 100644
index 00000000..5ad8e5c5
--- /dev/null
+++ b/docs/source/user_guide/geospatial-details/geospatial-analysis-horizontal.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/docs/source/user_guide/geospatial-details/geospatial-analysis-vertical.svg b/docs/source/user_guide/geospatial-details/geospatial-analysis-vertical.svg
new file mode 100644
index 00000000..8f7f82df
--- /dev/null
+++ b/docs/source/user_guide/geospatial-details/geospatial-analysis-vertical.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/docs/source/user_guide/geospatial-details/geospatial-analysis.svg b/docs/source/user_guide/geospatial-details/geospatial-analysis.svg
new file mode 100644
index 00000000..c46a4f80
--- /dev/null
+++ b/docs/source/user_guide/geospatial-details/geospatial-analysis.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/docs/source/user_guide/geospatial-details/meta_df.svg b/docs/source/user_guide/geospatial-details/meta_df.svg
new file mode 100644
index 00000000..3616b0f6
--- /dev/null
+++ b/docs/source/user_guide/geospatial-details/meta_df.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/docs/source/user_guide/geospatial-details/multi-dimensional-outputs.svg b/docs/source/user_guide/geospatial-details/multi-dimensional-outputs.svg
new file mode 100644
index 00000000..a03a2138
--- /dev/null
+++ b/docs/source/user_guide/geospatial-details/multi-dimensional-outputs.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/docs/source/user_guide/geospatial-details/weatherCube.svg b/docs/source/user_guide/geospatial-details/weatherCube.svg
new file mode 100644
index 00000000..31954545
--- /dev/null
+++ b/docs/source/user_guide/geospatial-details/weatherCube.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/docs/source/user_guide/geospatial-details/weatherSheet.svg b/docs/source/user_guide/geospatial-details/weatherSheet.svg
new file mode 100644
index 00000000..a494e827
--- /dev/null
+++ b/docs/source/user_guide/geospatial-details/weatherSheet.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/docs/source/user_guide/geospatial-details/weather_ds.svg b/docs/source/user_guide/geospatial-details/weather_ds.svg
new file mode 100644
index 00000000..952b465f
--- /dev/null
+++ b/docs/source/user_guide/geospatial-details/weather_ds.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/docs/source/user_guide/geospatial-templates.rst b/docs/source/user_guide/geospatial-templates.rst
deleted file mode 100644
index c19dead2..00000000
--- a/docs/source/user_guide/geospatial-templates.rst
+++ /dev/null
@@ -1,40 +0,0 @@
-.. _geospatial-templates:
-
-Geospatial Templates
-===================
-Using 3 dimensional labeled arrays (`Xarray`) we are able to run calculations using meteorological data across many points at once. This process has been parallelized using `dask` and `xarray`. Both of these packages can be run locally or on cloud HPC environments.
-
-This presents a new issue, our models produce outputs in many different shapes and sizes. We can have single numerical results, multiple numeric results or a timeseries of numeric results at each location. To parallelize this process, we cannot wait until runtime to know what shape to store the outputs in. This is where the need for `templates` arises.
-
-Previously, ``pvdeg.geospatial`` provided minimal templates and forced users to create their own for each function they wanted to use in a geospatial calculation.
-
-Auto-templating: allows users to skip creating templates for most functions within pvdeg by using ``pvdeg.geospatial.autotemplate`` to generate templates on the spot, instead of figuring out the output shape. For any given function within the source code decorated with `geospatial_result_type`, we can use `pvdeg.geospatial.autotemplate`
-
-
-Example
---------
-
-Here we are providing a function to autotemplate along with an ``Xarray.Dataset`` of weather data. Combining these two will give us enough information to produce an output template.
-
-Autotemplate approach to creating a template
-
-.. code-block:: Python
-
- edge_seal_template = pvdeg.geospatial.auto_template(
- func=pvdeg.design.edge_seal_width,
- ds_gids=geo_weather
- )
-
-Manual Approach to Creating the Sample Template
-
-.. code-block:: Python
-
- shapes = {
- "width" : ("gid",) # one return value at each datapoint, only dependent on datapoint, not time
- }
-
- template = pvdeg.geospatial.output_template(
- ds_gids=geo_weather, # xarray dataset
- shapes=shapes, # output shapes
- )
-
diff --git a/docs/source/user_guide/geospatial.rst b/docs/source/user_guide/geospatial.rst
new file mode 100644
index 00000000..43f86846
--- /dev/null
+++ b/docs/source/user_guide/geospatial.rst
@@ -0,0 +1,305 @@
+.. _geospatial:
+
+Geospatial
+==========
+
+Geospatial data is time based data that maps to a location on Earth. PVDeg supports single site and geospatial analyses using meteorological and solar radiation data,
+such as Typical meteorological year (TMY) data. This can be used to extrapolate the perfomance of PV systems over many years beacause it is statistically representative of
+weather conditions given a typical year. PVDeg collects an arbitrary amount of location specific meteorological and solar radiation data to run geospatial analyses.
+
+These datasets are multidimensional, with time and location as coordinates. These data come from :ref:`NSRDB` and :ref:`PVGIS` and can commonly be expressed in two ways.
+
+- three dimensions as a cube with coordinates ``time``, ``latitude``, and ``longitude``.
+- two dimensions as a sheet with coordinates ``time``, and ``location id`` (often represented as gid). Gid is a geospatial id, these are problematic and largely meaningless, see :ref:`GIDS`.
+
+.. image:: geospatial-details/weatherCube.svg
+ :width: 65%
+ :alt: multidimensional Meterological Solar Radiation data represented with dimensions time, latitude and longitude.
+
+.. image:: geospatial-details/weatherSheet.svg
+ :width: 50%
+ :alt: multidimensional Meterological Solar Radiation data represented with dimensions time, location id
+
+*The orange 3d shape and 2d band represent a single location's data, in the corresponding representation. This can be weather and solar radiation or other calculated results.*
+
+
+Geospatial Analysis
+-------------------
+
+To develop some intuition about what ``geospatial.analysis`` is doing lets examine the docstring. It says "applies a function to each gid of a weather dataset".
+This is a very simple message but it is not clear how this works at a cursory look. This is a powerful paradigm.
+
+The most consequential part of the function is the mapping from the inputs to the output. The input and outputs are multi-dimensional and have a different number of dimensions.
+
+*The specific function applied is not relevant at this point, it does change the data-variable results in the multi-dimensional output but this is a different aspect of the analysis function.*
+This is explained in `Geospatial Templates`_
+
+.. autofunction:: pvdeg.geospatial.analysis
+
+Multi-dimensional inputs
+^^^^^^^^^^^^^^^^^^^^^^^^
+- ``weather_ds`` is an ``xarray.Dataset`` with coordinates/dimensions of ``time`` and ``gid``.
+- ``meta_df`` is a ``pandas.DataFrame`` consisting of a row of data, extracting a single row yeilds a dictionary with metadata attributes for the specific location.
+
+Looking at ``weather_ds``, we generally want to get one of the tall rectangles shown in the figure. To do this we only need to index by ``gid``.
+This will get a "slice" that contains all of the weather data for that location for the length of the dataset (usually 1 year).
+This slice is roughly equivalent to the weather ``pandas.DataFrame`` taken by ``pvdeg`` functions called ``weather_df``.
+
+.. image:: geospatial-details/weather_ds.svg
+ :width: 50%
+ :alt:
+
+Looking at ``meta_df``, we want one of the wide rectangles shown in the figure. The dataframe is indexed by ``gid`` so we only need to index by a single ``gid``.
+This will get a "row" that contains the gid's meta data, such as latitude, longitude, time zone, and elevation/altitude.
+This can be unpacked to the standard python dictionary (``dict``) taken by ``pvdeg`` functions called ``meta_dict``.
+
+.. image:: geospatial-details/meta_df.svg
+ :width: 50%
+ :alt:
+
+In this context, gids serve purely as indexes, gid a in ``weather_ds`` coresponds to index a in ``meta_df``. No other information can be reliabily derived from gids.
+
+Multi-dimensional output
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+- ``ds_res`` is a ``xarray.Dataset`` with coordinates/dimensions of ``time``, ``latitude``, and ``longitude`` or simply ``latitude`` and ``longitude`` as shown below.
+
+Notice, ``ds_res`` is a multi-dimensional result similar to the inputs but it's shape can vary. The two standard appearances of ``ds_res`` are shown stacked on the right side of the figure below.
+
+The shape ``ds_res`` takes is determined by the provided function and template, ``func`` and ``template`` respectively. Oftentimes, ``template`` is not required because ``pvdeg``
+can automatically generate simple templates for commonly used builtin functions.
+
+When a function returns a timeseries result then the result will look like the cube version of ``ds_res`` with a time axis shown below.
+If the function returns single numeric results such as averages of a timeseries value then there is no need for a ``time`` axis. So the result will look like the plane version of ``ds_res`` shown below.
+For more on this see `Geospatial Templates`_.
+
+
+.. image:: geospatial-details/multi-dimensional-outputs.svg
+ :width: 100%
+ :alt:
+
+
+.. _GeospatialTemplates:
+Geospatial Templates
+---------------------
+Using multi-dimensional labeled arrays (``Xarray``) we are able to run calculations using meteorological data across many points at once. This process has been parallelized using `dask` and `xarray`. Both of these packages can be run locally or on cloud HPC environments.
+
+This presents a new issue, our models produce outputs in many different shapes and sizes. We can have single numerical results, multiple numeric results or a timeseries of numeric results at each location. To parallelize this process, we cannot wait until runtime to know what shape to store the outputs in. This is where the need for `templates` arises.
+
+Previously, ``pvdeg.geospatial`` provided minimal templates and forced users to create their own for each function they wanted to use in a geospatial calculation. This is still an option via ``geospatial.output_template``.
+But many pvdeg functions do not require a template for geospatial analysis.
+
+Auto-templating: allows users to skip creating templates for most ``pvdeg`` functions.
+It is integrated into ``geospatial.analysis``. If a function is defined with the ``@geospatial_quick_shape`` decorator in the source code, we can call ``geospatial.analysis`` without providing a template.
+The function responsible for this is called ``geospatial.auto_template`` and is exposed publicly to create templates outside of ``geospatial.analysis``.
+
+If a function cannot be auto-templated, both ``geospatial.analysis`` and ``geospatial.auto_template`` will raise the following error.
+
+.. code-block:: Python
+
+ " cannot be autotemplated. create a template manually"
+
+Auto-templating Example
+-----------------------
+
+The code below shows how to use auto-templating on a function implicitly. We simply call ``geospatial.analysis`` on a function that can be auto-templated and ``geospatial.analysis`` does the work for us.
+Note: *we do not need to provide a template to "analysis" if the function can be auto-templated*
+
+.. code-block:: Python
+
+ geo_res = pvdeg.geospatial.analysis(
+ weather_ds = geo_weather,
+ meta_df = geo_meta,
+ func = pvdeg.design.edge_seal_width,
+ )
+
+The code below shows the auto-templating process as the section above but this time we will explicitly call ``geospatial.auto_template`` and pass the generated template to ``geospatial.analysis``.
+The approach above is more direct and thus preferable.
+
+.. code-block:: Python
+
+ edge_seal_template = pvdeg.geospatial.auto_template(
+ func=pvdeg.design.edge_seal_width,
+ ds_gids=geo_weather
+ )
+
+ geo_res = pvdeg.geospatial.analysis(
+ weather_ds = geo_weather,
+ meta_df = geo_meta,
+ func = pvdeg.design.edge_seal_width,
+ template = edge_seal_template,
+ )
+
+
+
+Manual Templating Example I
+---------------------
+
+Creating manual templates is one of the most complicated parts of ``pvdeg``. We will use ``geospatial.output_template`` to tell ``pvdeg`` how to go from the multi-dimensional inputs to a multi-dimensional output.
+We have do to this because the dimensions are chaning. Refer to the sketch in `Multi-dimensional output`_.
+
+Lets examine some functions, comprehensive examples are the best way to illustrate this process.
+
+We will start by creating templates for functions that support auto-templating. If you run the code below or use the auto-templating approches shown above, the result will be identical.
+
+A simple function that has auto-templating is ``pvdeg.standards.standoff``. The docstring is shown below.
+
+.. autofunction:: pvdeg.standards.standoff
+
+We can see that this will return single numeric outputs for various aspects of standoff height calculation for each location. We want the output to rely only on the input location.
+This is identified with an index, ``gid``. Since we have single numeric outputs, we do not want a time dimension. Borrowing from above, a simple sketch of the analysis output should look like the following.
+
+.. image:: geospatial-details/ds_res-gid-shape.svg
+ :width: 100%
+ :alt:
+
+The crux of this process is defining the shapes dictionary. As presented above, we only care about the ``gid`` axis on the input so the process for creating a template and running the analysis with it will be as follows.
+The keys in the dictionary are named after the return values of the desired function. See the docstring for evidence of this. The values is a tuple of the dimensions that we map to in the output.
+
+.. code-block:: Python
+
+ shapes = {
+ "x": ("gid",),
+ "T98_inf": ("gid",),
+ "T98_0": ("gid",),
+ }
+
+*Note: the tuples appear with a comma after the string, such that ("gid",) NOT ("gid"). This is because python will interpret the string as an group of characters to unpack if we do not
+enforce the tuple requirement. Adding a comma forces python to interpret the parenthesis as a tuple*
+
+Next, we will create a template using this shapes dictionary and the ``weather_ds``. The parameters may be misleadly named as ``ds_gids`` but this is the same as ``weather_ds`` in ``geospatial.analysis``.
+
+``geo_weather`` and ``geo_meta`` are placeholders for the geospatial weather and metadata that we would generally have in this scenario. It is not possible to generate an output template without providing the
+geospatial weather data beacause the function needs to know how many entries it needs to make along the ``gid`` axis in this case.
+
+.. code-block:: Python
+
+ standoff_template = pvdeg.geospatial.output_template(
+ ds_gids=geo_weather, # geospatial xarray dataset
+ shapes=shapes, # output shapes defined above
+ )
+
+ geo_res = pvdeg.geospatial.analysis(
+ weather_ds = geo_weather, # geospatial xarray dataset
+ meta_df = geo_meta, # geospatial metadata dataframe
+ func = pvdeg.standards.standoff,
+ template = standoff_template # template created in this example
+ )
+
+
+Manual Templating Example II
+-----------------------------
+Another function we can look at that supports auto-templating is ``pvdeg.humidity.module``. This calculates module humidity parameters over a timeseries. This is where we diverge from the previous example.
+Inspect the docstring below and look at the return types, notice this will be a timeseries result.
+
+.. autofunction:: pvdeg.humidity.module
+
+Now we will define the shapes dictionary, the output will be a mapping from the input dimensions of ``gid`` and ``time`` so both of these will appear in our ``shapes`` value tuples.
+Thus our output will have a time axis and show look like the ``ds_res`` as a cube with the time axis as shown below.
+
+.. image:: geospatial-details/ds_res-gid-time-shape.svg
+ :width: 100%
+ :alt:
+
+This is an oversimplification but each column in the cube represets a ``pandas.DataFrame`` result with columns represeting each return value and a ``pd.DatetimeIndex``. The columns will be named as follows.
+
+- "RH_surface_outside"
+- "RH_front_encap"
+- "RH_back_encap"
+- "RH_backsheet"
+
+The docstring does not give us that much useful information about the results so we can run it on a single location and get the column names or dict keys then these will become our shape names.
+This is not ideal but simply running at a single site before a geospatial calculation can yield useful context. ``geospatial.analysis`` error messages are oftentimes clear.
+This is a result of dask, lazy-computing and confusing higher dimensional datasets.
+
+.. code-block:: Python
+
+ shapes = {
+ "RH_surface_outside": ("gid", "time"),
+ "RH_front_encap": ("gid", "time"),
+ "RH_back_encap": ("gid", "time"),
+ "RH_backsheet": ("gid", "time"),
+ }
+
+This shapes dictionary is valid, so we can pass it to ``geospatial.output_template`` as in the above example and run the analysis.
+
+.. code-block:: Python
+
+ module_humidity_template = pvdeg.geospatial.output_template(
+ ds_gids=geo_weather, # geospatial xarray dataset
+ shapes=shapes, # output shapes defined above
+ )
+
+ geo_res = pvdeg.geospatial.analysis(
+ weather_ds = geo_weather, # geospatial xarray dataset
+ meta_df = geo_meta, # geospatial metadata dataframe
+ func = pvdeg.module.humidity,
+ template = module_humidity_template # template created in this example
+ )
+
+
+Manual Templating Example III
+-----------------------------
+Last, lets look at another example. This one will be abridged as it covers the same topic as `Manual Templating Example II`_.
+
+This time consider ``pvdeg.letid.calc_letid_outdoors``. Lets inspect the docstring to see what the return values look like.
+
+.. autofunction:: pvdeg.letid.calc_letid_outdoors
+
+Once again we can see that the output shapes are obscured. It just says we are returning a ``pandas.DataFrame`` called timesteps. This is not helpful.
+We will have to run the function at a single location to see what the column names are.
+
+Assuming we ran ``pvdeg.letid.calc_letid_outdoors`` at a single site we would see that the DataFrame columns are named as follows.
+
+- "Temperature"
+- "Injection"
+- "NA"
+- "NB"
+- "NC"
+- "tau"
+- "Jsc"
+- "Voc"
+- "Isc"
+- "FF"
+- "Pmp"
+- "Pmp_norm"
+
+.. image:: geospatial-details/ds_res-gid-time-shape.svg
+ :width: 100%
+ :alt:
+
+Because we know the function returns a ``pandas.DataFrame`` with a time index, all of the columns will have entries at each timestep. This means that we need to include, the ``time`` dimension in our output.
+The shapes dictionary will look like the following. For visual assistance, refer to the cube shaped ``ds_res`` sketch.
+
+.. code-block:: Python
+
+ shapes = {
+ "Temperature": ("gid", "time"),
+ "Injection": ("gid", "time"),
+ "NA": ("gid", "time"),
+ "NB": ("gid", "time"),
+ "NC": ("gid", "time"),
+ "tau": ("gid", "time"),
+ "Jsc": ("gid", "time"),
+ "Voc": ("gid", "time"),
+ "Isc": ("gid", "time"),
+ "FF": ("gid", "time"),
+ "Pmp": ("gid", "time"),
+ "Pmp_norm": ("gid", "time"),
+ }
+
+Now we have defined shapes, as above we can simply pass it to ``geospatial.output_template`` and use the generated template in our analysis.
+
+.. code-block:: Python
+
+ letid_template = pvdeg.geospatial.output_template(
+ ds_gids=geo_weather, # geospatial xarray dataset
+ shapes=shapes, # output shapes defined above
+ )
+
+ geo_res = pvdeg.geospatial.analysis(
+ weather_ds = geo_weather, # geospatial xarray dataset
+ meta_df = geo_meta, # geospatial metadata dataframe
+ func = pvdeg.letid.calc_letid_outdoors
+ template = letid_template # template created in this example
+ )
\ No newline at end of file
diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst
index d4a4357b..40d06657 100644
--- a/docs/source/user_guide/index.rst
+++ b/docs/source/user_guide/index.rst
@@ -8,9 +8,11 @@ User Guide
installation
package_overview
+ meteorological-data
NSRDB_API_Key
montecarlo
- geospatial-templates
+ geospatial
+ materials
pv-variables-terms
contributing
diff --git a/docs/source/user_guide/materials.rst b/docs/source/user_guide/materials.rst
new file mode 100644
index 00000000..c81fa0e8
--- /dev/null
+++ b/docs/source/user_guide/materials.rst
@@ -0,0 +1,107 @@
+.. materials::
+
+Materials Storage and Access
+============================
+
+PVDeg contains a library of material parameters suitable for estimating the durability of materials and components.
+
+
+These material parameters and other relevant information sit in a directiory at ``PVDegradationTools/pvdeg/data``.
+
+This location can be quickly accessed through a special variable as shown below.
+
+.. code-block:: Python
+
+ import pvdeg
+
+ file_path = os.path.join(pvdeg.DATA_DIR, )
+
+.. code-block:: Python
+
+ from pvdeg import DATA_DIR
+
+ file_path = os.path.join(DATA_DIR, )
+
+File Organization
+------------------------------------
+There are many files in this directory. We will generally be interested in one of the following files.
+
+
+- `AApermeation.json `_ (acetic acid permeation parameters)
+- `H2Opermeation.json `_ (water permeation parameters)
+- `O2permeation.json `_ (oxygen permeation parameters)
+- kinetic_parameters.json (letid/bolid parameters)
+- DegradationDatabase.json (degredation models)
+
+Material Parameters
+------------------------------------
+Each of the material permeation parameters files above is a json indexed by arbitrary names.
+These are not a mapping of material names or aliases and are not consistent across the three files below.
+
+- `AApermeation.json `_ (acetic acid permeation parameters)
+- `H2Opermeation.json `_ (water permeation parameters)
+- `O2permeation.json `_ (oxygen permeation parameters)
+
+Accessing Material Parameters
+-----------------------------
+
+PVDeg provides convenience methods/functions to access material parameters. ``pvdeg.utilities.read_material`` is the simplest way to access material parameters. We will also show a sample use.
+
+.. autofunction:: pvdeg.utilities.read_material
+
+.. code-block:: Python
+
+ material_dict = pvdeg.utilities.read_material(
+ pvdeg_file = "AApermeation",
+ key = "AA001",
+ )
+
+.. code-block:: Python
+
+ material_dict = pvdeg.utilities.read_material(
+ pvdeg_file = "H2Opermeation",
+ key = "W003",
+ )
+
+
+The result of both of these functions will be a dictionary that looks like the following. The keys may vary depending on the structure of the json but this is the general idea.
+
+.. code-block:: Python
+
+ {
+ "name": string,
+ "alias": string,
+ "contributor": string,
+ "source": string,
+ "Fickian": bool,
+ "Ead": numeric,
+ "Do": numeric,
+ "Eas": numeric,
+ "So": numeric,
+ "Eap": numeric,
+ "Po": numeric
+ }
+
+There are also convenience functions to view and search jsons in jupyter notebooks called ``pvdeg.utilities.display_json`` and ``pvdeg.utilities.search_json``.
+
+
+.. _AApermeation:
+
+AApermeation
+~~~~~~~~~~~~
+.. literalinclude:: ../../../pvdeg/data/AApermeation.json
+ :language: json
+
+.. _H2Opermeation:
+
+H2Opermeation
+~~~~~~~~~~~~
+.. literalinclude:: ../../../pvdeg/data/H2Opermeation.json
+ :language: json
+
+.. _O2permeation:
+
+O2permeation
+~~~~~~~~~~~~
+.. literalinclude:: ../../../pvdeg/data/O2permeation.json
+ :language: json
\ No newline at end of file
diff --git a/docs/source/user_guide/meteorological-data-details/data_flow_chart.png b/docs/source/user_guide/meteorological-data-details/data_flow_chart.png
new file mode 100644
index 00000000..7b19bd4e
Binary files /dev/null and b/docs/source/user_guide/meteorological-data-details/data_flow_chart.png differ
diff --git a/docs/source/user_guide/meteorological-data-details/nsrdb_global_coverage.jpg b/docs/source/user_guide/meteorological-data-details/nsrdb_global_coverage.jpg
new file mode 100644
index 00000000..dee1cc68
Binary files /dev/null and b/docs/source/user_guide/meteorological-data-details/nsrdb_global_coverage.jpg differ
diff --git a/docs/source/user_guide/meteorological-data.rst b/docs/source/user_guide/meteorological-data.rst
new file mode 100644
index 00000000..6132a119
--- /dev/null
+++ b/docs/source/user_guide/meteorological-data.rst
@@ -0,0 +1,80 @@
+.. _meteorological-data:
+
+Meterological Data
+==================
+
+PVDeg seeks to automate the tedious parts of degradation analysis by providing simple tools to work with weather data.
+``pvdeg.weather.get`` seeks to unify this functionality into a simple function.
+
+The PVDeg tutorials and examples use two datasets, `NSRDB`_ and `PVGIS`_. These are serially complete data including meteorological data and solar radiation (irradiance) measurements.
+The methodology for these datasets varies but both are gridded geospatial datasets with similar attributes.
+
+.. _NSRDB:
+NSRDB
+------
+The NSRDB is produced by NREL and combines multiple datasets but we are most concerned with `Physical Solar Model 3 (PSM3) `_. This data was generated using satellite data from multiple channels to derive cloud
+and aerosol properties, then fed into a radiative transfer model. Learn more about the NSRDB `here `_.
+
+The NSRDB is free to use but requires an api-key and email. See :ref:`NSRDB_API_Key` for more information.
+For our purposes, the api is limited to 1000 requests per day, although you can request a batch download via email with a singificantly higher rate limit (not recommended for PVDeg).
+
+Flowchart showing the dataflow from satellite to solar radiation measurement.
+
+.. image:: meteorological-data-details/data_flow_chart.png
+ :alt: dataflow from satellite to solar radiation measurement, image missing
+
+``_
+
+NSRDB data are seperated by satellite/model source. Each dataset is shown below, much of the PVDeg project uses the *Americas* data.
+
+.. image:: meteorological-data-details/nsrdb_global_coverage.jpg
+ :alt: NSRDB data sources, image missing
+
+``_
+
+
+.. _PVGIS:
+PVGIS
+------
+`PVGIS`_ is the European counterpart of the `NSRDB`_. The data was sourced similarly. With PVGIS we are most concerned with a `typical meteorological year `_.
+PVDeg uses utilities built in `pvlib `_ to access the data.
+
+PVGIS is free to use and does NOT require an api-key. It has a rate limit of 30 requests per second and covers a much larger range of longitudes and latitudes.
+
+The PVDeg tutorials and examples use two datasets, `NSRDB`_ and `PVGIS`_. These are serially complete data including meteorological data and solar radiation (irradiance) measurements.
+The methodology for these datasets varies but both are gridded geospatial datasets with similar attributes.
+
+PVGIS data are seperated by satellite/model source. Visit the links below for more information about the datasets.
+
+- `PVGIS 5.2 `_
+- `PVGIS 5.3 `_
+
+.. _GIDS:
+Issues with Gids
+----------------
+
+"Gids", plural or "gid" singular refer to a geospatial id. This is where the simplicity ends because gids are largely meaningless.
+
+When using ``pvdeg.weather.get`` to grab PVGIS data as follows. We will get a gid back but it will always be the same because PVGIS gids are meaningless. The gids created during this process only serve as indexes.
+
+.. code-block:: Python
+
+ weather_df, meta_df = pvdeg.weather.get(
+ database="PVGIS",
+ id = (, ),
+ )
+
+
+When using the NSRDB PSM3 dataset, gids are unique only to their satellite. Because of this, gids can only be treated as unique if we can guarantee only one satellite source is being utilized.
+This is possible but causes headaches.
+
+.. code-block:: Python
+
+ weather_df, meta_df = pvdeg.weather.get(
+ database="PSM3",
+ id = (, ),
+ email = ,
+ api_key = ,
+ )
+
+Takeaway: gids are not unique or necessarily meaningful, be careful when using them. Duplicate gids can exist in geospatial data and will be loaded using Xarray without raising an error.
\ No newline at end of file
diff --git a/docs/source/whatsnew/index.rst b/docs/source/whatsnew/index.rst
index 8298a18d..d5b2f041 100644
--- a/docs/source/whatsnew/index.rst
+++ b/docs/source/whatsnew/index.rst
@@ -4,6 +4,7 @@ What's New
==========
PVDegradationTools (pvdeg) change log:
+.. include:: releases/v0.4.4.rst
.. include:: releases/v0.4.3.rst
.. include:: releases/v0.4.2.rst
.. include:: releases/v0.4.1.rst
diff --git a/docs/source/whatsnew/releases/v0.4.4.rst b/docs/source/whatsnew/releases/v0.4.4.rst
new file mode 100644
index 00000000..c2296037
--- /dev/null
+++ b/docs/source/whatsnew/releases/v0.4.4.rst
@@ -0,0 +1,12 @@
+v0.4.4 (2024-11-19)
+===================
+
+Enhancements
+------------
+* Documenation overhaul. Significant ``User Guide`` improvements. Added geospatial information with visual aids, added meteorological data page and materials access page.
+Suite of utility functions to facilitate accessing material parameter json files.
+* New Logo!
+
+Contributors
+-----------
+* Tobin Ford (:ghuser:`tobin-ford`)
\ No newline at end of file
diff --git a/tutorials_and_tools/tutorials_and_tools/Tools - Module Standoff for IEC TS 63126.ipynb b/tutorials_and_tools/tutorials_and_tools/Tools - Module Standoff for IEC TS 63126.ipynb
index a88a81a7..9f8e068a 100644
--- a/tutorials_and_tools/tutorials_and_tools/Tools - Module Standoff for IEC TS 63126.ipynb
+++ b/tutorials_and_tools/tutorials_and_tools/Tools - Module Standoff for IEC TS 63126.ipynb
@@ -577,7 +577,7 @@
"metadata": {},
"outputs": [],
"source": [
- "geospatial_standoff_scenario = pvdeg.scenario.Geospatial_Scenario(\n",
+ "geospatial_standoff_scenario = pvdeg.Geospatial_Scenario(\n",
" name='standoff geospatial',\n",
" geospatial = True,\n",
") "