fix docstrings for API

brightway-lca · Oct 28, 2024 · e3ca084 · e3ca084
1 parent 9e76f67
commit e3ca084
Show file tree

Hide file tree

Showing 7 changed files with 83 additions and 73 deletions.
diff --git a/bw_timex/dynamic_biosphere_builder.py b/bw_timex/dynamic_biosphere_builder.py
@@ -11,8 +11,7 @@
 
 class DynamicBiosphereBuilder:
     """
-    Class for building a dynamic biosphere matrix with dimensions
-    (biosphere flow at a specific point in time) x (processes)
+    Class for building a dynamic biosphere matrix with dimensions (biosphere flow at a specific point in time) x (processes)
     """
 
     def __init__(
@@ -344,7 +343,8 @@ def add_matrix_entry_for_biosphere_flows(self, row, col, amount):
 
         Returns
         -------
-        None, but the lists of row, col and values are updated
+        None
+            the lists of row, col and values are updated
 
         """
 

diff --git a/bw_timex/edge_extractor.py b/bw_timex/edge_extractor.py
@@ -34,8 +34,8 @@ class Edge:
 
 class EdgeExtractor(TemporalisLCA):
     """
-    Child class of TemporalisLCA that traverses the supply chain just as the parent
-    class but can create a timeline of edges, in addition timeline of flows or nodes.
+    Child class of TemporalisLCA that traverses the supply chain just as the parent class but can create a timeline of edges, in addition timeline of flows or nodes.
+
     The edge timeline is then used to match the timestamp of edges to that of background
     databases and to replace these edges with edges from these background databases
     using Brightway Datapackages.
@@ -56,8 +56,8 @@ def __init__(self, *args, edge_filter_function: Callable = None, **kwargs) -> No
 
         Returns
         -------
-        None but stores the output of the TemporalisLCA graph traversal (incl. relation
-        of edges (edge_mapping) and nodes (node_mapping) in the instance of the class.
+        None
+            stores the output of the TemporalisLCA graph traversal (incl. relation of edges (edge_mapping) and nodes (node_mapping) in the instance of the class.
 
         """
         super().__init__(*args, **kwargs)  # use __init__ of TemporalisLCA

diff --git a/bw_timex/helper_classes.py b/bw_timex/helper_classes.py
@@ -2,11 +2,11 @@
 
 
 class SetList:
-    """A little helper class fot the mapping of the same/mapped activity in different (temporal) databases.
-    It contains a list of sets, that hold can hold the set of tuples of (act_id, database). It is built by
-    adding sets to the list, and returns the matching sets if one calls the an item from a set.
+    """A helper class for the mapping of the same/mapped activity in different (temporal) databases, composed of a list of sets, that hold can hold the set of tuples of (act_id, database).
+    It is built by adding sets to the list, and returns the matching sets if one
+    calls the an item from a set.
 
-    Example: If the class instance is called my_setlist, my_setlist.add(set). When called
+    Example: If the class instance is called my_setlist, my_setlist.add(set).
     """
 
     def __init__(
@@ -20,13 +20,14 @@ def add(
     ) -> None:
         """
         This method adds a set to the SetList instance.
-        Input
+
+        Parameters
         -----
         new_set: a set to add to the SetList instance
 
         Returns
         -------
-        None (or rather nothing)
+        None
 
         """
 
@@ -80,8 +81,7 @@ def __repr__(self):
 
 class TimeMappingDict(dict):
     """
-    This class is used to create a dictionary that maps a tuple of (flow and timestamp)
-    to an unique integer id.
+    This class is used to create a dictionary that maps a tuple of (flow and timestamp) to an unique integer id.
     """
 
     def __init__(self, start_id=2, *args, **kwargs) -> None:

diff --git a/bw_timex/matrix_modifier.py b/bw_timex/matrix_modifier.py
@@ -79,7 +79,7 @@ def create_technosphere_datapackage(self) -> bwp.Datapackage:
         of this node (e.g. steel production on 2020-01-01 and steel production on 2015-01-01)
         becomes a separate, time-explicit new node, by adding the new elements to the technosphere matrix.
         For processes at the intersection with background databases, the timing of the exchanges
-         determines which background database to link to in so called "Temporal Markets".
+        determines which background database to link to in so called "Temporal Markets".
 
         Parameters
         ----------
@@ -182,12 +182,17 @@ def add_row_to_datapackage(
         """
         This adds the modifications to the technosphere matrix for each time-dependent exchange
         as datapackage elements to a given `bwp.Datapackage`.
+
+
         Modifications include:
+
         1) Exploded processes: new matrix elements for time-explicit consumer and time-explicit
         producer, representing the temporal edge between them.
+
         2) Temporal markets: new matrix entries for "temporal markets" and links to the producers
         in temporally matching background databases. Processes in the background databases are
         matched on name, reference product and location.
+
         3) Diagonal entries: ones on the diagonal for new nodes.
 
         This function also collects the ids of new nodes, temporalized nodes and temporal markets.
@@ -203,8 +208,8 @@ def add_row_to_datapackage(
 
         Returns
         -------
-        None but adds elements for this edge to the bwp.Datapackage and stores the ids of new nodes,
-        temporalized nodes and temporal markets.
+        None
+            Adds elements for this edge to the bwp.Datapackage and stores the ids of new nodes, temporalized nodes and temporal markets.
         """
 
         if row.consumer == -1:  # functional unit

diff --git a/bw_timex/timeline_builder.py b/bw_timex/timeline_builder.py
@@ -118,9 +118,12 @@ def build_timeline(self) -> pd.DataFrame:
         For edges between foreground and background system, the column "interpolation weights"
         assigns the ratio [0-1] of the edge's amount to be taken from the database with the closest
         time of representativeness. If a process is in the foreground system only, the interpolation weight is set to None.
+
         Available interpolation types are:
-            - "linear": linear interpolation between the two closest databases, based on temporal distance.
-            - "closest": closest database is assigned 1
+
+        - "linear": linear interpolation between the two closest databases, based on temporal distance.
+
+        - "closest": closest database is assigned 1
 
         Parameters
         ----------

diff --git a/bw_timex/timex_lca.py b/bw_timex/timex_lca.py
@@ -300,13 +300,13 @@ def lci(
 
         Returns
         -------
-        None, but calls LCI calculations from bw2calc and calculates the dynamic inventory, if
-        `build_dynamic_biosphere` is True.
+        None
+            calls LCI calculations from bw2calc and calculates the dynamic inventory, if
+            `build_dynamic_biosphere` is True.
 
         See also
         --------
-        build_datapackage: Method to create the datapackages that contain the modifications
-        to the technosphere and biosphere matrix using the `MatrixModifier` class.
+        build_datapackage: Method to create the datapackages that contain the modifications to the technosphere and biosphere matrix using the `MatrixModifier` class.
         calculate_dynamic_inventory: Method to calculate the dynamic inventory if `build_dynamic_biosphere` is True.
         """
 
@@ -368,7 +368,8 @@ def static_lcia(self) -> None:
 
         Returns
         -------
-        None, but stores the static score in the attribute `static_score`.
+        None
+            Stores the static score in the attribute `static_score`.
         """
         if not hasattr(self, "lca"):
             raise AttributeError("LCI not yet calculated. Call TimexLCA.lci() first.")
@@ -439,8 +440,7 @@ def dynamic_lcia(
 
         See also
         --------
-        dynamic_characterization: Package handling the dynamic characterization:
-        https://dynamic-characterization.readthedocs.io/en/latest/
+        dynamic_characterization: Package handling the dynamic characterization: https://dynamic-characterization.readthedocs.io/en/latest/
         """
 
         if not hasattr(self, "dynamic_inventory"):
@@ -582,13 +582,13 @@ def calculate_dynamic_inventory(
 
         Returns
         -------
-        None, but calculates the dynamic inventory and stores it in the attribute
-        `dynamic_inventory` as a matrix and in `dynamic_inventory_df` as a DataFrame.
+        None
+            calculates the dynamic inventory and stores it in the attribute
+            `dynamic_inventory` as a matrix and in `dynamic_inventory_df` as a DataFrame.
 
         See also
         --------
-        bw_timex.dynamic_biosphere_builder.DynamicBiosphereBuilder: Class for creating
-        the dynamic biosphere matrix and inventory.
+        bw_timex.dynamic_biosphere_builder.DynamicBiosphereBuilder: Class for creating the dynamic biosphere matrix and inventory.
         """
 
         if not hasattr(self, "lca"):
@@ -759,9 +759,7 @@ def prepare_base_lca_inputs(
 
         See also
         --------
-        bw2data.compat.prepare_lca_inputs: Original code this function is adapted from
-        (https://github.com/brightway-lca/brightway2-data/blob/main/bw2data/compat.py).
-
+        bw2data.compat.prepare_lca_inputs: Original code this function is adapted from (https://github.com/brightway-lca/brightway2-data/blob/main/bw2data/compat.py).
         """
         if not projects.dataset.data.get("25"):
             raise Brightway2Project(
@@ -873,8 +871,7 @@ def prepare_bw_timex_inputs(
 
         See also
         --------
-        bw2data.compat.prepare_lca_inputs: Original code this function is adapted
-        from (https://github.com/brightway-lca/brightway2-data/blob/main/bw2data/compat.py).
+        bw2data.compat.prepare_lca_inputs: Original code this function is adapted from (https://github.com/brightway-lca/brightway2-data/blob/main/bw2data/compat.py).
         """
 
         if not projects.dataset.data.get("25"):
@@ -971,7 +968,8 @@ def check_format_database_date_dict(self) -> None:
 
         Returns
         -------
-        None, but raises an error if the format is not correct or the databases are not available.
+        None
+            raises an error if the format is not correct or the databases are not available.
 
         """
         for database, value in self.database_date_dict.items():
@@ -992,21 +990,13 @@ def create_node_id_collection_dict(self) -> None:
         Available collections are:
 
         - ``demand_database_names``: set of database names of the demand processes
-        - ``demand_dependent_database_names``: set of database names of all processes
-        that depend on the demand processes
-        - ``demand_dependent_background_database_names``: set of database names of all
-        processes that depend on the demand processes and are in the background databases
-        - ``demand_dependent_background_node_ids``: set of node ids of all processes
-        that depend on the demand processes and are in the background databases
-        - ``foreground_node_ids``: set of node ids of all processes that are
-        not in the background databases
-        - ``first_level_background_node_ids_static``: set of node ids of all
-        processes that are in the background databases and are directly linked to the demand processes
-        - ``first_level_background_node_ids_interpolated``: like first_level_background_node_ids_static,
-        but includes first level background processes from the other time explicit databases that are
-        used (is filled after timeline is built)
-        - ``first_level_background_node_id_dbs``: dictionary with the first_level_background_node_ids_static
-        as keys returning their database
+        - ``demand_dependent_database_names``: set of database names of all processes that depend on the demand processes
+        - ``demand_dependent_background_database_names``: set of database names of all processes that depend on the demand processes and are in the background databases
+        - ``demand_dependent_background_node_ids``: set of node ids of all processes that depend on the demand processes and are in the background databases
+        - ``foreground_node_ids``: set of node ids of all processes that are not in the background databases
+        - ``first_level_background_node_ids_static``: set of node ids of all processes that are in the background databases and are directly linked to the demand processes
+        - ``first_level_background_node_ids_interpolated``: like first_level_background_node_ids_static, but includes first level background processes from the other time explicit databases that are used (is filled after timeline is built)
+        - ``first_level_background_node_id_dbs``: dictionary with the first_level_background_node_ids_static as keys returning their database
 
         It also initiates an instance of SetList which contains all mappings of equivalent
         activities across time-specific databases:
@@ -1019,8 +1009,9 @@ def create_node_id_collection_dict(self) -> None:
 
         Returns
         -------
-            None, but adds the `node_id_collection_dict containing` the above-mentioned collections,
-            as well as interdatabase_activity_mapping
+            None
+                adds the `node_id_collection_dict containing` the above-mentioned collections,
+                as well as interdatabase_activity_mapping
         """
         self.node_id_collection_dict = {}
 
@@ -1096,9 +1087,10 @@ def add_interdatabase_activity_mapping_from_timeline(self) -> None:
 
         Returns
         -------
-        None, but adds the ids of producers in other background databases
-        (only those interpolated to in the timeline) to the `interdatabase_activity_mapping`
-        and `node_id_collection["first_level_background_node_ids_interpolated"]`.
+        None
+            Adds the ids of producers in other background databases
+            (only those interpolated to in the timeline) to the `interdatabase_activity_mapping`
+            and `node_id_collection["first_level_background_node_ids_interpolated"]`.
         """
         if not hasattr(self, "timeline"):
             warnings.warn(
@@ -1177,8 +1169,9 @@ def collect_temporalized_processes_from_timeline(self) -> None:
 
         Returns
         -------
-        None, but adds "temporal_markets" and "temporalized_processes" to the
-        node_id_collection_dict based on the timeline.
+        None
+            Adds "temporal_markets" and "temporalized_processes" to the
+            node_id_collection_dict based on the timeline.
 
         """
         unique_producers = (
@@ -1221,7 +1214,8 @@ def add_static_activities_to_time_mapping_dict(self) -> None:
 
         Returns
         -------
-        None but adds the static activities to the `activity_time_mapping_dict`
+        None
+            adds the static activities to the `activity_time_mapping_dict`
         """
         for idx in self.base_lca.dicts.activity.keys():  # activity ids
             key = self.base_lca.remapping_dicts["activity"][idx]  # ('database', 'code')
@@ -1252,7 +1246,8 @@ def create_demand_timing_dict(self) -> dict:
 
         Returns
         -------
-        Dictionary mapping producer ids to reference timing for the specified demands.
+        dict
+            Dictionary mapping producer ids to reference timing for the specified demands.
         """
         demand_ids = [bd.get_activity(key).id for key in self.demand.keys()]
         demand_rows = self.timeline[
@@ -1278,8 +1273,9 @@ def create_labelled_technosphere_dataframe(self) -> pd.DataFrame:
 
         Returns
         -------
-        pd.DataFrame, technosphere matrix as a pandas.DataFrame with comprehensible labels instead
-        of ids.
+        pd.DataFrame
+            technosphere matrix as a pandas.DataFrame with comprehensible labels instead
+            of ids.
         """
 
         df = pd.DataFrame(self.lca.technosphere_matrix.toarray())
@@ -1305,8 +1301,9 @@ def create_labelled_biosphere_dataframe(self) -> pd.DataFrame:
 
         Returns
         -------
-        pd.DataFrame, biosphere matrix as a pandas.DataFrame with comprehensible labels instead of
-        ids.
+        pd.DataFrame
+            biosphere matrix as a pandas.DataFrame with comprehensible labels instead of
+            ids.
         """
 
         df = pd.DataFrame(self.lca.biosphere_matrix.toarray())
@@ -1336,8 +1333,9 @@ def create_labelled_dynamic_biosphere_dataframe(self) -> pd.DataFrame:
 
         Returns
         -------
-        pd.DataFrame, dynamic biosphere matrix as a pandas.DataFrame with comprehensible labels
-        instead of ids.
+        pd.DataFrame
+            dynamic biosphere matrix as a pandas.DataFrame with comprehensible labels
+            instead of ids.
         """
         df = pd.DataFrame(self.dynamic_biomatrix.toarray())
         df.rename(  # from matrix id to activity id
@@ -1365,8 +1363,9 @@ def create_labelled_dynamic_inventory_dataframe(self) -> pd.DataFrame:
 
         Returns
         -------
-        pd.DataFrame, dynamic inventory matrix as a pandas.DataFrame with comprehensible labels
-        instead of ids.
+        pd.DataFrame
+            dynamic inventory matrix as a pandas.DataFrame with comprehensible labels
+            instead of ids.
         """
 
         if not hasattr(self, "dynamic_inventory_df"):
@@ -1404,7 +1403,8 @@ def plot_dynamic_inventory(self, bio_flows, cumulative=False) -> None:
 
         Returns
         -------
-        none, but shows a plot
+        None
+            shows a plot
         """
         plt.figure(figsize=(14, 6))
 
@@ -1448,7 +1448,8 @@ def plot_dynamic_characterized_inventory(
 
         Returns
         -------
-        none, but shows a plot
+        None
+            shows a plot
         """
 
         if not hasattr(self, "characterized_inventory"):

diff --git a/bw_timex/utils.py b/bw_timex/utils.py
@@ -65,7 +65,7 @@ def extract_date_as_string(timestamp: datetime, temporal_grouping: str) -> str:
 
     Returns
     -------
-    date_as_string
+    date_as_string: str
         Date as a string in the format of the chosen temporal grouping.
     """
 
@@ -267,7 +267,8 @@ def plot_characterized_inventory_as_waterfall(
 
     Returns
     -------
-    None but plots the waterfall chart.
+    None
+        plots the waterfall chart.
 
     """
     if not hasattr(lca_obj, "characterized_inventory"):