From d0980ad4d27b4946713cab5e47ed9a5595954fb1 Mon Sep 17 00:00:00 2001
From: "BERTHET Clement (Externe)" <clement.berthet_externe@rte-france.com>
Date: Wed, 17 Jan 2024 12:07:43 +0100
Subject: [PATCH] readBindingConstraints add badge + update doc

---
 R/readBindingConstraints.R        | 52 +++++++++++++++++++++++------
 man/readBindingConstraints.Rd     | 54 +++++++++++++++++++++++++------
 man/summary.bindingConstraints.Rd |  1 +
 3 files changed, 88 insertions(+), 19 deletions(-)

diff --git a/R/readBindingConstraints.R b/R/readBindingConstraints.R
index ac2ee782..dd181e8c 100644
--- a/R/readBindingConstraints.R
+++ b/R/readBindingConstraints.R
@@ -3,6 +3,9 @@
 #' Read binding constraints
 #' 
 #' @description 
+#' `r antaresRead:::badge_api_ok()`
+#' `r lifecycle::badge("experimental")`  
+#' 
 #' This function reads the binding constraints of an Antares project. 
 #' 
 #' Be aware that binding constraints are read in the input files of a study. So
@@ -11,15 +14,28 @@
 #' @inheritParams readAntares
 #' 
 #' @return 
-#' \code{readBindingConstraints} returns an object of class \code{bindingConstraints}.
-#' It is a named list with one element per read constraint. Each element is itself
-#' a list with the following elements: 
-#' \item{enabled}{is the constraint enabled ?}
-#' \item{timeStep}{time step the constraint applies to}
-#' \item{operator}{type of constraint: equality, inequality on one side or both sides}
-#' \item{coefficients}{elements containing the coefficients used by the constraint}
-#' \item{values}{values used by the constraint. It contains one line per time step
-#'   and three columns "less", "greater" and "equal"}
+#' An object of class \code{bindingConstraints}. This object is also a named 
+#' list with 3 sections per read constraint.
+#' 
+#' @section Warning:
+#' Since `release 2.7.0` the structure of the returned object has evolved for 
+#' all versions of study Antares:  
+#'  - .ini parameters are in section `properties`
+#'  - Coeffcients links or thermal are in section `coefs`  
+#'  - Values are already in section `values`
+#'  
+#' @note 
+#' For an study Antares **version >=8.7.0**. Now contains `data.frame` with 
+#' one line per time step and \eqn{p} colums according to "scenarized RHS".  
+#' 
+#' For "both" case, you will find in section `values` two `data.frame` :  
+#'  - One `data.frame` for `less` 
+#'  - One `data.frame` for `greater`
+#'  
+#' For an study Antares **version <8.7.0**.  
+#' 
+#' Section \code{values} contains one line 
+#' per time step and three columns "less", "greater" and "equal"
 #' 
 #' 
 #' 
@@ -28,6 +44,20 @@
 #' setSimulationPath()
 #'
 #' constraints <- readBindingConstraints()
+#' 
+#' # read properties
+#' constraints$properties
+#' 
+#' # read coefs
+#' constraints$coefs
+#' 
+#' # read values
+#' constraints$values
+#'   # both case ( study Antares >=8.7.0)
+#' constraints$values$less
+#' constraints$values$greater
+#' 
+#' # display equation (only for study Antares <8.7.0)
 #' summary(constraints)
 #' 
 #' }
@@ -287,8 +317,10 @@ readBindingConstraints <- function(opts = simOptions()) {
   return(core_list)
 }
 
-#' `r lifecycle::badge("deprecated")`
 #' @title Display equation of binding constraint
+#' @description 
+#' `r lifecycle::badge("deprecated")`
+#' This function cannot be used for a study `>= 8.7.0`
 #' @param object Object returned by readBindingConstraints
 #' @param ... Unused
 #' 
diff --git a/man/readBindingConstraints.Rd b/man/readBindingConstraints.Rd
index 51c8052e..83de9997 100644
--- a/man/readBindingConstraints.Rd
+++ b/man/readBindingConstraints.Rd
@@ -11,27 +11,63 @@ readBindingConstraints(opts = simOptions())
 \code{\link{setSimulationPath}}}
 }
 \value{
-\code{readBindingConstraints} returns an object of class \code{bindingConstraints}.
-It is a named list with one element per read constraint. Each element is itself
-a list with the following elements:
-\item{enabled}{is the constraint enabled ?}
-\item{timeStep}{time step the constraint applies to}
-\item{operator}{type of constraint: equality, inequality on one side or both sides}
-\item{coefficients}{elements containing the coefficients used by the constraint}
-\item{values}{values used by the constraint. It contains one line per time step
-and three columns "less", "greater" and "equal"}
+An object of class \code{bindingConstraints}. This object is also a named
+list with 3 sections per read constraint.
 }
 \description{
+\ifelse{html}{\figure{badge_api_ok.svg}{options: alt='Antares API OK'}}{Antares API: \strong{OK}}
+\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
+
 This function reads the binding constraints of an Antares project.
 
 Be aware that binding constraints are read in the input files of a study. So
 they may have changed since a simulation has been run.
 }
+\note{
+For an study Antares \strong{version >=8.7.0}. Now contains \code{data.frame} with
+one line per time step and \eqn{p} colums according to "scenarized RHS".
+
+For "both" case, you will find in section \code{values} two \code{data.frame} :
+\itemize{
+\item One \code{data.frame} for \code{less}
+\item One \code{data.frame} for \code{greater}
+}
+
+For an study Antares \strong{version <8.7.0}.
+
+Section \code{values} contains one line
+per time step and three columns "less", "greater" and "equal"
+}
+\section{Warning}{
+
+Since \verb{release 2.7.0} the structure of the returned object has evolved for
+all versions of study Antares:
+\itemize{
+\item .ini parameters are in section \code{properties}
+\item Coeffcients links or thermal are in section \code{coefs}
+\item Values are already in section \code{values}
+}
+}
+
 \examples{
 \dontrun{
 setSimulationPath()
 
 constraints <- readBindingConstraints()
+
+# read properties
+constraints$properties
+
+# read coefs
+constraints$coefs
+
+# read values
+constraints$values
+  # both case ( study Antares >=8.7.0)
+constraints$values$less
+constraints$values$greater
+
+# display equation (only for study Antares <8.7.0)
 summary(constraints)
 
 }
diff --git a/man/summary.bindingConstraints.Rd b/man/summary.bindingConstraints.Rd
index f00ec913..e2d2f3c7 100644
--- a/man/summary.bindingConstraints.Rd
+++ b/man/summary.bindingConstraints.Rd
@@ -16,4 +16,5 @@ A data.frame with one line per constraint.
 }
 \description{
 \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
+This function cannot be used for a study \verb{>= 8.7.0}
 }