Merge pull request #25 from jbisits/joey-exampleandreadme

Joey update the example and the README

Project.toml

@@ -1,7 +1,7 @@
 name = "OceanRasterConversions"
 uuid = "07ff2621-03e0-4bfb-9812-e5d28c6dbff8"
 authors = ["Josef I. Bisits <[email protected]>"]
-version = "0.2.0"
+version = "0.2.1"
 
 [deps]
 GibbsSeaWater = "9a22fb26-0b63-4589-b28e-8f9d0b5c3d05"

README.md

@@ -4,6 +4,26 @@
 [![Build Status](https://github.com/jbisits/OceanRasterConversions.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/jbisits/OceanRasterConversions.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![codecov](https://codecov.io/gh/jbisits/OceanRasterConversions.jl/branch/main/graph/badge.svg?token=XEAWB8IHFV)](https://codecov.io/gh/jbisits/OceanRasterConversions.jl)
 
-This package converts ocean varaibles that are saved as `Raster` data structures using [GibbsSeaWater.jl](https://github.com/TEOS-10/GibbsSeaWater.jl).
+This package converts and computes ocean varaibles that are saved as `Raster` data structures using [GibbsSeaWater.jl](https://github.com/TEOS-10/GibbsSeaWater.jl).
 [Rasters.jl](https://github.com/rafaqz/Rasters.jl) provides excellent reading, writing and manipulation of geospatial data.
 Typically, the salt and temperature variables from ocean models or observational data are practical salinity and potential temperature so conversions must be to the TEOS-10 standard variables of absolute salinity and conservative temperature to accurately calculate further variables like seawater density.
+
+## Using the package
+
+The package is installed using Julia's package manager
+
+```julia
+julia> ]
+(@v1.8) pkg> add OceanRasterConversions
+```
+
+then press `backspace` to exit the package manager.
+To start using the package you will also need to have [Rasters.jl](https://github.com/rafaqz/Rasters.jl) installed (in the same manner as above but replace `OceanRasterConversions` with `Rasters`).
+To then use the packages type
+
+```julia
+julia> using Rasters, OceanRasterConversions
+```
+
+into the repl.
+To see a list of the exported functions from OceanRasterConversions.jl see the [documnetation](https://jbisits.github.io/OceanRasterConversions.jl/dev/#Functions-exported-from-OceanRasterConversions).

docs/src/index.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-This package converts ocean varaibles that are saved as `Raster` data structures using [GibbsSeaWater.jl](https://github.com/TEOS-10/GibbsSeaWater.jl).
+This package converts and computes ocean varaibles that are saved as `Raster` data structures using [GibbsSeaWater.jl](https://github.com/TEOS-10/GibbsSeaWater.jl).
 [Rasters.jl](https://github.com/rafaqz/Rasters.jl) provides excellent reading, writing and manipulation of geospatial data.
 Typically, the salt and temperature variables from ocean models or observational data are practical salinity and potential temperature so conversions must be to the TEOS-10 standard variables of absolute salinity and conservative temperature to accurately calculate further variables like seawater density.
 
@@ -39,7 +39,9 @@ Currently the varabile symbols are:
 - `Sₐ` absolute salinity
 - `p` pressure
 - `ρ` in-situ seawater density
-- `σₚ` potential density at user defined reference pressure `ₚ`.
+- `σₚ` potential density at user defined reference pressure `ₚ`
+- `α` thermal expansion coefficient
+- `β` haline contraction coefficient.
 
 ### Limitations
 
@@ -67,4 +69,6 @@ Sₚ_to_Sₐ
 θ_to_Θ
 get_ρ
 get_σₚ
+get_α
+get_β
 ```

examples/ECCO_example.jl

@@ -16,22 +16,46 @@ metadata(stack)["summary"]
 # This tells us that the temperature variable is potential temperature and the salt
 # variabile is practical salinity (for more information about this data see the user guide).
 #
-# ## Converting variables and plotting
-# To calculate seawater density using TEOS-10, we require absolute salinity and
-# conservative temperature. This can be done by extracting the data and using
+# ## Converting all variables and plotting
+# To calculate seawater density using TEOS-10, we require absolute salinity, conservative
+# temperature and pressure. This can be done by extracting the data and using
 # [GibbsSeaWater.jl](https://github.com/TEOS-10/GibbsSeaWater.jl) or with this package,
 converted_stack = convert_ocean_vars(stack, (Sₚ = :SALT, θ = :THETA))
 
 # Note that this is a new `RasterStack`, so the metadata from the original `RasterStack` is
 # not attached. As we have a returned `RasterStack` and plotting recipes have been written,
-# we can then take slices of the data to look at depth-latitude plots of the returned
-# variables (note by defaul the in-situ density ρ is computed and returned)
+# we can, for example, look at the conservative temperature closest to the sea-surface (-5.0m)
+contourf(converted_stack[:Θ][Z(Near(0.0))]; color = :balance, colorbar_title = "ᵒC")
+
+# We can also take slices of the data to look at depth-latitude plots of the returned
+# variables (note by default the in-situ density `ρ` is computed and returned)
 lon = 180
-var_plots = plot(; layout = (4, 1), size = (900, 1000))
+var_plots = plot(; layout = (4, 1), size = (1000, 1000))
 for (i, key) ∈ enumerate(keys(converted_stack))
     contourf!(var_plots[i], converted_stack[key][X(Near(lon))])
 end
 var_plots
 # As this is a `RasterStack` all methods exported by Rasters.jl will work. See the
 # [documentation for Rasters.jl](https://rafaqz.github.io/Rasters.jl/stable/#Rasters.jl)
 # for more information.
+
+# ## Converting chosen variables
+# It is also possible to convert only chosen variables from a `RasterStack`. If we just want
+# to look at temperature-salinity vertical profiles, we can convert the practical salinity
+# and conservative temperature then extact vertical profiles and compute the potential
+# density referenced to 0dbar
+Sₐ = Sₚ_to_Sₐ(stack, :SALT)
+Θ = θ_to_Θ(stack, (Sₚ = :SALT, θ = :THETA))
+lon, lat = -100.0, -70.0
+Sₐ_profile, Θ_profile = Sₐ[X(Near(lon)), Y(Near(lat)), Ti(1)],
+                         Θ[X(Near(lon)), Y(Near(lat)), Ti(1)]
+σ₀_profile = get_σₚ(Sₐ_profile, Θ_profile, 0)
+profile_plots = plot(; layout = (2, 2), size = (800, 800))
+plot!(profile_plots[1, 1], Sₐ_profile;
+      title = "Sₐ-depth", xmirror = true, xlabel = "Sₐ (g/kg)")
+plot!(profile_plots[1, 2], Θ_profile;
+      title = "Θ-depth", xmirror = true, xlabel = "Θ (ᵒC)")
+plot!(profile_plots[2, 1], Sₐ_profile, Θ_profile;
+      xlabel = "Sₐ (g/kg)", ylabel = "Θ (ᵒC)", label = false, title = "Sₐ-Θ")
+plot!(profile_plots[2, 2], σ₀_profile;
+      title = "σ₀-depth", xmirror = true, xlabel = "σ₀ (kgm⁻³)")

src/oceanconversions.jl

@@ -221,7 +221,7 @@ get_ρ(stack::RasterStack, var_names::NamedTuple) = get_ρ(stack[var_names.Sₐ]
 get_ρ(series::RasterSeries, var_names::NamedTuple) = get_ρ.(series, Ref(var_names))
 
 """
-    function get_σₚ(Sₐ::Raster, Θ::Raster, p::Float64)
+    function get_σₚ(Sₐ::Raster, Θ::Raster, p::Number)
     function get_σₚ(stack::RasterStack, var_names::NamedTuple)
     function get_σₚ(series::RasterStack, var_names::NamedTuple)
 Compute potential density at reference pressure `p`, `σₚ`, using `gsw_rho`
@@ -316,8 +316,7 @@ get_β(series::RasterSeries, var_names::NamedTuple) = get_β.(series, Ref(var_na
 
 """
     function get_dims(raster::Raster)
-    function get_dims(stack::RasterStack)
-Get the dimensions of a `Raster` or `RasterStack`.
+Get the dimensions of a `Raster`.
 """
 function get_dims(raster::Raster)
 
@@ -326,7 +325,7 @@ function get_dims(raster::Raster)
                 dims(raster, Z), dims(raster, Ti))
               elseif !hasdim(raster, X)
                 throw(ArgumentError(
-                "To computes the absolute salinity variable the longitude dimension, `X`, is required."))
+                "To compute the absolute salinity variable the longitude dimension, `X`, is required."))
               elseif !hasdim(raster, Y)
                 throw(ArgumentError(
                 "To compute the pressure variable the latitude dimension,`Y`, is required."))