Merge branch 'main' into tpoisot/issue23

.github/ISSUE_TEMPLATE/to-do.md

@@ -6,14 +6,11 @@ labels: need-triage, to do
 assignees: 'tpoisot'
 ---
 
-**What to do?**
-
+**What to do?**   
 ...
 
-**Why?**
-
+**Why?**   
 ...
 
-**## **Any ideas how?**
-
+**Any ideas how?**   
 ...

docs/src/namefinding.md

@@ -91,9 +91,35 @@ diplectanidfinder = descendantsfinder(taxid("Diplectanidae"))
 diplectanidfinder("Lamellodiscus")
 ```
 
+## Standard namefinders
+
+To save some time, there are namefinders pre-populated with the large-level
+taxonomic divisions.
+
+```@docs
+bacteriafinder
+virusfinder
+mammalfinder
+vertebratefinder
+plantfinder
+invertebratefinder
+rodentfinder
+primatefinder
+```
+
+All of these return a `namefinder` function -- so for example, the viral example
+from above can be re-written simply as:
+
+```@example taxid
+virusfinder()("Bumbulu ebolavirus"; fuzzy=true)
+```
+
+Note that we need to *call* the finder function to return the name finder. This
+may change in a future release.
+
 ## Internal functions
 
 ```@docs
 NCBITaxonomy._get_sciname_from_taxid
 NCBITaxonomy._df_from_taxlist
-```
+```

src/NCBITaxonomy.jl

@@ -31,6 +31,9 @@ select!(nodes_table, Not(:division_id))
 include("taxid.jl")
 export taxid, namefinder, descendantsfinder
 
+include("divisions.jl")
+export bacteriafinder, virusfinder, mammalfinder, vertebratefinder, plantfinder, invertebratefinder, rodentfinder, primatefinder
+
 include("string_macro.jl")
 export @ncbi_str
 
@@ -40,5 +43,4 @@ export children, descendants
 include("lineage.jl")
 export lineage, parent, rank
 
-
-end
+end

src/divisions.jl

@@ -0,0 +1,98 @@
+function _divisionfinder(division::Symbol)
+    nodes_subset = select(NCBITaxonomy.nodes_table, [:tax_id, :division_code])
+    filter!((r) -> r.division_code == division, nodes_subset)
+    df = leftjoin(nodes_subset, NCBITaxonomy.names_table; on=:tax_id)
+    return namefinder(df)
+end
+
+function _divisionfinder(division::Vector{Symbol})
+    nodes_subset = select(NCBITaxonomy.nodes_table, [:tax_id, :division_code])
+    filter!((r) -> r.division_code in division, nodes_subset)
+    df = leftjoin(nodes_subset, NCBITaxonomy.names_table; on=:tax_id)
+    return namefinder(df)
+end
+
+"""
+    virusfinder()
+
+Returns a `namefinder` limited to the viral division of the NCBI taxonomy. See
+the documentation for `namefinder` and `taxid` for more information about
+arguments.
+"""
+virusfinder() = _divisionfinder(:VRL)
+
+"""
+    bacteriafinder()
+
+Returns a `namefinder` limited to the bacterial division of the NCBI taxonomy. See
+the documentation for `namefinder` and `taxid` for more information about
+arguments.
+"""
+bacteriafinder() = _divisionfinder(:BCT)
+
+"""
+    plantfinder()
+
+Returns a `namefinder` limited to the "plant and fungi" division of the NCBI
+taxonomy. See the documentation for `namefinder` and `taxid` for more
+information about arguments.
+"""
+plantfinder() = _divisionfinder(:PLN)
+
+"""
+    primatefinder()
+
+Returns a `namefinder` limited to the primate division of the NCBI taxonomy. See
+the documentation for `namefinder` and `taxid` for more information about
+arguments.
+"""
+primatefinder() = _divisionfinder(:PRI)
+
+"""
+    rodentfinder()
+
+Returns a `namefinder` limited to the rodent division of the NCBI
+taxonomy. See the documentation for `namefinder` and `taxid` for more
+information about arguments.
+"""
+rodentfinder() = _divisionfinder(:ROD)
+
+"""
+    mammalfinder(;inclusive::Bool=true)
+
+Returns a `namefinder` limited to the mammal division of the NCBI taxonomy. See
+the documentation for `namefinder` and `taxid` for more information about
+arguments.
+
+If the keyword argument `inclusive` is set to `false`, this will *not* search
+for organisms assigned to a lower division, in this case rodents (covered by
+`rodentfinder`) and primates (covered by `primatefinder`). The default behavior
+is to include these groups.
+"""
+mammalfinder(inclusive::Bool=true) = inclusive ? _divisionfinder([:MAM, :ROD, :PRI]) : _divisionfinder(:MAM)
+
+"""
+    vertebratefinder(;inclusive::Bool=true)
+
+Returns a `namefinder` limited to the vertebrate division of the NCBI taxonomy.
+See the documentation for `namefinder` and `taxid` for more information about
+arguments.
+
+If the keyword argument `inclusive` is set to `false`, this will *not* search
+for organisms assigned to a lower division, in this case mammals (covered by
+`mammalfinder`). The default behavior is to include these groups, which also
+include the groups covered by `mammalfinder` itself.
+"""
+vertebratefinder(inclusive::Bool=true) = inclusive ? _divisionfinder([:VRT, :MAM, :ROD, :PRI]) : _divisionfinder(:VRT)
+
+"""
+    invertebratefinder()
+
+Returns a `namefinder` limited to the invertebrate division of the NCBI taxonomy. See
+the documentation for `namefinder` and `taxid` for more information about
+arguments.
+
+Note that this is limited organisms not covered by `plantfinder`,
+`bacteriafinder`, and `virusfinder`.
+"""
+invertebratefinder() = _divisionfinder(:INV)

test/divisions.jl

@@ -0,0 +1,19 @@
+module TestDivisionFinders
+
+    using Test
+    using NCBITaxonomy
+
+    @test typeof(virusfinder()("Ebolavirus")) <: NCBITaxon
+    @test typeof(plantfinder()("Acer")) <: NCBITaxon
+    @test isnothing(mammalfinder(false)("Homo"))
+    @test isnothing(mammalfinder(false)("Mus"))
+    @test !isnothing(mammalfinder(true)("Mus"))
+    @test !isnothing(rodentfinder()("Mus"))
+    @test isnothing(vertebratefinder(false)("Homo"))
+    @test !isnothing(vertebratefinder(true)("Homo"))
+    @test !isnothing(primatefinder()("Homo"))
+    @test !isnothing(vertebratefinder(true)("Homo"))
+    @test !isnothing(bacteriafinder()("Pseudomonas"))
+    @test !isnothing(invertebratefinder()("Lamellodiscus"))
+
+end

test/runtests.jl

@@ -5,7 +5,8 @@ my_tests = [
    "taxid.jl",
    "lineages.jl",
    "rank.jl",
-   "namefinders.jl"
+   "namefinders.jl",
+   "divisions.jl"
 ]
 
 global test_n