Merge pull request #63 from COBREXA/mk-io-types

improve the type&conversion handling around IO

Project.toml

@@ -1,7 +1,7 @@
 name = "COBREXA"
 uuid = "babc4406-5200-4a30-9033-bf5ae714c842"
 authors = ["The developers of COBREXA.jl"]
-version = "2.1.0"
+version = "2.2.0"
 
 [deps]
 AbstractFBCModels = "5a4f3dfa-1789-40f8-8221-69268c29937c"

docs/src/examples/01-loading-and-saving.jl

@@ -76,18 +76,21 @@ A.reactions(model2)
 
 # Normally, [`load_model`](@ref) is forced to guess the model type from the
 # filename suffix. We can specify the model type ourselves (this also allows
-# the users to work with non-standard file suffixes):
+# the users to work with non-standard file suffixes, and saves some overhead
+# and uncertainty in the guessing process):
 
-model = load_model(JSONFBCModels.JSONFBCModel, "e_coli_core.json")
+import JSONFBCModels: JSONFBCModel
+
+model = load_model(JSONFBCModel, "e_coli_core.json")
 
 # Sometimes it is useful to convert the model data to another type, such as the
 # SBML to a JSON model structure:
 
-model_converted_to_json = load_model("e_coli_core.xml", JSONFBCModels.JSONFBCModel)
+model_converted_to_json = load_model("e_coli_core.xml", JSONFBCModel)
 
 # Or to the "Canonical Julia model" from AbstractFBCModels:
 model_in_julia_structures =
-    load_model(JSONFBCModels.JSONFBCModel, "e_coli_core.json", A.CanonicalModel.Model)
+    load_model(JSONFBCModel, "e_coli_core.json", A.CanonicalModel.Model)
 
 #md # !!! tip "Compatibility with COBREXA v1.x"
 #md #     `CanonicalModel` is a newer, cleaned-up version of the `StandardModel` type used in COBREXA version 1. For all code that relied on `StandardModel`, the canonical one should work just as well.
@@ -98,7 +101,7 @@ model_in_julia_structures =
 # If required, it is also possible to convert all model types to each other
 # simply by using Julia's `convert`:
 
-model_in_json_structure = convert(JSONFBCModels.JSONFBCModel, model_in_julia_structures)
+model_in_json_structure = convert(JSONFBCModel, model_in_julia_structures)
 
 # ## Saving models
 
@@ -109,3 +112,32 @@ save_model(model_converted_to_json, "e_coli_core_from_sbml.json")
 println(open("e_coli_core_from_sbml.json") do f
     read(f, 100)
 end |> String, "...")
+
+# Note that without the conversion, it may happen that you save the model in an unexpected format!
+save_model(model_in_julia_structures, "e_coli_saved_wrongly.json")
+println(open("e_coli_saved_wrongly.json") do f
+    read(f, 100)
+end |> String, "...")
+
+# The above code has saved the `CanonicalModel` in the way specified by the
+# `CanonicalModel` structure -- which is, in this case, a binary dump of the
+# Julia objects, instead of the expected JSON. To prevent this, you can either
+# specify the output type yourself:
+
+save_model(model_in_julia_structures, "e_coli_saved_right.json", JSONFBCModel)
+
+# ...or use [`save_converted_model`](@ref) to guess the model type
+# automatically from the extension:
+
+save_converted_model(model_in_julia_structures, "e_coli_saved_automatically_right.json")
+println(open("e_coli_saved_automatically_right.json") do f
+    read(f, 100)
+end |> String, "...")
+
+@test load_model("e_coli_saved_automatically_right.json") isa JSONFBCModel #src
+
+# As with [`load_model`](@ref), there is some overhead and uncertainty
+# associated with [`save_converted_model`](@ref) guessing the model type from
+# extension. For that reason, it is adviseable to rely on the guessing
+# functionality only in interactive use in REPL, and avoid it in automated
+# scriptage altogether.

src/io.jl

@@ -17,8 +17,8 @@
 """
 $(TYPEDSIGNATURES)
 
-Load a FBC model representation while guessing the correct model type. Uses
-`AbstractFBCModels.load`.
+Load a FBC model representation while guessing the correct model type to load.
+Uses `AbstractFBCModels.load`.
 
 This overload almost always involves a search over types; do not use it in
 environments where performance is critical.
@@ -30,35 +30,36 @@ end
 """
 $(TYPEDSIGNATURES)
 
-Like [`load_model`](@ref) that guesses the input type, but immediately converts
-to the model type given by second argument.
+Overload of [`load_model`](@ref) that guesses the input type, but immediately
+converts to the model type given by argument `convert_to`.
 """
-function load_model(path::String, ::Type{O}) where {O<:A.AbstractFBCModel}
+function load_model(path::String, convert_to::Type{O}) where {O<:A.AbstractFBCModel}
     convert(O, A.load(path))
 end
 
 """
 $(TYPEDSIGNATURES)
 
-Load a FBC model representation from known `model_type`. Uses
+Load a FBC model representation from a known `model_type`. Uses
 `AbstractFBCModels.load`.
 """
 function load_model(model_type::Type{I}, path::String) where {I<:A.AbstractFBCModel}
-    A.load(model_type, path)
+    A.load(I, path)
 end
 
 """
 $(TYPEDSIGNATURES)
 
-Like [`load_model`](@ref) with the type specified, but immediately converts to
-the "output" model type given by third argument.
+Overload of [`load_model`](@ref) that explicitly specifies the known input
+type, and immediately converts to another model type given by argument
+`convert_to`.
 """
 function load_model(
     model_type::Type{I},
     path::String,
-    ::Type{O},
+    convert_to::Type{O},
 ) where {I<:A.AbstractFBCModel,O<:A.AbstractFBCModel}
-    convert(O, A.load(model_type, path))
+    convert(O, A.load(I, path))
 end
 
 export load_model
@@ -67,16 +68,50 @@ export load_model
 $(TYPEDSIGNATURES)
 
 Save a FBC model representation. Uses `AbstractFBCModels.save`.
+
+Use the 3-parameter overload if you need to convert the model to another
+representation (e.g., if you want to save a canonical model type as JSON or
+SBML).
 """
 function save_model(model::T, path::String) where {T<:A.AbstractFBCModel}
     A.save(model, path)
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+Overload of [`save_model`](@ref) that converts the model type to `convert_to`
+before saving.
+"""
+function save_model(
+    model::T,
+    path::String,
+    convert_to::Type{O},
+) where {T<:A.AbstractFBCModel,O<:A.AbstractFBCModel}
+    A.save(convert(O, model), path)
+end
+
 export save_model
 
 """
 $(TYPEDSIGNATURES)
 
+Like [`save_model`](@ref) but tries to convert the `model` to a type that
+matches the extension of the `path`. For example, this will convert the
+`model` to a JSON model type in case the `path` ends with `.json`.
+
+This is an utility shortcut -- if possible, it is always better to specify the
+output model type explicitly.
+"""
+function save_converted_model(model::T, path::String) where {T<:A.AbstractFBCModel}
+    save_model(model, path, A.guess_model_type_from_filename(path))
+end
+
+export save_converted_model
+
+"""
+$(TYPEDSIGNATURES)
+
 Safely download a model with a known hash. All arguments are forwarded to
 `AbstractFBCModels.download_data_file` -- see the documentation in the
 AbstractFBCModels package for details.