Add Var.set_units

Author: ph-kev

NEWS.md

@@ -1,5 +1,19 @@
 ClimaAnalysis.jl Release Notes
 ===============================
+v0.5.10
+-------
+
+## Features
+
+### Set units
+
+You can now set units for a `OutputVar`. This is useful if you need to change the name of
+the units or units are missing.
+
+```julia
+new_var = ClimaAnalysis.set_units(var, "kg m s^-1")
+```
+
 
 v0.5.9
 ------

docs/src/api.md

@@ -57,6 +57,7 @@ Var.range_dim
 Var.reordered_as
 Var.resampled_as
 Var.convert_units
+Var.set_units
 Var.integrate_lonlat
 Var.integrate_lat
 Var.integrate_lon

docs/src/var.md

@@ -55,6 +55,14 @@ new_var = ClimaAnalysis.convert_units(var, "kg m/s", conversion_function = (x) -
 
 !!! note If you find some unparseable units, please open an issue. We can fix them!
 
+If units do not exist or you want to change the name of the units, then one can uses the
+`set_units` function.
+```julia
+new_var = ClimaAnalysis.set_units(var, "kg m s^-1")
+```
+!!! warning "Override existing units"
+    If units already exist, this will override the units for data in `var`.
+
 ## Integration
 
 `OutputVar`s can be integrated with respect to longitude, latitude, or both using
@@ -188,4 +196,4 @@ julia> global_rmse(sim, obs)
 
 julia> units(se_var)
 "K^2"
-```
+```

src/Var.jl

@@ -50,7 +50,8 @@ export OutputVar,
     global_bias,
     squared_error,
     global_mse,
-    global_rmse
+    global_rmse,
+    set_units
 
 """
     Representing an output variable
@@ -241,7 +242,6 @@ end
 # Implemented in ClimaAnalysisUnitfulExt
 function _maybe_convert_to_unitful end
 
-
 """
     Var.convert_units(var, new_units; conversion_function = nothing)
 
@@ -301,6 +301,19 @@ Failure to specify the `conversion_function` will produce an error.
 """
 function convert_units end
 
+"""
+    set_units(var::OutputVar, units::AbstractString)
+
+Set `units` for data in `var`.
+
+!!! warning "Override existing units"
+    If units already exist, this will override the units for data in `var`. To convert
+    units, see [`Var.convert_units`](@ref)
+"""
+function set_units(var::OutputVar, units::AbstractString)
+    converted_var = convert_units(var, units, conversion_function = identity)
+    return converted_var
+end
 
 """
     is_z_1D(var::OutputVar)

test/test_Var.jl

@@ -1247,3 +1247,49 @@ end
     @test_throws ErrorException ClimaAnalysis.bias(var_tal, var_tal)
     @test_throws ErrorException ClimaAnalysis.squared_error(var_tal, var_tal)
 end
+
+@testset "Setting units" begin
+    # Unit exists (unitful)
+    lon = collect(range(-179.5, 179.5, 360))
+    lat = collect(range(-89.5, 89.5, 180))
+    data = ones(length(lon), length(lat))
+    dims = OrderedDict(["lon" => lon, "lat" => lat])
+    dim_attribs = OrderedDict([
+        "lon" => Dict("units" => "deg"),
+        "lat" => Dict("units" => "deg"),
+    ])
+    attribs =
+        Dict("long_name" => "idk", "short_name" => "short", "units" => "kg")
+    var = ClimaAnalysis.OutputVar(attribs, dims, dim_attribs, data)
+    var_units = ClimaAnalysis.set_units(var, "idk")
+    @test ClimaAnalysis.units(var_units) == "idk"
+
+    # Unit exists (not unitful)
+    lon = collect(range(-179.5, 179.5, 360))
+    lat = collect(range(-89.5, 89.5, 180))
+    data = ones(length(lon), length(lat))
+    dims = OrderedDict(["lon" => lon, "lat" => lat])
+    dim_attribs = OrderedDict([
+        "lon" => Dict("units" => "deg"),
+        "lat" => Dict("units" => "deg"),
+    ])
+    attribs =
+        Dict("long_name" => "idk", "short_name" => "short", "units" => "wacky")
+    var = ClimaAnalysis.OutputVar(attribs, dims, dim_attribs, data)
+    var_units = ClimaAnalysis.set_units(var, "idk")
+    @test ClimaAnalysis.units(var_units) == "idk"
+
+    # Unit does not exist
+    lon = collect(range(-179.5, 179.5, 360))
+    lat = collect(range(-89.5, 89.5, 180))
+    data = ones(length(lon), length(lat))
+    dims = OrderedDict(["lon" => lon, "lat" => lat])
+    dim_attribs = OrderedDict([
+        "lon" => Dict("units" => "deg"),
+        "lat" => Dict("units" => "deg"),
+    ])
+    attribs = Dict("long_name" => "idk", "short_name" => "short")
+    var = ClimaAnalysis.OutputVar(attribs, dims, dim_attribs, data)
+    var_units = ClimaAnalysis.set_units(var, "idk")
+    @test ClimaAnalysis.units(var_units) == "idk"
+end