#5: Add multiple convenience functions for TMEAResults

src/TMEA/Frames.fs

@@ -3,14 +3,15 @@
 module Frames =
 
     open Deedle
+    open FSharp.Stats
 
     let internal optDefFloat (f:float opt)=
         if f.HasValue then f.Value else -1.
 
     let internal optDefInt (f:int opt)=
         if f.HasValue then f.Value else 0
 
-    let internal createTMEACharacterizationTable minBinSize (termNameTransformation: string -> string) (tmeaCharacterizations:TMEACharacterization []) : Frame<(string*(string*int)),string> =
+    let internal createTMEACharacterizationTable minBinSize (alphaLevel:float) (termNameTransformation: string -> string) (tmeaCharacterizations:TMEACharacterization []) : Frame<(string*(string*int)),string> =
         tmeaCharacterizations
         |> Array.mapi (fun i desc ->
             let negFrame: Frame<string,string> =
@@ -82,8 +83,8 @@ module Frames =
                                 optDefFloat o1,optDefFloat o2
                             |None -> -1.,-1.
 
-                        ((p1 < 0.05 && p1 >= 0.) 
-                        || (p2 < 0.05 && p2 >= 0.))
+                        ((p1 < alphaLevel && p1 >= 0.) 
+                        || (p2 < alphaLevel && p2 >= 0.))
                         |> Some
                     )
                 f |> Frame.addCol "isAnySig_BH_Corrected" allPvalZip
@@ -97,27 +98,70 @@ module Frames =
                                 optDefFloat o1, optDefFloat o2
                             |None -> -1.,-1.
 
-                        ((p1 < 0.05 && p1 >= 0.) 
-                        || (p2 < 0.05 && p2 >= 0.))
+                        ((p1 < alphaLevel && p1 >= 0.) 
+                        || (p2 < alphaLevel && p2 >= 0.))
                         |> Some
                     )
                 f |> Frame.addCol "isAnySig" allPvalZip
 
     type TMEAResult with
 
-        static member toTMEACharacterizationFrame(?MinBinSize:int, ?TermNameTransformation:string->string) = 
+        /// <summary>
+        /// Returns a function that creates a frame containing the TMEA Characterizations identified in the given TMEAResult. This is the central result of TMEA analysis.
+        ///
+        /// It contains rows with the following columns:
+        ///
+        /// Term(FAS) - Indicates the Name of the Functionally Annotated Set (FAS)
+        ///
+        /// Transformed Term - A custom term name transformation that can be set by the user. Can be used e.g. for further grouping of the FAS
+        ///
+        /// ConstraintIndex - Indicates the index of the constraint the rest of the result in the row is concerned with
+        ///
+        /// Neg_PValue - The raw empirical PValue returned by the TMEA Monte-Carlo simulation indicating if the FAS is enriched when only analyzing negative weights in the constraint
+        ///
+        /// Neg_BinSize - The amount of entities with negative weight in the FAS
+        ///
+        /// Neg_WeightSum - The sum of negative weights in the FAS
+        ///
+        /// Pos_PValue - The raw empirical PValue returned by the TMEA Monte-Carlo simulation indicating if the FAS is enriched when only analyzing positive weights in the constraint
+        ///
+        /// Pos_BinSize - The amount of entities with positive weight in the FAS
+        ///
+        /// Pos_WeightSum - The sum of positive weights in the FAS
+        ///
+        /// Total_BinSize - The amount of entities contained in the FAS
+        ///
+        /// Pos_PValue_BH_Corrected - The afforementioned positive p-value, constraint-wise adjusted with the Benjamini-Hochberg correction for multiple testing
+        ///
+        /// Neg_PValue_BH_Corrected - The afforementioned negative p-value, constraint-wise adjusted with the Benjamini-Hochberg correction for multiple testing
+        ///
+        /// isAnySig_BH_Corrected - Indicates if the FAS can be considered as significantly enriched when looking at either negative or positive weights depending on the user defined alpha level
+        ///
+        /// isAnySig - Indicates if the FAS can be considered as significantly enriched when looking at either negative or positive weights depending on the user defined alpha level after applying constraint-wise adjustment with the Benjamini-Hochberg correction for multiple testing
+        ///
+        /// </summary>
+        /// <param name="MinBinSize">A threshold for the amount of entities contained in every FAS. FAS below this entity count will not be contained in the result frame. Default=0</param>
+        /// <param name="AlphaLevel">The alpha level to either accept or reject the FAS as significantly enriched. Default=0.05</param>
+        /// <param name="TermNameTransformation">A function to transform the FAS Names</param>
+        static member toTMEACharacterizationFrame(?MinBinSize:int, ?AlphaLevel:float, ?TermNameTransformation:string->string) = 
 
             let minBinSize = defaultArg MinBinSize 0
+            let alphaLevel = defaultArg AlphaLevel 0.05
             let termNameTransformation = defaultArg TermNameTransformation id
 
             fun (tmeaRes: TMEAResult) ->
-                tmeaRes.Characterizations |> createTMEACharacterizationTable minBinSize termNameTransformation
-
-
-        static member toSignificanceMatrixFrame (?UseBenjaminiHochberg:bool, ?Threshold:float, ?TermNameTransformation:string->string) =
+                tmeaRes.Characterizations |> createTMEACharacterizationTable minBinSize alphaLevel termNameTransformation
+
+        /// <summary>
+        /// Returns a function that creates a frame containing A matrix that contains 1(indicating significant enrichment) or 0(indicating no enrichment) for all FAS(rows) in all constraints(columns)
+        /// </summary>
+        /// <param name="UseBenjaminiHochberg">Wether to use p-values adjusted by constraint-wise Benjamini-Hochberg correction for multiple testing. Default=false</param>
+        /// <param name="AlphaLevel">The alpha level to either accept or reject the FAS as significantly enriched. Default=0.05</param>
+        /// <param name="TermNameTransformation">A function to transform the FAS Names</param>
+        static member toSignificanceMatrixFrame (?UseBenjaminiHochberg:bool, ?AlphaLevel:float, ?TermNameTransformation:string->string) =
 
             let useBenjaminiHochberg = defaultArg UseBenjaminiHochberg false
-            let threshold = defaultArg Threshold 0.05
+            let threshold = defaultArg AlphaLevel 0.05
             let termNameTransformation = defaultArg TermNameTransformation id
 
             fun (tmeaRes:TMEAResult) ->
@@ -167,7 +211,26 @@ module Frames =
                 |> Frame.fillMissingWith 0
                 |> Frame.mapRowKeys (fun (name) -> (termNameTransformation name) => name)
 
-        static member toConstraintsFrame : unit = raise (System.NotImplementedException())
-
-        static member toConstraintPotentialsFrame : unit = raise (System.NotImplementedException())
-
+        /// <summary>
+        /// Creates a frame containing the constraints(patterns) identified in the TMEAResult
+        /// </summary>
+        /// <param name="tmeaRes">The tmeaResult to extract the constraint frame from.</param>
+        static member toConstraintsFrame (tmeaRes:TMEAResult) =
+
+            tmeaRes.Constraints
+            |> Matrix.toArray2D
+            |> Frame.ofArray2D
+            |> Frame.mapRowKeys(fun (i:int) -> tmeaRes.EntityNames.[i])
+            |> Frame.mapColKeys (fun (ck: int) -> $"C_{ck}")
+
+        /// <summary>
+        /// Creates a frame containing the constraint potentials identified in the TMEAResult
+        /// </summary>
+        /// <param name="tmeaRes">The tmeaResult to extract the constraint potentials frame from.</param>
+        static member toConstraintPotentialsFrame (tmeaRes:TMEAResult) =
+
+            tmeaRes.ConstraintPotentials
+            |> Matrix.toArray2D
+            |> Frame.ofArray2D
+            |> Frame.mapRowKeys(fun (i:int) -> $"C_{i}")
+            |> Frame.mapColKeys (fun (i:int) -> tmeaRes.Timepoints.[i])

src/TMEA/IO.fs

@@ -3,6 +3,7 @@
 module IO =
     open Deedle
     open System.IO
+    open Frames
 
     let readComparisonFrame (path:string) : Frame<string,string> =
         Frame.ReadCsv(
@@ -123,10 +124,85 @@ module IO =
 
     type TMEAResult with
 
-        static member saveTMEACharacterizationFrame (tmeaRes:TMEAResult) : unit = raise (System.NotImplementedException())
+        /// <summary>
+        /// Returns a function that saves a frame containing the TMEA Characterizations identified in the given TMEAResult at the given path. This is the central result of TMEA analysis.
+        ///
+        /// It contains rows with the following columns:
+        ///
+        /// Term(FAS) - Indicates the Name of the Functionally Annotated Set (FAS)
+        ///
+        /// Transformed Term - A custom term name transformation that can be set by the user. Can be used e.g. for further grouping of the FAS
+        ///
+        /// ConstraintIndex - Indicates the index of the constraint the rest of the result in the row is concerned with
+        ///
+        /// Neg_PValue - The raw empirical PValue returned by the TMEA Monte-Carlo simulation indicating if the FAS is enriched when only analyzing negative weights in the constraint
+        ///
+        /// Neg_BinSize - The amount of entities with negative weight in the FAS
+        ///
+        /// Neg_WeightSum - The sum of negative weights in the FAS
+        ///
+        /// Pos_PValue - The raw empirical PValue returned by the TMEA Monte-Carlo simulation indicating if the FAS is enriched when only analyzing positive weights in the constraint
+        ///
+        /// Pos_BinSize - The amount of entities with positive weight in the FAS
+        ///
+        /// Pos_WeightSum - The sum of positive weights in the FAS
+        ///
+        /// Total_BinSize - The amount of entities contained in the FAS
+        ///
+        /// Pos_PValue_BH_Corrected - The afforementioned positive p-value, constraint-wise adjusted with the Benjamini-Hochberg correction for multiple testing
+        ///
+        /// Neg_PValue_BH_Corrected - The afforementioned negative p-value, constraint-wise adjusted with the Benjamini-Hochberg correction for multiple testing
+        ///
+        /// isAnySig_BH_Corrected - Indicates if the FAS can be considered as significantly enriched when looking at either negative or positive weights depending on the user defined alpha level
+        ///
+        /// isAnySig - Indicates if the FAS can be considered as significantly enriched when looking at either negative or positive weights depending on the user defined alpha level after applying constraint-wise adjustment with the Benjamini-Hochberg correction for multiple testing
+        ///
+        /// </summary>
+        /// <param name="path">The path (containing the filename with extension) of the output file</param>
+        /// <param name="MinBinSize">A threshold for the amount of entities contained in every FAS. FAS below this entity count will not be contained in the result frame. Default=0</param>
+        /// <param name="AlphaLevel">The alpha level to either accept or reject the FAS as significantly enriched. Default=0.05</param>
+        /// <param name="TermNameTransformation">A function to transform the FAS Names</param>
+        static member saveTMEACharacterizationFrame(path:string, ?MinBinSize:int, ?AlphaLevel:float, ?TermNameTransformation:string->string) = 
+
+             fun (tmeaRes: TMEAResult) ->
+                tmeaRes
+                |> TMEAResult.toTMEACharacterizationFrame(?MinBinSize=MinBinSize, ?AlphaLevel=AlphaLevel, ?TermNameTransformation=TermNameTransformation)
+                |> fun f -> f.SaveCsv(path,separator='\t',keyNames=["Term(FAS)"; "Transformed Term"; "ConstraintIndex"])
 
-        static member saveSignificanceMatrixFrame (tmeaRes:TMEAResult) : unit = raise (System.NotImplementedException())
-
-        static member saveConstraintsFrame (tmeaRes:TMEAResult) : unit = raise (System.NotImplementedException())
+        /// <summary>
+        /// Returns a function that saves a frame containing A matrix that contains 1(indicating significant enrichment) or 0(indicating no enrichment) for all FAS(rows) in all constraints(columns) at the given path.
+        /// </summary>
+        /// <param name="path">The path (containing the filename with extension) of the output file</param>
+        /// <param name="UseBenjaminiHochberg">Wether to use p-values adjusted by constraint-wise Benjamini-Hochberg correction for multiple testing. Default=false</param>
+        /// <param name="AlphaLevel">The alpha level to either accept or reject the FAS as significantly enriched. Default=0.05</param>
+        /// <param name="TermNameTransformation">A function to transform the FAS Names</param>
+        static member saveSignificanceMatrixFrame(path:string, ?UseBenjaminiHochberg:bool, ?AlphaLevel:float, ?TermNameTransformation:string->string) =
+
+            fun (tmeaRes: TMEAResult) ->
+                tmeaRes
+                |> TMEAResult.toSignificanceMatrixFrame(?UseBenjaminiHochberg=UseBenjaminiHochberg, ?AlphaLevel=AlphaLevel, ?TermNameTransformation=TermNameTransformation)
+                |> fun f -> f.SaveCsv(path,separator='\t',keyNames=["Term(FAS)"; "Transformed Term"])
+
+        /// <summary>
+        /// Saves a frame containing the constraints(patterns) identified in the TMEAResult at the given path.
+        /// </summary>
+        /// <param name="path">The path (containing the filename with extension) of the output file</param>
+        /// <param name="tmeaRes">The tmeaResult to extract the constraint frame from.</param>
+        static member saveConstraintsFrame (path:string) (tmeaRes:TMEAResult) = 
+
+            fun (tmeaRes: TMEAResult) ->
+                tmeaRes
+                |> TMEAResult.toConstraintsFrame
+                |> fun f -> f.SaveCsv(path,separator='\t',keyNames=["EntityName"])
+
+        /// <summary>
+        /// Saves a frame containing the constraint potentials identified in the TMEAResult at the given path.
+        /// </summary>
+        /// <param name="tmeaRes">The tmeaResult to extract the constraint potentials frame from.</param>
+        /// <param name="path">The path (containing the filename with extension) of the output file</param>
+        static member saveConstraintPotentialsFrame (path:string) (tmeaRes:TMEAResult) = 
 
-        static member saveConstraintPotentialsFrame (tmeaRes:TMEAResult) : unit = raise (System.NotImplementedException())
+            fun (tmeaRes: TMEAResult) ->
+                tmeaRes
+                |> TMEAResult.toConstraintPotentialsFrame
+                |> fun f -> f.SaveCsv(path,separator='\t',keyNames=["EntityName"])

src/TMEA/Playground.fsx

@@ -11,11 +11,11 @@ open Deedle
 open FSharpAux
 
 #load "Domain.fs"
+#load "Frames.fs"
 #load "IO.fs"
 #load "SurprisalAnalysis.fs"
 #load "MonteCarlo.fs"
 #load "WeightDistributions.fs"
-#load "Frames.fs"
 #load "Plots.fs"
 #load "Analysis.fs"
 
@@ -99,6 +99,20 @@ testTmeaRes
 |> TMEAResult.toSignificanceMatrixFrame()
 |> fun f -> f.Print()
 
+testTmeaRes.Constraints
+|> Matrix.toArray2D
+|> Frame.ofArray2D
+|> Frame.mapRowKeys(fun (i:int) -> testTmeaRes.EntityNames.[i])
+|> Frame.mapColKeys (fun (ck: int) -> $"C_{ck}")
+|> fun f -> f.Print()
+
+
+testTmeaRes.ConstraintPotentials
+|> Matrix.toArray2D
+|> Frame.ofArray2D
+|> Frame.mapRowKeys(fun (i:int) -> $"C_{i}")
+|> Frame.mapColKeys (fun (i:int) -> testTmeaRes.Timepoints.[i])
+|> fun f -> f.Print()
 
 //readDataFrame 
 //    "TranscriptIdentifier" 

src/TMEA/TMEA.fsproj

@@ -11,11 +11,11 @@
   </PropertyGroup>
   <ItemGroup>
     <Compile Include="Domain.fs" />
+    <Compile Include="Frames.fs" />
     <Compile Include="IO.fs" />
     <Compile Include="SurprisalAnalysis.fs" />
     <Compile Include="MonteCarlo.fs" />
     <Compile Include="WeightDistributions.fs" />
-    <Compile Include="Frames.fs" />
     <Compile Include="Plots.fs" />
     <Compile Include="Analysis.fs" />
     <None Include="Playground.fsx" />