More general constructors (#21)

Author: mtfishman

Project.toml

@@ -1,19 +1,13 @@
 name = "Observers"
 uuid = "338f10d5-c7f1-4033-a7d1-f9dec39bcaa0"
 authors = ["Giacomo Torlai <gttorlai@amazon.com>", "Matthew Fishman <mfishman@flatironinstitute.org>"]
-version = "0.2.2"
+version = "0.2.3"
 
 [deps]
-Accessors = "7d9f7c33-5ae7-4f3b-8dc6-eff91059b697"
 Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"
-ConstructionBase = "187b0558-2788-49d3-abe0-74a17ed4e7c9"
-DataAPI = "9a962f9c-6df0-11e9-0e5d-c546b8b5ee8a"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 
 [compat]
-Accessors = "0.1.28"
 Compat = "4.6.1"
-ConstructionBase = "1.5.1"
-DataAPI = "1.14.0"
 DataFrames = "1.5.0"
 julia = "1.6"

README.md

@@ -45,7 +45,7 @@ julia> ] add Observers
 ## Basic Usage
 
 ```julia
-using Observers
+using Observers: Observers, observer
 
 # Series for π/4
 f(k) = (-1)^(k + 1) / (2k - 1)
@@ -55,7 +55,7 @@ function my_iterative_function(niter; observer!, observe_step)
   for n in 1:niter
     π_approx += f(n)
     if iszero(n % observe_step)
-      update!(observer!; iteration=n, π_approx=4π_approx)
+      Observers.update!(observer!; iteration=n, π_approx=4π_approx)
     end
   end
   return 4π_approx
@@ -336,7 +336,7 @@ You can also rename the columns to more desirable names using the `rename!`
 function from `DataFrames`:
 
 ```julia
-julia> using DataFrames
+julia> using DataFrames: rename!
 
 julia> rename!(obs, ["Iteration", "Error"])
 10×2 DataFrame
@@ -394,23 +394,23 @@ for more details.
 
 
 
-You can access and modify functions of an observer with `get_function`, `set_function!`, and `insert_function!`:
+You can access and modify functions of an observer with `Observers.get_function`, `Observers.set_function!`, and `Observers.insert_function!`:
 
 ```julia
-julia> get_function(obs, "Iteration") == iter
+julia> Observers.get_function(obs, "Iteration") == iter
 true
 
-julia> get_function(obs, "Error") == err
+julia> Observers.get_function(obs, "Error") == err
 true
 
-julia> set_function!(obs, "Error" => sin);
+julia> Observers.set_function!(obs, "Error" => sin);
 
-julia> get_function(obs, "Error") == sin
+julia> Observers.get_function(obs, "Error") == sin
 true
 
-julia> insert_function!(obs, "New column" => cos);
+julia> Observers.insert_function!(obs, "New column" => cos);
 
-julia> get_function(obs, "New column") == cos
+julia> Observers.get_function(obs, "New column") == cos
 true
 
 julia> obs
@@ -431,13 +431,13 @@ julia> obs
 ```
 
 
-`set_function!` just updates the function of an existing column but doesn't create new columns,
-while `insert_function!` creates a new column and sets the function of that new column
+`Observers.set_function!` just updates the function of an existing column but doesn't create new columns,
+while `Observers.insert_function!` creates a new column and sets the function of that new column
 but won't update an existing column.
 For example, these will both throw errors:
 ```julia
-set_function!(obs, "New column 2", cos)
-insert_function!(obs, "Error", cos)
+Observers.set_function!(obs, "New column 2", cos)
+Observers.insert_function!(obs, "Error", cos)
 ```
 
 
@@ -514,7 +514,8 @@ Another option is saving and loading as a
 though this will drop information about the functions associated with each column:
 
 ```julia
-using CSV
+using CSV: CSV
+using DataFrames: DataFrame
 CSV.write("results.csv", obs)
 obs_loaded = DataFrame(CSV.File("results.csv"))
 ```
@@ -537,8 +538,9 @@ This [README](https://github.com/GTorlai/Observers.jl#readme) file was generated
 [Weave.jl](https://github.com/JunoLab/Weave.jl) with the following commands:
 
 ```julia
-using Observers, Weave
-weave(
+using Observers: Observers
+using Weave: Weave
+Weave.weave(
   joinpath(pkgdir(Observers), "examples", "README.jl");
   doctype="github",
   out_path=pkgdir(Observers),

examples/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
+Observers = "338f10d5-c7f1-4033-a7d1-f9dec39bcaa0"
+Weave = "44d3d7a6-8a23-5bf8-98c5-b353f8df5ec9"

examples/README.jl

@@ -32,7 +32,7 @@
 
 #+ results="hidden"
 
-using Observers
+using Observers: Observers, observer
 
 # Series for π/4
 f(k) = (-1)^(k + 1) / (2k - 1)
@@ -42,7 +42,7 @@ function my_iterative_function(niter; observer!, observe_step)
   for n in 1:niter
     π_approx += f(n)
     if iszero(n % observe_step)
-      update!(observer!; iteration=n, π_approx=4π_approx)
+      Observers.update!(observer!; iteration=n, π_approx=4π_approx)
     end
   end
   return 4π_approx
@@ -139,7 +139,7 @@ obs[!, Symbol(err)]
 #' You can also rename the columns to more desirable names using the `rename!`
 #' function from `DataFrames`:
 #+ term=true
-using DataFrames
+using DataFrames: rename!
 rename!(obs, ["Iteration", "Error"])
 obs.Iteration
 obs.Error
@@ -152,23 +152,23 @@ obs.Error
 
 #' ## Accessing and modifying functions
 
-#' You can access and modify functions of an observer with `get_function`, `set_function!`, and `insert_function!`:
+#' You can access and modify functions of an observer with `Observers.get_function`, `Observers.set_function!`, and `Observers.insert_function!`:
 #+ term=true
-get_function(obs, "Iteration") == iter
-get_function(obs, "Error") == err
-set_function!(obs, "Error" => sin);
-get_function(obs, "Error") == sin
-insert_function!(obs, "New column" => cos);
-get_function(obs, "New column") == cos
+Observers.get_function(obs, "Iteration") == iter
+Observers.get_function(obs, "Error") == err
+Observers.set_function!(obs, "Error" => sin);
+Observers.get_function(obs, "Error") == sin
+Observers.insert_function!(obs, "New column" => cos);
+Observers.get_function(obs, "New column") == cos
 obs
 
-#' `set_function!` just updates the function of an existing column but doesn't create new columns,
-#' while `insert_function!` creates a new column and sets the function of that new column
+#' `Observers.set_function!` just updates the function of an existing column but doesn't create new columns,
+#' while `Observers.insert_function!` creates a new column and sets the function of that new column
 #' but won't update an existing column.
 #' For example, these will both throw errors:
 #' ```julia
-#' set_function!(obs, "New column 2", cos)
-#' insert_function!(obs, "Error", cos)
+#' Observers.set_function!(obs, "New column 2", cos)
+#' Observers.insert_function!(obs, "Error", cos)
 #' ```
 
 #' Alternatively, if you define the observer with column names to begin with,
@@ -198,7 +198,8 @@ obs_loaded.Error == obs.Error
 #' [CSV file](https://dataframes.juliadata.org/stable/man/importing_and_exporting/#CSV-Files),
 #' though this will drop information about the functions associated with each column:
 #+ results="hidden"
-using CSV
+using CSV: CSV
+using DataFrames: DataFrame
 CSV.write("results.csv", obs)
 obs_loaded = DataFrame(CSV.File("results.csv"))
 #+ term=true
@@ -211,8 +212,9 @@ obs_loaded.Error == obs.Error
 #' [Weave.jl](https://github.com/JunoLab/Weave.jl) with the following commands:
 #+ eval=false
 
-using Observers, Weave
-weave(
+using Observers: Observers
+using Weave: Weave
+Weave.weave(
   joinpath(pkgdir(Observers), "examples", "README.jl");
   doctype="github",
   out_path=pkgdir(Observers),

examples/example1.jl

@@ -1,4 +1,4 @@
-using Observers
+using Observers: observer
 
 # Series for π/4
 f(k) = (-1)^(k + 1) / (2k - 1)
@@ -8,7 +8,7 @@ function my_iterative_function(niter; observer!, observe_step)
   for n in 1:niter
     π_approx += f(n)
     if iszero(n % observe_step)
-      update!(observer!; π_approx=4π_approx, iteration=n)
+      Observers.update!(observer!; π_approx=4π_approx, iteration=n)
     end
   end
   return 4π_approx

src/Observers.jl

@@ -1,19 +1,10 @@
 module Observers
-
 export observer, update!, get_function, set_function!, insert_function!
 # Deprecated
 export results
-
-using Accessors
-using Compat
-using ConstructionBase
-using DataFrames
-using DataAPI
-
 include("base/method_utils.jl")
 include("abstractdataframe/column_functions.jl")
 include("abstractdataframe/deprecated.jl")
 include("dataframe/observer.jl")
 include("dataframe/deprecated.jl")
-
-end # module
+end

src/abstractdataframe/column_functions.jl

@@ -1,3 +1,6 @@
+using Compat: @compat
+using DataFrames: AbstractDataFrame, colmetadata, colmetadata!, insertcols!
+
 # Function accessors interface
 get_function(df::AbstractDataFrame, name) = colmetadata(df, name, "function")
 

src/dataframe/observer.jl

@@ -1,42 +1,58 @@
+using DataFrames: DataFrame
+
 # Convenient constructors of DataFrames with functions as column metadata,
 # called an "observer".
 
-observer() = DataFrame()
+const ColumnName = Union{Symbol,String}
+
+function observer(names::Vector{<:ColumnName}, functions::Vector{<:Function}; kwargs...)
+  df = DataFrame(map(name -> name => Union{}[], names); kwargs...)
+  for (name, func) in zip(names, functions)
+    set_function!(df, name, func)
+  end
+  return df
+end
 
-# In general, fall back to `DataFrame` constructors.
-observer(args...; kwargs...) = DataFrame(args...; kwargs...)
+function observer(
+  names::Tuple{Vararg{ColumnName}}, functions::Tuple{Vararg{Function}}; kwargs...
+)
+  return observer(collect(names), collect(functions); kwargs...)
+end
 
 # Treat function column data as column metadata.
 # Default to empty columns with element type `Union{}`
 # so they get automatically promoted to the first type that gets pushed
 # into them.
-function observer(
-  name_function_pairs::Vector{<:Pair{T,<:Function}}; kwargs...
-) where {T<:Union{Symbol,String}}
-  df = DataFrame(
-    [first(name_function) => Union{}[] for name_function in name_function_pairs]; kwargs...
-  )
-  name_function_dict = Dict(name_function_pairs)
-  for name in keys(name_function_dict)
-    set_function!(df, name, name_function_dict[name])
-  end
-  return df
+function observer(name_function_pairs::Vector{<:Pair{<:ColumnName,<:Function}}; kwargs...)
+  return observer(first.(name_function_pairs), last.(name_function_pairs); kwargs...)
 end
 
-function observer(
-  key_function_pairs::Pair{T,<:Function}...; kwargs...
-) where {T<:Union{Symbol,String}}
-  return observer(Pair{T,Function}[key_function_pairs...]; kwargs...)
+function observer(name_function_pairs::Pair{<:ColumnName,<:Function}...; kwargs...)
+  return observer(first.(name_function_pairs), last.(name_function_pairs); kwargs...)
+end
+
+function observer(name_function_pairs::NamedTuple; kwargs...)
+  return observer(keys(name_function_pairs), values(name_function_pairs); kwargs...)
+end
+
+function observer(names::Tuple{}, functions::Tuple{}; kwargs...)
+  return DataFrame(; kwargs...)
 end
 
+observer(; kwargs...) = observer(NamedTuple(kwargs))
+
 function observer(functions::Vector{<:Function}; kwargs...)
-  return observer(
-    Pair{String,Function}[string(func) => func for func in functions]; kwargs...
-  )
+  return observer(string.(functions), functions; kwargs...)
+end
+
+function observer(::Tuple{}; kwargs...)
+  return observer((), (); kwargs...)
+end
+
+function observer(functions::Tuple{Vararg{Function}}; kwargs...)
+  return observer(string.(functions), functions; kwargs...)
 end
 
 function observer(functions::Function...; kwargs...)
-  return observer(
-    Pair{String,Function}[string(func) => func for func in functions]; kwargs...
-  )
+  return observer(string.(functions), functions; kwargs...)
 end