Update docstrings

ramp/core/core.py

@@ -62,9 +62,13 @@ def __init__(
         users : Union[Iterable,None], optional
             a list of users to be added to the usecase instance, by default None
         date_start: str, optional
+            start date of the daily profiles generated by the UseCase instance
         date_end: str, optional
+            end date of the daily profiles generated by the UseCase instance
         parallel_processing: bool, optional
+            if set True, the profiles will be generated in parallel rather than sequencially
         peak_enlarge: float, optional
+            percentage random enlargement or reduction of peak time range length, used in UseCase.calc_peak_time_range
 
         """
         self.name = name
@@ -98,6 +102,7 @@ def __init__(
 
     @property
     def date_start(self):
+        """Start date of the daily profiles generated by the UseCase instance"""
         return self._date_start
 
     @date_start.setter
@@ -110,6 +115,7 @@ def date_start(self, new_date):
 
     @property
     def date_end(self):
+        """End date of the daily profiles generated by the UseCase instance"""
         return self._date_end
 
     @date_end.setter
@@ -126,16 +132,24 @@ def peak_enlarge(self):
 
     @peak_enlarge.setter
     def peak_enlarge(self, new_peak_enlarge):
-        self._peak_enlarge = new_peak_enlarge
-        self.peak_time_range = self.calc_peak_time_range()
+        """Percentage random enlargement or reduction of peak time range length, used in UseCase.calc_peak_time_range"""
+
+        if isinstance(new_peak_enlarge, float):
+            if new_peak_enlarge >= 0:
+                self._peak_enlarge = new_peak_enlarge
+                self.peak_time_range = self.calc_peak_time_range()
+            else:
+                raise ValueError("peak enlarge value must be greater than 0")
+        else:
+            raise TypeError("peak enlarge must be a float")
 
     def add_user(self, user) -> None:
         """adds new user to the user property list
 
         Parameters
         ----------
         user : User
-            an user instance
+            a user instance
 
         Raises
         ------
@@ -154,24 +168,43 @@ def add_user(self, user) -> None:
             )
 
     def collect_appliances_from_users(self):
+        """Gather all appliances from a UseCase instance users into self.appliances attribute"""
         appliances = []
         for user in self.users:
             appliances = appliances + user.App_list
         self.appliances = appliances
 
     @property
     def num_days(self):
+        """Number of days for which the UseCase instance will be able to generate profiles"""
         if self.__num_days is None:
             self.initialize()
         return self.__num_days
 
     @property
     def datetimeindex(self):
+        """Return the datetimeindex of the UseCase and call UseCase.initialize() if it was not set"""
         if self.__datetimeindex is None:
             self.initialize()
         return self.__datetimeindex
 
-    def initialize(self, num_days=None, peak_enlarge=None, force=False):
+    def initialize(
+        self, num_days: int = None, peak_enlarge: float = None, force: bool = False
+    ):
+        """Sets the list of days for which to generate profiles and compute peak time range
+
+        Parameters
+        ----------
+        num_days: int, optional
+            if provided it will set the number of days on which profiles will be generated (num_days from date_start
+            or num_days until date_end). If both date_start and date_end are provided, num_days will run from date_start
+            and a warning will be printed
+        peak_enlarge: float, optional
+            percentage random enlargement or reduction of peak time range length, used in UseCase.calc_peak_time_range
+        force: bool, optional
+            if the UseCase instance has already been initialized, it can be forced to take new values with this option set to True
+
+        """
         # TODO allow calendar years multi-year inputs
 
         if self.is_initialized is True and force is False:
@@ -193,7 +226,7 @@ def initialize(self, num_days=None, peak_enlarge=None, force=False):
                 if self.days is not None:
                     # logging.error
                     print(
-                        f"You want to initialize the usecase '{self.name}' with num_days but you already have provided days. This might be the case if you use UseCase.load before you used UseCase.initialize()"
+                        f"You want to initialize the usecase '{self.name}' with num_days but you already have provided days. This might be the case if you use UseCase.load() before you used UseCase.initialize()"
                     )
                     self.__num_days = None
 
@@ -256,7 +289,10 @@ def initialize(self, num_days=None, peak_enlarge=None, force=False):
                 print(
                     f"You will simulate {self.__num_days} day(s) from {self.days[0]} until {self.days[-1]+datetime.timedelta(days=1)}"
                 )
-            self.peak_time_range = self.calc_peak_time_range(peak_enlarge=peak_enlarge)
+            if peak_enlarge is not None:
+                self.peak_enlarge = peak_enlarge
+            else:
+                self.peak_time_range = self.calc_peak_time_range()
             # format datetimeindex in minutes
             self.__datetimeindex = pd.date_range(
                 start=self.days[0],
@@ -302,6 +338,8 @@ def calc_peak_time_range(self, peak_enlarge=None):
 
         if peak_enlarge is None:
             peak_enlarge = self.peak_enlarge
+        else:
+            self.peak_enlarge = peak_enlarge
 
         tot_max_profile = np.zeros(1440)  # creates an empty daily profile
         # Aggregate each User's theoretical max profile to the total theoretical max
@@ -334,13 +372,18 @@ def generate_daily_load_profiles(
 
         Parameters
         ----------
-        days: datetimeindex
+        days: datetimeindex, optional
             a list of days for which to generate daily profiles, if None, then self.days is used instead
-        flat: boolean
+        flat: boolean, optional
             flatten the daily profiles into a 1 dimensional array via reshaping
-        cases: iterable
+        cases: iterable, optional
             a list of label of the different cases. This is used if one would like to compare several independent runs
-            of a ramp UseCase, in that case the method returns a ramp.Plot object
+            of a ramp UseCase instance, in that case the method returns a ramp.Plot object
+        verbose: boolean, optional
+
+        Returns
+        -------
+        daily_profiles: numpy array
         """
         if cases is not None:
             results = {}
@@ -387,6 +430,20 @@ def generate_daily_load_profiles(
         return answer
 
     def generate_daily_load_profiles_parallel(self, days=None, flat=True):
+        """
+        Generate a daily profile for each of the days in a parallel process
+
+        Parameters
+        ----------
+        days: datetimeindex, optional
+            a list of days for which to generate daily profiles, if None, then self.days is used instead
+        flat: boolean, optional
+            flatten the daily profiles into a 1 dimensional array via reshaping
+
+        Returns
+        -------
+        daily_profiles: numpy array
+        """
         if self.days is None:
             if days is not None:
                 self.days = days  # TODO this might be wrong need to update the date_start, end num_days etc