Merge pull request #11 from jd-foster/fix-review-issues

Use Tables.jl for GDX record storage

Author: MartinBonde

Project.toml

@@ -1,19 +1,22 @@
 name = "GDXInterface"
 uuid = "b8352055-3412-4df1-864e-ee7edae71aec"
-version = "0.1.1"
+version = "0.2.0"
 authors = ["Martin Kirk Bonde", "James Daniel Foster"]
 
 [deps]
-DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+DataAPI = "9a962f9c-6df0-11e9-0e5d-c546b8b5ee8a"
+Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
 gdx_jll = "aa021fa7-5c7d-5dc1-9fa7-c90cd282ac20"
 
 [compat]
-DataFrames = "1"
+DataAPI = "1"
+Tables = "1"
 gdx_jll = "7.11.20"
 julia = "1.6"
 
 [extras]
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test"]
+test = ["Test", "DataFrames"]

README.md

@@ -48,7 +48,7 @@ list_parameters(gdx)
 list_variables(gdx)
 list_equations(gdx)
 
-# Access data as DataFrames
+# Access data as Tables.jl-compatible column tables
 demand = gdx[:demand]       # bracket syntax
 demand = gdx.demand         # property syntax (with tab completion)
 
@@ -57,17 +57,21 @@ sym = get_symbol(gdx, :demand)
 sym.name         # "demand"
 sym.description  # explanatory text from GAMS
 sym.domain       # ["j"]
-sym.records      # the DataFrame
+sym.records      # the records table
+
+# Pass DataFrame as a sink to materialize DataFrames while reading
+using DataFrames
+gdx = read_gdx("transport.gdx", DataFrame)
 ```
 
 ### Writing GDX files
 
 ```julia
-using GDXInterface, DataFrames
+using GDXInterface
 
-# Write DataFrames as parameters
-supply = DataFrame(i = ["seattle", "san-diego"], value = [350.0, 600.0])
-demand = DataFrame(j = ["new-york", "chicago", "topeka"], value = [325.0, 300.0, 275.0])
+# Write Tables.jl-compatible tables as parameters
+supply = (; i = ["seattle", "san-diego"], value = [350.0, 600.0])
+demand = (; j = ["new-york", "chicago", "topeka"], value = [325.0, 300.0, 275.0])
 write_gdx("output.gdx", "supply" => supply, "demand" => demand)
 
 # Round-trip: read a GDX file and write it back (preserves all symbol types)
@@ -98,17 +102,18 @@ gdx = read_gdx("big_model.gdx", only=[:x, :demand])
 ### Reading
 
 ```julia
-read_gdx(filepath; parse_integers=true, only=nothing) -> GDXFile
+read_gdx(filepath[, sink]; parse_integers=true, only=nothing) -> GDXFile
 ```
 
+- `sink`: callable that materializes a column table, defaulting to `Tables.columntable`
 - `parse_integers`: convert set elements like `"2020"` to `Int`
 - `only`: vector of symbol names to load (e.g. `[:x, :demand]`)
 
 ### Writing
 
 ```julia
-# Write DataFrames as parameters (convenience)
-write_gdx(filepath, "name" => DataFrame, ...)
+# Write tables as parameters (convenience)
+write_gdx(filepath, "name" => table, ...)
 
 # Write a full GDXFile (sets, parameters, variables, equations)
 write_gdx(filepath, gdxfile::GDXFile)
@@ -117,8 +122,8 @@ write_gdx(filepath, gdxfile::GDXFile)
 ### Querying a GDXFile
 
 ```julia
-gdx[:name]               # records DataFrame (bracket access)
-gdx.name                 # records DataFrame (property access)
+gdx[:name]               # records table (bracket access)
+gdx.name                 # records table (property access)
 get_symbol(gdx, :name)   # full GDXSymbol object
 
 list_sets(gdx)            # list set names