Commit 5382e0f4 authored by St. Elmo's avatar St. Elmo
Browse files

fix IO docs

parent 07ca82af
# Model IO
\ No newline at end of file
# Model IO
## Model structure
Before reading or writing models, it is important to understand how they are represented internally.
Each model is a type of `CobraTools.Model`, which is composed of a model `id`, arrays of `Reaction`s, `Metabolite`s and `Gene`s, and a gene reaction rules (`grrs`) dictionary.
The fields of `Reaction`, `Metabolite`, `Gene` types are shown below.
When reading or writing, these fields are what is used by `CobraTools.jl`.
```@docs
Model
```
Note, the format of `grrs` in `CobraTools.Model` is a nested array, like [[g1, g2], [g3, g4], ...], indexed by a reaction `id` key.
Each sub-array, e.g. [g1, g2], is composed of essential genes for the reaction to function.
Thus, if rxn1 requires (g1 and g2) or (g3 and g4) to function, then this would be represented by rxn1 => [[g1, g2], [g3, g4]] in `grrs`.
```@docs
Reaction
```
Note, the format of `grr` in `Reaction` is a string like `"(g1 and g2) or (g3 and g4)"`.
This string is parsed into the format used by `grrs` in `CobraTools.Model`, as explained above.
Also note, the metabolites dictionary field of `Reaction` maps a `Metabolite` to its stoichiometrix coefficient.
```@docs
Metabolite
```
```@docs
Gene
```
FIY: `JuMP` also exports a `Model` type, so you need to qualify which `Model` you are referring to when making a new function.
## Reading constraint based models
Currently, SBML, JSON and Matlab formatted models can be imported.
```@docs
read_model(file_location::String)
```
```@setup modelread
using CobraTools
models_folder = joinpath(join(split(pwd(), "\\")[1:end-2], "\\"), "models")
model_location = joinpath(models_folder, "iJO1366.json")
model = read_model(model_location) # import model so that the examples are simpler
```
```@example modelread
using CobraTools
# models_folder is a directory where models are stored
model_location = joinpath(models_folder, "iJO1366.json")
model = read_model(model_location)
```
## Writing constraint based models
Currently, JSON and Matlab models can be exported.
```@docs
save_model(model::CobraTools.Model, file_location::String)
```
```@example modelread
using CobraTools
# "e_coli_json_model.json" is the file name we are going to use to save the model
model_location = joinpath(pwd(), "e_coli_json_model.json")
# model is a CobraTools.Model object previously imported or created
save_model(model, model_location)
```
## Problems
Please let me know when you run into model import/export problems by filing an issue on the repo.
\ No newline at end of file
......@@ -30,6 +30,7 @@ include("equilibrator_tools.jl")
export , , , , , ,
export Reaction, Metabolite, Gene, Model
export build_cbm, fba, pfba, map_fluxes, set_bound, exchange_reactions, metabolite_fluxes
export read_model, save_model
# Initialization functions
......
"""
Gene struct (mutable)
Gene struct (mutable).
# Fields
````
id :: String
name :: String
notes :: Dict{String, Array{String, 1}}
annotation :: Dict{String, Union{Array{String, 1}, String}}
````
"""
mutable struct Gene
id :: String
name :: String
notes :: Dict{String, Array{String, 1}}
annotation :: Dict{String, Union{Array{String, 1}, String}}
annotation :: Dict{String, Union{Array{String, 1}, String}}
end
"""
......
"""
model = read_model(file_location)
read_model(file_location::String))
Reads a model file at file_location and returns a constraint based model.
Supported formats include SBML (.xml), Matlab COBRA models (.mat) and JSON COBRA models (.json).
Reads a model at file_location and returns a constraint based model (::CobraTools.Model).
Currently supported formats include SBML (.xml), Matlab (.mat) and JSON (.json) models.
The model format is inferred from the file extension.
Note, some meta-information may be lost when importing a model. Importantly, only information regarding the
reactions, metabolites and genes are imported. Currently reading JSON models captures the most meta-information
regarding reactions, metabolites and genes (e.g. the notes and annotation fields).
Note, when importing JSON models only reactions, metabolites, genes and id are used.
When importing Matlab models some annotation and notes may not be imported because of the non-standard field names used by some models.
Gene reaction rules are successfully imported only if they adhere to this format: `"(YIL010W and YLR043C) or (YIL010W and YGR209C)"`. Other gene reaction rules
formats are not supported yet.
Note, when importing Matlab models only rxns, metCharge, lb, metNames, S, grRules,
genes, description, rxnNames, ub, metFormulas, b, subSystems, mets and c are used.
In all cases the basic information should be imported, e.g. stoichiometrix matrix, constraints etc..
Advanced tools that require, e.g. metabolite formulas, gene reaction rules, and KEGG or BIGG IDs, will not function if these are improperly imported.
Always inspect the imported model before running analysis.
"""
function read_model(file_location)
function read_model(file_location::String)
if endswith(file_location, ".json")
try
model = reconstruct_model_json(JSON.parsefile(file_location))
model = reconstruct_model_json(file_location)
catch err
@error "JSON model reading error.\n$err"
model = CobraTools.Model()
......@@ -39,9 +47,9 @@ function read_model(file_location)
end
"""
reconstructmodeljson(modeldict)
reconstructmodeljson(modeldict::String)
"""
function reconstruct_model_json(file_location)
function reconstruct_model_json(file_location::String)
modeldict = JSON.parsefile(file_location)
id = modeldict["id"]
......@@ -72,9 +80,7 @@ function reconstruct_model_json(file_location)
end
"""
reconstruct_model_matlab(file_location)
Note, notes and some annotation information will be lost when reading in in this format.
reconstruct_model_matlab(file_location::String)
"""
function reconstruct_model_matlab(file_location::String)
matfile = matread(file_location)
......@@ -82,6 +88,7 @@ function reconstruct_model_matlab(file_location::String)
modeldict = matfile[model_name]
model_id = haskey(modeldict, "description") ? modeldict["description"] : model_name
model_id = haskey(modeldict, "modelName") ? modeldict["modelName"] : model_name # more specific
mets = Metabolite[]
for i in eachindex(modeldict["mets"])
......@@ -181,7 +188,10 @@ function reconstruct_model_matlab(file_location::String)
return CobraTools.Model(model_id, rxns, mets, genes, grrs)
end
function reconstruct_model_sbml(file_location)
"""
reconstruct_model_sbml(file_location::String)
"""
function reconstruct_model_sbml(file_location::String)
m = readSBML(file_location)
# m is now a Model structure with:
......@@ -193,7 +203,7 @@ function reconstruct_model_sbml(file_location)
end
"""
parsegrr(string_rule)
parsegrr(string_rule)
Format: (YIL010W and YLR043C) or (YIL010W and YGR209C)
"""
......@@ -208,18 +218,13 @@ function parse_grr(s::String)
end
"""
savemodel(model, file_location)
save_model(model::CobraTools.Model, file_location::String)
Save model at location file_location. Infers format from file_location extension.
Save model(::CobraTools.Model) at file_location. Infers format from file_location extension.
Supported formats include SBML (.xml), Matlab COBRA models (.mat) and JSON COBRA models (.json).
Note, when exporting JSON models only reactions, metabolites, genes and id are written.
Note, when exporting Matlab models only rxns, metCharge, lb, metNames, S, grRules,
genes, description, rxnNames, ub, metFormulas, b, subSystems, mets, rev, rxnGeneMat
and c are written to.
Note, SBML is not implemented yet.
Note, only the fields contained in model::CobraTools.Model are saved. Make sure that information isn't
lost between reading a model and writing a model (e.g. check gene reaction rules, notes and annotations).
"""
function save_model(model::CobraTools.Model, file_location::String)
if endswith(file_location, ".json")
......@@ -233,8 +238,10 @@ function save_model(model::CobraTools.Model, file_location::String)
end
end
function save_json_model(model::CobraTools.Model, file_location :: String)
"""
save_json_model(model::CobraTools.Model, file_location::String)
"""
function save_json_model(model::CobraTools.Model, file_location::String)
modeldict = Dict{String, Any}()
modeldict["id"] = model.id
modeldict["metabolites"] = model.mets
......@@ -261,6 +268,9 @@ function save_json_model(model::CobraTools.Model, file_location :: String)
end
end
"""
save_matlab_model(model::CobraTools.Model, file_location::String)
"""
function save_matlab_model(model::CobraTools.Model, file_location::String)
rxnrevs = zeros(Int64, length(model.rxns))
for i in eachindex(model.rxns)
......@@ -298,10 +308,12 @@ function save_matlab_model(model::CobraTools.Model, file_location::String)
"metCharge" => [m.charge for m in model.mets],
"rxns" => [r.id for r in model.rxns])
write_matfile(file_location; Dict(Symbol(model.id) => mdict)...)
matwrite(file_location, Dict(Symbol(model.id) => mdict))
end
function save_sbml_model()
"""
save_sbml_model(model::CobraTools.Model, file_location::String)
"""
function save_sbml_model(model::CobraTools.Model, file_location::String)
# To do...
end
"""
Metabolite struct (mutable)
Metabolite struct (mutable).
# Fields
````
id :: String
name :: String
formula :: String
charge :: Int64
compartment :: String
notes :: Dict{String, Array{String, 1}}
annotation :: Dict{String, Union{Array{String, 1}, String}}
````
"""
mutable struct Metabolite
id :: String
......
"""
Model struct of a constraint based metabolic model.
# Fields
````
id :: String
rxns :: Array{Reaction, 1}
mets :: Array{Metabolite, 1}
genes :: Array{Gene, 1}
grrs :: Dict{String, Array{Array{String, 1}, 1}}
````
"""
struct Model
id :: String # model name
......@@ -73,9 +82,10 @@ end
"""
Pretty printing of model::CobraTools.Model.
"""
function Base.show(io::IO, m::CobraTools.Model)
println(io, "Constraint based model: ", m.id)
println(io, "Number of reactions: ", length(m.rxns))
println(io, "Number of metabolites: ", length(m.mets))
println(io, "Number of genes: ", length(m.genes))
function Base.show(io::IO, ::MIME"text/plain", m::CobraTools.Model)
println(io, "Constraint based model: ", m.id, "\n",
"Number of reactions: ", length(m.rxns), "\n",
"Number of metabolites: ", length(m.mets), "\n",
"Number of genes: ", length(m.genes))
end
"""
Reaction struct (mutable)
Reaction struct (mutable).
# Fields
````
id :: String
name :: String
metabolites :: Dict{Metabolite, Float64}
lb :: Float64
ub :: Float64
grr :: String
subsystem :: String
notes :: Dict{String, Array{String, 1}}
annotation :: Dict{String, Union{Array{String, 1}, String}}
objective_coefficient :: Float64
````
"""
mutable struct Reaction
id :: String
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment