From d78153b964a2ea18a81f6668af6fbdf6cb08247e Mon Sep 17 00:00:00 2001
From: Kevin Bonham <kevbonham@gmail.com>
Date: Tue, 14 Dec 2021 22:01:35 -0500
Subject: [PATCH] Metabolites (#125)

* add metabolite feature

* remove qualifier

* add docs for Metabolite

* fix doctests for julia 1.7

* add doctests
---
 docs/src/profiles.md         |  4 ++--
 docs/src/samples_features.md | 37 +++++++++++++++++++++++++++++++++---
 src/features.jl              | 31 ++++++++++++++++++++++++++++++
 3 files changed, 67 insertions(+), 5 deletions(-)

diff --git a/docs/src/profiles.md b/docs/src/profiles.md
index 9e42ef4..7f2499c 100644
--- a/docs/src/profiles.md
+++ b/docs/src/profiles.md
@@ -285,7 +285,7 @@ with the value `missing` in any samples that do not have that field set.
 
 ```jldoctest profiles
 julia> metadata(comm)
-3-element Vector{NamedTuple{(:sample, :subject), T} where T<:Tuple}:
+3-element Vector{NamedTuple{(:sample, :subject)}}:
  (sample = "s1", subject = "kevin")
  (sample = "s2", subject = "anika")
  (sample = "s3", subject = missing)
@@ -310,7 +310,7 @@ julia> md2 = [(name="s1", other="Hello, World!"), (name="s2", other="Goodbye!")]
 julia> insert!(comm, md2; namecol=:name)
 
 julia> metadata(comm)
-3-element Vector{NamedTuple{(:sample, :subject, :foo, :other), T} where T<:Tuple}:
+3-element Vector{NamedTuple{(:sample, :subject, :foo, :other)}}:
  (sample = "s1", subject = "kevin", foo = "bar", other = "Hello, World!")
  (sample = "s2", subject = "anika", foo = missing, other = "Goodbye!")
  (sample = "s3", subject = "annelle", foo = "baz", other = missing)
diff --git a/docs/src/samples_features.md b/docs/src/samples_features.md
index 36ef5bf..087d059 100644
--- a/docs/src/samples_features.md
+++ b/docs/src/samples_features.md
@@ -78,7 +78,8 @@ MicrobiomeSample("sample3", {:age = 23, :gender = "nonbinary", :genotype = "XY",
 ## Feature Types
 
 `AbstractFeature` types also have a `name`, but other fields are optional.
-`Microbiome.jl` defines two concrete `AbstractFeature` types, [`Taxon`](@ref) and [`GeneFunction`](@ref).
+`Microbiome.jl` defines three concrete `AbstractFeature` types,
+[`Taxon`](@ref), [`GeneFunction`](@ref), and [`Metabolite`](@ref).
 
 
 ### Taxon
@@ -135,8 +136,6 @@ julia> String(ecoli) |> taxon
 Taxon("Escherichia_coli", :species)
 ```
 
-
-
 ### GeneFunction
 
 The [`GeneFunction`](@ref) type contains a name and (optionally) a [`Taxon`](@ref).
@@ -195,6 +194,31 @@ GeneFunction("gene2", Taxon("Species_name", :species))
 ```
 
 
+### Metabolites
+
+The [`Metabolite`](@ref) type has a `name` and optionally
+a `commonname`, a mass / charge ratio (`mz`), and retention time (`rt`).
+
+
+```jldoctest
+julia> m = Metabolite("name", "common", 1., 2.)
+Metabolite("name", "common", 1.0, 2.0)
+
+julia> name(m)
+"name"
+
+julia> commonname(m)
+"common"
+
+julia> masscharge(m)
+1.0
+
+julia> retentiontime(m)
+2.0
+
+julia> m2 = Metabolite("other name")
+Metabolite("other name", missing, missing, missing)
+```
 
 ## Types and Methods
 
@@ -214,4 +238,11 @@ taxon
 ```@docs
 GeneFunction
 genefunction
+```
+
+```@docs
+Metabolite
+commonname
+masscharge
+retentiontime
 ```
\ No newline at end of file
diff --git a/src/features.jl b/src/features.jl
index e326321..6249d94 100644
--- a/src/features.jl
+++ b/src/features.jl
@@ -182,6 +182,18 @@ end
 
 Base.string(f::AbstractFeature) = String(f)
 
+"""
+    Metabolite(name::String, commonname::Union{Missing, String}, mz::Union{Missing, Float64}, rt::Union{Missing, Float64}) <: AbstractFeature
+    Metabolite(name::String)
+
+Represents a small-molecule metabolite coming from an LCMS.
+The fields are
+
+- `name`: required, this should be a unique identifier
+- `commonname`: might refer to a chemical name like "proprionate"
+- `mz`: The mass/charge ratio
+- `rt`: The retention time
+"""
 struct Metabolite <: AbstractFeature
     name::String
     commonname::Union{Missing, String}
@@ -192,8 +204,27 @@ end
 Metabolite(n::AbstractString) = Metabolite(n, missing, missing, missing)
 
 name(m::Metabolite) = m.name
+
+"""
+    commonname(m::Metabolite)
+
+Accessor function for the `commonname` field of a [`Metabolite`](@ref).
+"""
 commonname(m::Metabolite) = m.commonname
+
+
+"""
+    masscharge(m::Metabolite)
+
+Accessor function for the `mz` field of a [`Metabolite`](@ref).
+"""
 masscharge(m::Metabolite) = m.mz
+
+"""
+    retentiontime(m::Metabolite)
+
+Accessor function for the `rt` field of a [`Metabolite`](@ref).
+"""
 retentiontime(m::Metabolite) = m.rt
 
 @testset "Metabolites" begin