Add iscoding and decision rule functions to criteria module

Author: camilogarciabotero

src/criteria.jl

@@ -0,0 +1,126 @@
+export iscoding,
+    log_odds_ratio_decision_rule, lordr,
+    ribsome_binding_site_decision_rule, rbsdr
+
+
+    @doc raw"""
+    iscoding(orf::ORFI{N,F}; criteria::Function = lordr, kwargs...) -> Bool
+
+Check if the given DNA sequence of an ORF is likely to be coding based on a scoring scheme/function.
+
+## Scoring Criteria/Functions
+- `lordr`: Log-Odds Ratio Decision Rule
+- `rbsdr`: Ribosome Binding Site Decision Rule
+
+```
+phi = dna"GTGTGAGGTTATAACGCCGAAGCGGTAAAAATTTTAAT...AGTGTTTCCAGTCCGTTCAGTTAATAGTCAGGTTAAAGATAAAAGATTGA"
+orfs = findorfs(phi)
+
+orf = orfs[2]
+    ORFI{NaiveFinder}(94:126, '-', 1)
+
+iscoding(orf)  # Returns: true
+```
+"""
+function iscoding(
+    orf::ORFI{N,F};
+    criteria::Function = lordr, #rbsdr
+    kwargs...
+) where {N,F<:GeneFinderMethod}
+    return criteria(orf; kwargs...)
+end
+
+### Actual criteria functions ###
+
+## Log-Odds Ratio Decision Rule
+
+@doc raw"""
+    log_odds_ratio_decision_rule(
+        sequence::LongSequence{DNAAlphabet{4}};
+        modela::BioMarkovChain,
+        modelb::BioMarkovChain,
+        η::Float64 = 1e-5
+        )
+
+Check if a given DNA sequence is likely to be coding based on a log-odds ratio.
+    The log-odds ratio is a statistical measure used to assess the likelihood of a sequence being coding or non-coding. It compares the probability of the sequence generated by a coding model to the probability of the sequence generated by a non-coding model. If the log-odds ratio exceeds a given threshold (`η`), the sequence is considered likely to be coding.
+    It is formally described as a decision rule:
+
+```math
+S(X) = \log \left( \frac{{P_C(X_1=i_1, \ldots, X_T=i_T)}}{{P_N(X_1=i_1, \ldots, X_T=i_T)}} \right) \begin{cases} > \eta & \Rightarrow \text{{coding}} \\ < \eta & \Rightarrow \text{{noncoding}} \end{cases}
+```
+
+# Arguments
+- `sequence::NucleicSeqOrView{DNAAlphabet{N}}`: The DNA sequence to be evaluated.
+
+## Keyword Arguments
+- `codingmodel::BioMarkovChain`: The transition model for coding regions, (default: `ECOLICDS`).
+- `noncodingmodel::BioMarkovChain`: The transition model for non-coding regions, (default: `ECOLINOCDS`)
+- `b::Number = 2`: The base of the logarithm used to calculate the log-odds ratio (default: 2).
+- `η::Float64 = 1e-5`: The threshold value (eta) for the log-odds ratio (default: 1e-5).
+
+# Returns
+- `true` if the sequence is likely to be coding.
+- `false` if the sequence is likely to be non-coding.
+
+# Raises
+- `ErrorException`: if the length of the sequence is not divisible by 3.
+- `ErrorException`: if the sequence contains a premature stop codon.
+
+# Example
+
+```
+sequence = dna"ATGGCATCTAG"
+iscoding(sequence)  # Returns: true or false
+```
+"""
+function lordr( #log_odds_ratio_decision, also lordr/cudr/kfdr/aadr
+    orf::ORFI{N,F};
+    modela::BioMarkovChain = ECOLICDS,
+    modelb::BioMarkovChain = ECOLINOCDS,
+    b::Number = 2,
+    η::Float64 = 5e-3
+) where {N,F<:GeneFinderMethod}
+    orfseq = sequence(orf)
+    scorea = log_odds_ratio_score(orfseq; modela=modela, b=b)
+    scoreb = log_odds_ratio_score(orfseq; modela=modelb, b=b)
+    
+    logodds = scorea / scoreb
+
+    if logodds > η
+        return true
+    else
+        false
+    end
+end
+
+const log_odds_ratio_decision_rule = lordr # criteria
+
+## Ribosome Binding Site Decision Rule
+
+"""
+    ribsome_binding_site_decision_rule(orf::ORFI{N,F}) where {N,F<:GeneFinderMethod} -> Bool
+
+Evaluates if an Open Reading Frame (ORF) has a significant ribosome binding site (RBS).
+
+The function uses the `orf_rbs_score` to calculate a score for the ORF's RBS region and returns
+true if the score exceeds a threshold of 9, indicating the presence of at least one RBS.
+
+# Arguments
+- `orf::ORFI{N,F}`: An Open Reading Frame Interface (ORFI) object parameterized by N and F,
+  where F is a subtype of GeneFinderMethod
+
+# Returns
+- `Bool`: `true` if the RBS score is greater than 9, `false` otherwise
+
+"""
+function rbsdr(orf::ORFI{N,F}) where {N,F<:GeneFinderMethod}
+    scr = orf_rbs_score(orf)
+    if scr > 9 # at least one RBS...
+        return true
+    else
+        return false
+    end
+end
+
+const ribsome_binding_site_decision_rule = rbsdr