From d4ccd7c4dc4d2b2fc6af94bfee135e2920f43e5c Mon Sep 17 00:00:00 2001 From: amandamalk0601 Date: Mon, 6 Nov 2023 12:12:29 +0100 Subject: [PATCH] fixed inconsistent docstrings --- vessim/__init__.py | 37 ++++++++++++++++++++++--------------- vessim/analysis.py | 7 ++++--- vessim/core/storage.py | 9 +++++---- vessim/sil/api_server.py | 13 +++++++------ vessim/sil/http_client.py | 4 ++-- vessim/sil/node.py | 2 +- 6 files changed, 41 insertions(+), 31 deletions(-) diff --git a/vessim/__init__.py b/vessim/__init__.py index cc22cd45..c160f0cd 100644 --- a/vessim/__init__.py +++ b/vessim/__init__.py @@ -19,17 +19,22 @@ class TimeSeriesApi: actual data between timestamps is computed using either `ffill` or `bfill`. If you wish a different behavior, you have to change your actual data beforehand (e.g. by resampling into a different frequency). - forecast: An optional time-series dataset representing forecasted values. - The data should contain two datetime-like indices. One is the + + forecast: An optional time-series dataset representing forecasted values. The + data should contain two datetime-like indices. One is the `Request Timestamp`, marking the time when the forecast was made. One is the `Forecast Timestamp`, indicating the time the forecast is made for. + - If data does not include a `Request Timestamp`, it is treated as a static - forecast that does not change over time. - - If `forecast` is not provided, predictions are derived from the actual data - when requesting forecasts (actual data is treated as static forecast). + forecast that does not change over time. + + - If `forecast` is not provided, predictions are derived from the actual + data when requesting forecasts (actual data is treated as static forecast). + - When using a non-static forecast, you have to be aware that all the - zones/column names also have to appear in the actual dataframe because - some actual values are used for interpolation. + zones/column names also have to appear in the actual dataframe because some + actual values are used for interpolation. + fill_method: Either `ffill` or `bfill`. Determines how actual data is acquired in between timestamps. Some data providers like `Solcast` index their data with a timestamp marking the end of the time-period that the data is valid for. @@ -109,7 +114,7 @@ def actual(self, dt: DatetimeLike, zone: Optional[str] = None) -> Any: Args: dt: Timestamp, at which the data is needed. - zone: Optional Zone for the data. Has to be provided if there is more than one + zone: Optional zone for the data. Has to be provided if there is more than one zone specified in the data. Defaults to None. Raises: @@ -136,10 +141,10 @@ def forecast( - If no forecast time-series data is provided, actual data is used. - Specified timestamps are always rounded down to the nearest existing. - If frequency is not specified, all existing data in the window will be returned. - - For various resampling methods, the actual value valid at start_time is used. - So you have to make sure that there is a valid actual value. + - For various resampling methods, the actual value valid at `start_time` is used. + So you have to make sure that there is a valid actual value. - If there is more than one zone present in the data, zone has to be specified. - (Note that zone name must also appear in actual data for non-static forecast.) + (Note that zone name must also appear in actual data for non-static forecast.) - The forecast does not include the value at `start_time` (see example). Args: @@ -149,15 +154,17 @@ def forecast( frequency: Optional interval, in which the forecast data is to be provided. Defaults to None. resample_method: Optional method, to deal with holes in resampled data. - Can be either 'bfill', 'ffill' or an interpolation method. - https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.interpolate.html#pandas.DataFrame.interpolate) + Can be either `bfill`, `ffill` or an interpolation method. + For more information on interpolation methods, see the + `pandas documentation `_. Returns: pd.Series of forecasted data with timestamps of forecast as index. Raises: - ValueError: If there is no available data at apecified zone or time, or - there is not enough data for frequency, without resample_method specified. + ValueError: If no data is available for the specified zone or time, or if + insufficient data exists for the frequency, without `resample_method` + specified. Example: >>> index = pd.date_range( diff --git a/vessim/analysis.py b/vessim/analysis.py index 1eecf3e1..2473efe0 100644 --- a/vessim/analysis.py +++ b/vessim/analysis.py @@ -5,11 +5,11 @@ def plot_basic_evaluation(data: pd.DataFrame, title: str = "Evaluation"): - """Simple function for plotting of the simulation _data. + """Simple function for plotting of the simulation data. Args: data: The dataframe containing the simulation data. - title: The title of the plot. Defaults to `Evaluation` + title: The title of the plot. Defaults to `Evaluation`. """ data.index = pd.to_datetime(data.index) @@ -100,7 +100,8 @@ def plot_accumulated_emissions( ) -> float: """Create plot of total carbon emission over time. - Returns: The total emission over the whole simulation as float. + Returns: + The total emission over the whole simulation as float. """ emissions = (-p_grid) * carbon_intensity # 60 Ws * gCO2/kWh emissions /= 60000 diff --git a/vessim/core/storage.py b/vessim/core/storage.py index aea3cee4..1e41da8b 100644 --- a/vessim/core/storage.py +++ b/vessim/core/storage.py @@ -29,10 +29,11 @@ class SimpleBattery(Storage): """(Way too) simple battery. Args: - capacity: Battery capacity in Ws - charge_level: Initial charge level in Ws - min_soc: Minimum allowed soc for the battery - c_rate: C-rate (https://www.batterydesign.net/electrical/c-rate/) + capacity: Battery capacity in watt-seconds (Ws). + charge_level: Initial charge level in watt-seconds (Ws). + min_soc: Minimum allowed state of charge (SoC) for the battery. + c_rate: C-rate, which defines the charge and discharge rate of the battery. + For more information on C-rate, see `C-rate explanation `_. """ def __init__( diff --git a/vessim/sil/api_server.py b/vessim/sil/api_server.py index de06ec77..ffaa14fc 100644 --- a/vessim/sil/api_server.py +++ b/vessim/sil/api_server.py @@ -19,7 +19,7 @@ class SilApi(ABC): necessary cleanup tasks of the child process running the API. Attributes: - app: The FastApi instance to be runned. + app: The FastApi instance to be run. """ def __init__(self) -> None: @@ -39,8 +39,10 @@ class ApiServer(multiprocessing.Process): Args: api_type: The type of the class containing the app to be executed. - host: The host address, defaults to '127.0.0.1'. - port: The port to run the FastAPI application, defaults to 8000. + host: The host address where the server will be accessible. + Defaults to '127.0.0.1'. + port: The port number on which the FastAPI application will run. + Defaults to 8000. """ def __init__( @@ -84,11 +86,10 @@ class VessimApi(SilApi): """Specialized Vessim API to be executed in a different process. Initializes a FastAPI instance with specific routes related to the Vessim API. - This app is very specific for the use case of the vessim vision paper: - https://arxiv.org/pdf/2306.09774.pdf + This app is very specific for the use case of the `Vessim vision paper `_. Attributes: - app: The FastApi instance to be runned. + app: The FastApi instance to be run. """ def __init__(self) -> None: diff --git a/vessim/sil/http_client.py b/vessim/sil/http_client.py index d1003e73..cda1c79c 100644 --- a/vessim/sil/http_client.py +++ b/vessim/sil/http_client.py @@ -22,7 +22,7 @@ def get(self, route: str) -> dict: route: The path of the endpoint to send the request to. Raises: - HTTPError if response code is != 200. + HTTPError: If response code is != 200. Returns: A dictionary containing the response. @@ -41,7 +41,7 @@ def put(self, route: str, data: Dict[str, Any] = {}) -> None: data: The data to be updated, in dictionary format. Raises: - HTTPError if response code is != 200. + HTTPError: If response code is != 200. """ headers = {"Content-type": "application/json"} response = requests.put( diff --git a/vessim/sil/node.py b/vessim/sil/node.py index 25a6499d..4c38fcf9 100644 --- a/vessim/sil/node.py +++ b/vessim/sil/node.py @@ -10,7 +10,7 @@ class Node: id: A unique ID assigned to each node. address: The network address of the node. port: The application port of the node api. - power_mode: The power mode of the node. Default is "high performance". + power_mode: The power mode of the node. Default is `high performance`. """ existing_ids: Set[str] = set()