docs: Usage examples

.gitignore

@@ -1 +1,2 @@
 Manifest*.toml
+data/

Project.toml

@@ -23,7 +23,7 @@ YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
 
 # TODO: Remove after https://github.com/JuliaIO/FileIO.jl/pull/427
 [sources]
-FileIO = {url = "https://github.com/icweaver/FileIO.jl", rev = "asdf"}
+FileIO = {url = "https://github.com/JuliaIO/FileIO.jl", rev = "master"}
 
 [compat]
 AbstractTrees = "0.4.5"

README.md

@@ -10,4 +10,27 @@
 
 A new [Advanced Scientific Data Format (ASDF)](https://asdf-standard.readthedocs.io/en/latest/index.html) package, written in Julia.
 
+## Quickstart
+
+```julia
+using ASDF
+```
+
+```julia
+# Load
+af = ASDF.load_file("<file.asdf>")
+```
+
+```julia
+# Acess and modify
+af.metadata["<key>"] = <val>
+```
+
+```julia
+# Write
+doc = Dict(<data>)
+ASDF.write_file("<new_file.asdf>", doc)
+```
+
+=======
 See [`ASDF.jl v1`](https://github.com/JuliaAstro/ASDF.jl/tree/v1) for the older one which is based on the Python [`asdf`](https://github.com/spacetelescope/asdf) Python package.

docs/Project.toml

@@ -1,6 +1,11 @@
 [deps]
 ASDF = "686f71d1-807d-59a4-a860-28280ea06d7b"
+AWS = "fbe9abb3-538b-5e4e-ba9e-bc94f4f92ebc"
+AWSS3 = "1c724243-ef5b-51ab-93f4-b0a88ac62a95"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
+OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
 
 [compat]
 Documenter = "1"

docs/make.jl

@@ -8,9 +8,17 @@ makedocs(;
     repo = GitHub("JuliaAstro/ASDF.jl"),
     sitename = "ASDF.jl",
     format = Documenter.HTML(
-        prettyurls = true,
         canonical = "https://juliaastro.org/ASDF/stable/",
     ),
+    pages = [
+        "Home" => "index.md",
+        "Introduction" => "intro.md",
+        "Examples" => [
+            "JWST" => "examples/jwst.md",
+            "Roman" => "examples/roman.md",
+    ],
+        "API" => "api.md",
+    ],
     doctest = false,
 )
 

docs/src/api.md

@@ -0,0 +1,14 @@
+# API
+
+## Public
+
+```@autodocs
+Modules = [ASDF]
+Private = false
+```
+
+## Private
+```@autodocs
+Modules = [ASDF]
+Public = false
+```

docs/src/examples/jwst.md

@@ -0,0 +1,54 @@
+# JWST
+
+*Adapted from [ADASS 2024 workshop](https://github.com/asdf-format/asdf-adass2024/blob/main/02_working_with_asdf/Working_with_ASDF.ipynb).*
+
+In this example, we show how to use ASDF.jl to load and view some astronomical data taken from the James Webb Space Telescope ([JWST](https://science.nasa.gov/mission/webb/)).
+
+!!! note "Data availability"
+    The sample data for this example can be [downloaded here](https://data.science.stsci.edu/redirect/Roman/Roman_Data_Workshop/ADASS2024/jwst.asdf) from the data repository of the Space Telescope Science Institute ([STScI](https://www.stsci.edu/)). Note: it is a moderately large file (~100 MB).
+
+## Load
+
+```@repl jwst
+
+fpath = let
+    data_dir = joinpath("..", "..", "data")
+    mkpath(data_dir)
+    joinpath(data_dir, "jwst.asdf")
+end;
+
+if !isfile(fpath)
+    using Downloads: download
+
+    download("https://data.science.stsci.edu/redirect/Roman/Roman_Data_Workshop/ADASS2024/jwst.asdf", fpath)
+end
+```
+
+```@repl jwst
+using ASDF
+
+af = load(fpath; extensions = true)
+```
+
+## Plot
+
+```@example jwst
+using CairoMakie
+
+img_sci = let
+    img = af["data"][]
+    img[img .< 0] .= 1
+    img
+end
+
+fig, ax, hm = heatmap(img_sci;
+    colorrange = (1, 1e3),
+    colorscale = log10,
+    colormap = :cividis,
+    nan_color = :limegreen, # NaNs are handled automatically
+)
+
+Colorbar(fig[1, 2], hm)
+
+fig
+```

docs/src/examples/roman.md

@@ -0,0 +1,55 @@
+# Roman
+
+*Adapted from [STScI Roman Notebooks](https://spacetelescope.github.io/roman_notebooks/notebooks/working_with_asdf/working_with_asdf.html).*
+
+In this example, we show how to use ASDF.jl to load and view some simulated astronomical data created in preparation for the future ([Nancy Grace Roman Space Telescope](https://science.nasa.gov/mission/roman-space-telescope/)) mission.
+
+!!! note "Data availability"
+    Simulated data products are currently provided by STScI via [AWS S3 buckets](https://spacetelescope.github.io/roman_notebooks/notebooks/data_discovery_and_access/data_discovery_and_access.html). Note: The data product used for this example is a moderately large file (~300 MB).
+
+## Load
+
+```@repl roman
+fpath = let
+    data_dir = joinpath("..", "..", "data")
+    mkpath(data_dir)
+    joinpath(data_dir, "roman.asdf")
+end;
+
+if !isfile(fpath)
+    using AWSS3, AWS
+    aws_config = AWS.AWSConfig(; creds = nothing, region = "us-east-1")
+    AWSConfig(nothing, "us-east-1", "json", 3)
+
+    # This is a large file, will take some time to download
+    s3_get_file(
+        aws_config,
+        "stpubdata",
+        "roman/nexus/soc_simulations/tutorial_data/r0003201001001001004_0001_wfi01_f106_cal.asdf",
+        fpath
+    )
+end
+```
+
+```@repl roman
+using ASDF
+
+af = load(fpath; extensions = true, validate_checksum = false)
+```
+
+## Plot
+
+```@example roman
+using CairoMakie
+
+img = af["roman"]["data"][]
+
+fig, ax, hm = heatmap(img[begin:1000, begin:1000]; colorscale = asinh, colorrange = (0.5, 4))
+
+Colorbar(fig[1, 2], hm)
+
+fig
+```
+
+!!! note
+    Some ASDF files produced by the Python implementation of ASDF may save a checksum in its header block computed from the original decompressed file. This will cause ASDF.jl to fail because in constrast, it computes the checksum based on the compressed (i.e., "used data"), as per the [current specification for ASDF](https://www.asdf-format.org/projects/asdf-standard/en/1.0.1/file_layout.html#block-header). To handle this potenial failure mode, we pass `validate_checksum = false` to avoid running the default checksum.

docs/src/index.md

@@ -1,5 +1,34 @@
 # ASDF.jl
 
-```@autodocs
-Modules = [ASDF]
+A new [Advanced Scientific Data Format (ASDF)](https://asdf-standard.readthedocs.io/en/latest/index.html) package, written in Julia.
+
+
+## Quickstart
+
+
+### Installation
+
+```julia-repl
+pkg> add ASDF, OrderedCollections
+```
+
+### Usage
+
+```@repl
+using ASDF, OrderedCollections
+
+doc = OrderedDict(
+    "field_1" => [5, 6, 7, 8],
+    "field_2" => ["up", "down", "left", "right"],
+    "field_3" => OrderedDict(
+        "field_3a" => ["apple", "orange", "pear"],
+        "field_3b" => [1.0, 2.0, 3.0],
+    )
+);
+
+save("example.asdf", doc)
+
+af = load("example.asdf")
+
+ASDF.info(af; max_rows = 3)
 ```