Merge pull request #9 from PALEOtoolkit/doc_update

update documentation

Project.toml

@@ -1,7 +1,7 @@
 name = "PALEOmodel"
 uuid = "bf7b4fbe-ccb1-42c5-83c2-e6e9378b660c"
 authors = ["Stuart Daines <[email protected]>"]
-version = "0.14.6"
+version = "0.14.7"
 
 [deps]
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"

docs/make.jl

@@ -17,7 +17,8 @@ makedocs(bib, sitename="PALEOmodel Documentation",
                 "HOWTOsmallnegativevalues.md",
             ],
             "Reference" => [
-                "PALEOmodel.md",
+                "PALEOmodelSolvers.md",
+                "PALEOmodelOutput.md",
             ],
             "References.md",
             "indexpage.md",

docs/src/HOWTOshowmodelandoutput.md

@@ -70,11 +70,11 @@ To show linkage of a ReactionMethod Variable with localname "pO2PAL", Reaction "
 
 ## Display model output
 
-Model output is stored in a [`PALEOmodel.OutputWriters.OutputMemory`](@ref) object, which is
+Model output is stored in a [`PALEOmodel.AbstractOutputWriter`](@ref) object, which is
 available as `run.output`, ie the `output` field of the default [`PALEOmodel.Run`](@ref) instance created
 by the `COPSE_reloaded_reloaded.jl` script.
 
-[`PALEOmodel.OutputWriters.OutputMemory`](@ref) stores model output by Domain:
+The default [`PALEOmodel.OutputWriters.OutputMemory`](@ref) stores model output in memory, by Domain:
 
     julia> run.output  # shows Domains
 
@@ -111,17 +111,54 @@ Raw data arrays can also be accessed as Julia Vectors using `get_data`:
 
 ## Plot model output
 
-The output can be plotted using the Julia Plots.jl package. Plot recipes are defined for [`PALEOmodel.FieldArray`](@ref), 
-so output data can be plotted directly:
+The output can be plotted using the Julia Plots.jl package, see [Plotting output](@ref). Plot recipes are defined for [`PALEOmodel.FieldArray`](@ref), so output data can be plotted directly using the `plot` command:
 
     julia> using Plots
     julia> plot(run.output, "atm.pCO2atm")  # plot output variable as a single command
     julia> plot(pCO2atm) # a PALEOmodel.FieldArray can be plotted
     julia> plot!(tmodel_raw, pCO2atm_raw, label="some raw data") # overlay data from standard Julia Vectors
 
-## Spatial output
+## Spatial or wavelength-dependent output
 
-TODO - key point is that [`PALEOmodel.FieldArray`](@ref) includes coordinates to plot column and image data.
+To analyze spatial or eg wavelength-dependent output (eg time series from a 1D column or 3D general circulation model, or quantities that are a function of wavelength or frequency), [`PALEOmodel.get_array`](@ref) takes additional arguments to take 1D or 2D slices from the spatial, spectral and timeseries data. The [`PALEOmodel.FieldArray`](@ref) returned includes coordinates to plot column (1D) and heatmap (2D) data.
+
+### Examples for a column-based model
+
+Visualisation of spatial and wavelength-dependent output from the PALEOdev.jl ozone photochemistry example (a single 1D atmospheric column):
+
+#### 1D column data
+    julia> plot(title="O3 mixing ratio", output, "atm.O3_mr", (tmodel=[0.0, 0.1, 1.0, 10.0, 100.0, 1000.0], column=1),
+                swap_xy=true, xaxis=:log, labelattribute=:filter_records) # plots O3 vs height
+
+Here the `labelattribute=:filter_records` keyword argument is used to generate plot labels from the `:filter_records` FieldArray attribute, which contains the `tmodel` values used to select the timeseries records.  The plot recipe expands
+the Vector-valued `tmodel` argument to overlay a sequence of plots.
+
+This is equivalent to first creating and then plotting a sequence of `FieldArray` objects:
+
+    julia> O3_mr = PALEOmodel.get_array(run.output, "atm.O3_mr", tmodel=0.0, column=1)
+    julia> plot(title="O3 mixing ratio", O3_mr, swap_xy=true, xaxis=:log, labelattribute=:filter_records)
+    julia> O3_mr = PALEOmodel.get_array(run.output, "atm.O3_mr", tmodel=0.1, column=1)
+    julia> plot!(O3_mr, swap_xy=true, labelattribute=:filter_records)
+
+#### Wavelength-dependent data
+    julia> plot(title="direct transmittance", output, ["atm.direct_trans"], (tmodel=1e12, column=1, cell=[1, 80]),
+                ylabel="fraction", labelattribute=:filter_region) # plots vs wavelength
+
+Here `tmodel=1e12` selects the last model time output, and `column=1, cell=[1, 80]` selects the top and bottom cells within the first (only) 1D column. The `labelattribute=:filter_region` keyword argument is used to generate plot labels from the `:filter_region` FieldArray attribute, which contains the `column` and `cell` values used to select the spatial region.
+
+### Examples for a 3D GCM-based model
+
+Visualisation of spatial output from the 3D GENIE transport-matrix example (PALEOdev.jl repository)
+
+### Horizontal slices across levels
+    julia> heatmap(run.output, "ocean.O2_conc", (tmodel=1e12, k=1), swap_xy=true)
+
+Here `k=1` selects a horizontal level corresponding to model grid cells with index k=1, which is the ocean surface in the GENIE grid.
+
+### Vertical section at constant longitude
+    julia> heatmap(run.output, "ocean.O2_conc", (tmodel=1e12, i=10), swap_xy=true, mult_y_coord=-1.0)
+
+Here `i=10` selects a section at longitude corresponding to model grid cells with index i=10.
 
 ## Save and load output
 

docs/src/PALEOmodelOutput.md

@@ -0,0 +1,112 @@
+
+
+# PALEOmodel output
+
+## Run
+
+```@meta
+CurrentModule = PALEOmodel
+```
+```@docs
+Run
+```
+
+## Output
+PALEO model output is accumulated into a container such as an [OutputMemory](@ref) instance that implements the [AbstractOutputWriter interface](@ref).
+
+### AbstractOutputWriter interface
+
+```@meta
+CurrentModule = PALEOmodel
+```
+```@docs
+AbstractOutputWriter
+```
+
+```@meta
+CurrentModule = PALEOmodel.OutputWriters
+```
+#### Writing output
+```@docs
+initialize!
+add_record!
+```
+#### Modifying output
+```@docs
+PB.add_field!(output::PALEOmodel.AbstractOutputWriter, fr::PALEOmodel.FieldRecord) 
+```
+#### Querying output
+```@docs
+PB.get_table(output::PALEOmodel.AbstractOutputWriter, domainname::AbstractString)
+PB.show_variables(output::PALEOmodel.AbstractOutputWriter)
+PB.has_variable(output::PALEOmodel.AbstractOutputWriter, varname::AbstractString)
+```
+
+#### Accessing output data
+```@docs
+PALEOmodel.get_array(output::PALEOmodel.AbstractOutputWriter, varname::AbstractString; kwargs...)
+PB.get_field(output::PALEOmodel.AbstractOutputWriter, varname::AbstractString)
+PB.get_data(output::PALEOmodel.AbstractOutputWriter, varname::AbstractString; records=nothing)
+PB.get_mesh(output::PALEOmodel.AbstractOutputWriter, domainname::AbstractString)
+```
+```@meta
+CurrentModule = PALEOmodel
+```
+```@docs
+FieldRecord
+```
+
+### OutputMemory
+
+```@meta
+CurrentModule = PALEOmodel.OutputWriters
+```
+```@docs
+OutputMemory
+OutputMemoryDomain
+save_jld2
+load_jld2!
+```
+
+## Field Array
+
+```@meta
+CurrentModule = PALEOmodel
+```
+[`FieldArray`](@ref) provides a generic array type with named dimensions `PALEOboxes.NamedDimension` and optional coordinates `PALEOboxes.FixedCoord` for processing of model output.
+
+```@docs
+FieldArray
+get_array(f::PB.Field{D, PB.ScalarSpace, V, N, M}; attributes=nothing) where {D, V, N, M}
+```
+
+## Plotting output
+
+### Plot recipes
+Plotting using the Julia [Plots.jl](https://github.com/JuliaPlots/Plots.jl) package is implemented by [plot recipes](https://docs.juliaplots.org/latest/recipes/) that enable plotting of PALEO data types using the `plot` command.
+
+The general principles are that:
+- Data is extracted from model output into [`FieldArray`](@ref)s with attached coordinates
+- Vector-valued arguments are "broadcast" to allow multiple line plot series to be overlaid in a single plot panel
+
+```@meta
+CurrentModule = PALEOmodel
+```
+```@docs
+RecipesBase.apply_recipe(::Dict{Symbol, Any}, output::AbstractOutputWriter, vars::Union{AbstractString, Vector{<:AbstractString}}, selectargs::NamedTuple)
+RecipesBase.apply_recipe(::Dict{Symbol, Any}, fr::FieldRecord, selectargs::NamedTuple)
+RecipesBase.apply_recipe(::Dict{Symbol, Any}, fa::FieldArray)
+```
+### Assembling multi-plot panels
+```@docs
+PlotPager
+DefaultPlotPager
+```
+
+## Analyze reaction network
+```@meta
+CurrentModule = PALEOmodel
+```
+```@docs
+ReactionNetwork
+```