Cleaned and commented

plotting/matrix.R

@@ -27,6 +27,7 @@
 
 
 ## 1. MATRIX PANEL
+# Generates a summarizing matrix of the trend analyses of all station for different hydrological variables and periods. Also shows difference of means between specific periods.
 matrix_panel = function (list_df2plot, df_meta, trend_period, mean_period, slice=NULL, outdirTmp='', outnameTmp='matrix', title=NULL, A3=FALSE) {
 
     # Number of variable/plot
@@ -171,11 +172,12 @@ matrix_panel = function (list_df2plot, df_meta, trend_period, mean_period, slice
             }
         }
     }
-    # Compute the min and the max of the mean trend for all the station
+    # Computes the min and the max of the mean trend for
+    # all the station
     minTrendMean = apply(TrendMean_code, c(1, 2), min, na.rm=TRUE)
     maxTrendMean = apply(TrendMean_code, c(1, 2), max, na.rm=TRUE)
 
-    
+    # Blank vectors to store info about trend analyses
     Periods_trend = c()
     NPeriod_trend = c()
     Type_trend = list()
@@ -204,42 +206,54 @@ matrix_panel = function (list_df2plot, df_meta, trend_period, mean_period, slice
                 # Extracts the trend corresponding to the code
                 df_trend_code = df_trend[df_trend$code == code,]
 
+                # Gets the associated time info
                 Start = Start_code[Code_code == code][[1]][j]
                 End = End_code[Code_code == code][[1]][j]
                 Periods = Periods_code[Code_code == code][[1]][j]
 
+                # Extracts the corresponding data for the period
                 df_data_code_per =
                     df_data_code[df_data_code$Date >= Start 
                                  & df_data_code$Date <= End,]
-
+                # Same for trend
                 df_trend_code_per = 
                     df_trend_code[df_trend_code$period_start == Start 
                                   & df_trend_code$period_end == End,]
 
+                # Computes the number of trend analysis selected
                 Ntrend = nrow(df_trend_code_per)
+                # If there is more than one trend on the same period
                 if (Ntrend > 1) {
+                    # Takes only the first because they are similar
                     df_trend_code_per = df_trend_code_per[1,]
                 }
-                
+
+                # Computes the mean of the data on the period
                 dataMean = mean(df_data_code_per$Qm3s, na.rm=TRUE)
+                # Normalises the trend value by the mean of the data
                 trendMean = df_trend_code_per$trend / dataMean
 
+                # If the p value is under the threshold
                 if (df_trend_code_per$p <= p_threshold){
+                    # Gets the color associated to the mean trend
                     color_res = get_color(trendMean, 
                                           minTrendMean[j, i],
                                           maxTrendMean[j, i],
                                           palette_name='perso',
                                           reverse=TRUE)
-
+                    # Specifies the color fill and contour of
+                    # table cells
                     fill = color_res
                     color = 'white'
                     Pthresold = p_thresold
+                # Otherwise it is not significative
                 } else { 
                     fill = 'white'
                     color = 'grey85'  
                     Pthresold = NA
                 }
 
+                # Stores info needed to plot
                 Periods_trend = append(Periods_trend, Periods)
                 NPeriod_trend = append(NPeriod_trend, j)
                 Type_trend = append(Type_trend, type)
@@ -253,10 +267,9 @@ matrix_panel = function (list_df2plot, df_meta, trend_period, mean_period, slice
         }
     }
 
-    
     # If there is a 'mean_period'
     if (!is.null(mean_period)) {
-        
+        # Blank vectors to store info about mean analyses
         Periods_mean = c()
         NPeriod_mean = c()
         Type_mean = list()
@@ -269,9 +282,11 @@ matrix_panel = function (list_df2plot, df_meta, trend_period, mean_period, slice
         # Number of mean period
         nPeriod_mean = length(mean_period)
 
+        # Blank array to store difference of mean between two periods
         BreakMean_code = array(rep(1, nPeriod_mean*nbp*nCode),
                                dim=c(nPeriod_mean, nbp, nCode))
-        
+        # Blank array to store mean for a temporary period in order
+        # to compute the difference of mean with a second period
         dataMeantmp = array(rep(NA, nbp*nCode),
                             dim=c(nbp, nCode))
         
@@ -311,18 +326,24 @@ matrix_panel = function (list_df2plot, df_meta, trend_period, mean_period, slice
                     dataMean = mean(df_data_code_per$Qm3s,
                                     na.rm=TRUE)
 
+                    # If this in not the first period
                     if (j > 1) {
+                        # Compute the difference of mean
                         Break = dataMean - dataMeantmp[i, k]
+                    # Otherwise for the first period
                     } else {
+                        # Stocks NA
                         Break = NA
                     }
-                    
+                    # Normalises the break by the mean of the
+                    # initial period
                     BreakMean = Break / dataMeantmp[i, k]
+                    # Stores the result
                     BreakMean_code[j, i, k] = BreakMean
-                    
+                    # Stores temporarily the mean of the current period
                     dataMeantmp[i, k] = dataMean
                     
-                    
+                    # Stores info needed to plot
                     Periods_mean = append(Periods_mean, Periods)
                     NPeriod_mean = append(NPeriod_mean, j)
                     Type_mean = append(Type_mean, type)
@@ -333,15 +354,16 @@ matrix_panel = function (list_df2plot, df_meta, trend_period, mean_period, slice
                 }
             }
         }
-        
+        # Computes the min and the max of the mean trend for
+        # all the station
         minBreakMean = apply(BreakMean_code, c(1, 2),
                              min, na.rm=TRUE)
         maxBreakMean = apply(BreakMean_code, c(1, 2),
                              max, na.rm=TRUE)
-
+        # Blanks vector to store color info
         Fill_mean = c()
         Color_mean = c()
-
+        # Index to count over all break computed
         ii = 1
         for (j in 1:nPeriod_mean) {
             # For all the code
@@ -350,52 +372,59 @@ matrix_panel = function (list_df2plot, df_meta, trend_period, mean_period, slice
                 code = Code[k]
                 # For all variable
                 for (i in 1:nbp) {
-                    
+                    # Extracts break mean
                     BreakMean = BreakMean_mean[ii]
-                    
+                    # Gets the color associated
                     color_res = get_color(BreakMean, 
                                           minBreakMean[j, i],
                                           maxBreakMean[j, i],
                                           palette_name='perso',
                                           reverse=TRUE)
-                    
+                    # Gets the fill and contour color
                     fill = color_res
                     color = 'white'
-
+                    # Stores it
                     Fill_mean = append(Fill_mean, fill)
                     Color_mean = append(Color_mean, color)
-                    
+                    # Passes to the next index
                     ii = ii + 1
                 }
             }
         }
     }
 
-
+    # If the slice option is not specified, the info for all
+    # stations will be draw on the same page 
     if (is.null(slice)) {
         slice = nCode
     }
 
+    # Extracts each possibilities of first letter of station code
     firstLetter = levels(factor(substr(Code, 1, 1)))
-    
+    # For all the available first letter
     for (fL in firstLetter) {
-
+        # Print the matrix name
         print(paste('Matrix for region :', fL))
 
         # Get only station code with the same first letter 
         subCodefL = Code[substr(Code, 1, 1) == fL]
+        # Counts the number of station in it
         nsubCodefL = length(subCodefL)
-        
+        # Computes the number of pages needed to plot all stations
         nMat = as.integer(nsubCodefL/slice) + 1
-        
+        # For all the pages
         for (imat in 1:nMat) {
+            # Extracts the station for the current page
             subCode = subCodefL[(slice*(imat-1)+1):(slice*imat)]
-
+            # Removes NA stations
             subCode = subCode[!is.na(subCode)]
+            # Gets the number of station for the page
             nsubCode = length(subCode)
 
+            # Creates logical vector to select only info about
+            # stations that will be plot on the page
             CodefL_trend = Code_trend %in% subCode
-            
+            # Extracts those info
             subPeriods_trend = Periods_trend[CodefL_trend]
             subNPeriod_trend = NPeriod_trend[CodefL_trend]
             subType_trend = Type_trend[CodefL_trend]
@@ -405,9 +434,10 @@ matrix_panel = function (list_df2plot, df_meta, trend_period, mean_period, slice
             subDataMean_trend = DataMean_trend[CodefL_trend]
             subFill_trend = Fill_trend[CodefL_trend]
             subColor_trend = Color_trend[CodefL_trend]
-            
+
+            # Same for mean difference analysis
             CodefL_mean = Code_mean %in% subCode
-            
+            # Extracts right info
             subPeriods_mean = Periods_mean[CodefL_mean]
             subNPeriod_mean = NPeriod_mean[CodefL_mean]
             subType_mean = Type_mean[CodefL_mean]
@@ -416,9 +446,10 @@ matrix_panel = function (list_df2plot, df_meta, trend_period, mean_period, slice
             subBreakMean_mean = BreakMean_mean[CodefL_mean]
             subFill_mean = Fill_mean[CodefL_mean]
             subColor_mean = Color_mean[CodefL_mean]
-            
-            title = df_meta[df_meta$code == subCode[1],]$region_hydro
 
+            # Extracts the name of the currently hydrological
+            # region plotted
+            title = df_meta[df_meta$code == subCode[1],]$region_hydro
             
             ### Plot ###
             height = nsubCode