diff --git a/docs/api/activity_generator.rst b/docs/api/activity_generator.rst index 8ce1cd5..a65f275 100644 --- a/docs/api/activity_generator.rst +++ b/docs/api/activity_generator.rst @@ -1,4 +1,4 @@ -Activity generator +Activity Generator ================== .. automodule:: sport_activities_features.activity_generator diff --git a/docs/api/data_extraction_from_csv.rst b/docs/api/data_extraction_from_csv.rst index afb0fa1..5191b40 100644 --- a/docs/api/data_extraction_from_csv.rst +++ b/docs/api/data_extraction_from_csv.rst @@ -1,4 +1,4 @@ -Data Extraction from csv files +Data Extraction from CSV Files ============================== .. automodule:: sport_activities_features.data_extraction_from_csv diff --git a/docs/api/plot_data.rst b/docs/api/plot_data.rst index 2215083..ccdd8d2 100644 --- a/docs/api/plot_data.rst +++ b/docs/api/plot_data.rst @@ -1,4 +1,4 @@ -Plot data +Plot Data ========= .. automodule:: sport_activities_features.plot_data diff --git a/docs/api/tcx_manipulation.rst b/docs/api/tcx_manipulation.rst index 4be28a0..ee2042e 100644 --- a/docs/api/tcx_manipulation.rst +++ b/docs/api/tcx_manipulation.rst @@ -1,4 +1,4 @@ -TCX manipulation +TCX Manipulation ================ .. automodule:: sport_activities_features.tcx_manipulation diff --git a/docs/api/topographic_features.rst b/docs/api/topographic_features.rst index 4c9a600..6bcb288 100644 --- a/docs/api/topographic_features.rst +++ b/docs/api/topographic_features.rst @@ -1,4 +1,4 @@ -Topographic features +Topographic Features ==================== .. automodule:: sport_activities_features.topographic_features diff --git a/docs/api/training_loads.rst b/docs/api/training_loads.rst index ee09243..f9aa4c1 100644 --- a/docs/api/training_loads.rst +++ b/docs/api/training_loads.rst @@ -1,4 +1,4 @@ -Training loads +Training Loads ============== .. automodule:: sport_activities_features.training_loads diff --git a/sport_activities_features/activity_generator.py b/sport_activities_features/activity_generator.py index 55ed46b..8210a42 100644 --- a/sport_activities_features/activity_generator.py +++ b/sport_activities_features/activity_generator.py @@ -10,8 +10,7 @@ class SportyDataGen: Brezočnik, L., Podgorelec, V., & Fister, I. (2018). - SportyDataGen: An Online Generator of Endurance - Sports Activity Collections. + SportyDataGen: An Online Generator of Endurance Sports Activity Collections. In Central European Conference on Information and Intelligent Systems (pp. 171-178). Faculty of Organization and Informatics Varazdin. @@ -21,6 +20,7 @@ class SportyDataGen: [WIP] This class is still under developement, therefore its methods may not work as expected. + """ def __init__(self, **kwargs) -> None: diff --git a/sport_activities_features/area_identification.py b/sport_activities_features/area_identification.py index 8bc1cf6..d5a126d 100644 --- a/sport_activities_features/area_identification.py +++ b/sport_activities_features/area_identification.py @@ -12,7 +12,7 @@ class AreaIdentification: positions (np.array): coordinates of positions as an array of latitudes and longitudes distances (np.array): - cummulative distances as an array of floats + cumulative distances as an array of floats timestamps (np.array): information about time as an array of datetimes heart_rates (np.array): @@ -42,7 +42,7 @@ def __init__( coordinates of positions as an array of latitudes and longitudes distances (np.array): - cummulative distances as an array of floats + cumulative distances as an array of floats timestamps (np.array): information about time as an array of datetimes heart_rates (np.array): @@ -58,8 +58,7 @@ def __init__( self.area_coordinates = area_coordinates def is_equal(self, value_1: float, value_2: float) -> bool: - """Method for checking whether the two float values are equal - with certain tolerance (because of round error).\n + """Method for checking whether the two float values are equal with certain tolerance (because of round error).\n Args: value_1 (float): first value @@ -99,7 +98,7 @@ def do_two_line_segments_intersect( True if the two lines have an intersection point, False otherwise. """ - # Initialization of vectors and values. + # Initialisation of vectors and values. v12 = np.array(p2 - p1) v34 = np.array(p4 - p3) v31 = np.array(p1 - p3) @@ -169,14 +168,16 @@ def identify_points_in_area(self) -> None: def extract_data_in_area(self) -> dict: """Method for extracting the data of the identified points in area.\n - Returns: area_data: { - 'distance': distance, - 'time': time, - 'average_speed': average_speed, - 'minimum_heart_rate': minimum_heart_rate, - 'maximum_heart_rate': maximum_heart_rate, - 'average_heart_rate': average_heart_rate - }. + Returns: + dict: + { + 'distance': distance, + 'time': time, + 'average_speed': average_speed, + 'minimum_heart_rate': minimum_heart_rate, + 'maximum_heart_rate': maximum_heart_rate, + 'average_heart_rate': average_heart_rate + }. """ distance = 0.0 time = 0.0 diff --git a/sport_activities_features/classes.py b/sport_activities_features/classes.py index 94073f6..858bcbf 100644 --- a/sport_activities_features/classes.py +++ b/sport_activities_features/classes.py @@ -8,8 +8,7 @@ class StoredSegments: average_slope(): - Note: - ---- + Note: [WIP] This class is still under developement, therefore its methods may not work as expected. diff --git a/sport_activities_features/data_analysis.py b/sport_activities_features/data_analysis.py index 531368e..5508ee2 100644 --- a/sport_activities_features/data_analysis.py +++ b/sport_activities_features/data_analysis.py @@ -96,6 +96,8 @@ def load_pipeline(file_name: str) -> Pipeline: Args: file_name (str): path to a binary pipeline file + Returns: + Pipeline: instance of Pipeline object from the NiaAML framework Note: See NiaAML's documentation for more details on the use of the Pipeline class. diff --git a/sport_activities_features/data_extraction_from_csv.py b/sport_activities_features/data_extraction_from_csv.py index 756d2b2..4bbb02a 100644 --- a/sport_activities_features/data_extraction_from_csv.py +++ b/sport_activities_features/data_extraction_from_csv.py @@ -19,12 +19,12 @@ def __init__(self, activities: list = None) -> None: """ self.activities = activities - def from_file(self, path: str) -> list: + def from_file(self, path: str) -> pd.DataFrame: """Method for extracting data from CSV file to dataframe.\n Args: path (str): absolute path to the CSV file Returns: - list: list of activities. + pandas.DataFrame: pandas DataFrame of activities. """ with open( path + '.csv' @@ -47,7 +47,7 @@ def from_all_files(self, path: str) -> list: path (str): absolute path to the folder with CSV files Returns: - list: list of activities. + list: list of pandas DataFrames. """ if not path.endswith('/'): path = path + '/' diff --git a/sport_activities_features/dead_end_identification.py b/sport_activities_features/dead_end_identification.py index 8348842..b542338 100644 --- a/sport_activities_features/dead_end_identification.py +++ b/sport_activities_features/dead_end_identification.py @@ -16,17 +16,15 @@ class DeadEndIdentification: positions (np.array): array of positions as pairs of latitudes and longitudes distances (np.array): - array of cummulative distances + array of cumulative distances tolerance_degrees (float): - tolerance of driving the same route in - the opposite direction given in degrees + tolerance of driving the same route in the opposite direction given in degrees tolerance_position (float): tolerance of positions given in meters minimum_distance (int): minimum distance of a dead end U_turn_allowed_distance (int): - maximum distance of a U-turn while - turning around and starting a dead end + maximum distance of a U-turn while turning around and starting a dead end Note: [WIP] This class is still under developement, therefore @@ -49,17 +47,15 @@ def __init__( positions (np.array): array of positions as pairs of latitudes and longitudes distances (np.array): - array of cummulative distances + array of cumulative distances tolerance_degrees (float): - tolerance of driving the same route in - the opposite direction given in degrees + tolerance of driving the same route in the opposite direction given in degrees tolerance_position (float): tolerance of positions given in meters minimum_distance (int): minimum distance of a dead end U_turn_allowed_distance (int): - maximum distance of a U-turn while - turning around and starting a dead end. + maximum distance of a U-turn while turning around and starting a dead end. """ # Reorganizing the exercise data in order to achieve better results. self.reorganize_exercise_data( @@ -84,7 +80,7 @@ def reorganize_exercise_data( positions (np.array): array of positions as pairs of latitudes and longitudes distances (np.array): - array of cummulative distances + array of cumulative distances interval_distance (int): desired distance between two neighboring points. """ @@ -143,8 +139,8 @@ def is_dead_end( tolerance_azimuth (float): difference tolerance of the two azimuths Returns: - bool: True if given azimuths are within the given tolerance, - False otherwise. + bool: + True, if given azimuths are within the given tolerance, False otherwise. """ if abs(180 - abs(azimuth_1 - azimuth_2)) < tolerance_azimuth: return True @@ -159,11 +155,12 @@ def long_enough_to_be_a_dead_end( long enough to be a dead end.\n Args: start_distance (float): - cummulative distance at the start of the dead end + cumulative distance at the start of the dead end finish_distance (float): - cummulative distance at the end of the dead end + cumulative distance at the end of the dead end Returns: - bool: True if dead end is long enough, False otherwise. + bool: + True, if dead end is long enough, False otherwise. """ if finish_distance - start_distance < self.minimum_distance: return False @@ -184,8 +181,8 @@ def really_is_dead_end( tolerance_coordinates (float): the tolerance between the two positions in meters Returns: - bool: True if a track segment is a part of dead end, - False otherwise. + bool: + True, if a track segment is a part of dead end, False otherwise. """ print(geopy.distance.distance(position1, position2).m) if (geopy.distance.distance(position1, position2).m @@ -299,9 +296,9 @@ def draw_map(self) -> None: def show_map(self) -> plt: """Method for plotting the exercise with dead ends. - Returns - ------- - plt. + Returns: + plt (matplotlib.pyplot): + plot of the exercise with dead ends. """ if np.shape(self.positions)[0] == 0: msg = 'Dataset is empty or invalid.' diff --git a/sport_activities_features/file_manipulation.py b/sport_activities_features/file_manipulation.py index a1e52fa..61ef846 100644 --- a/sport_activities_features/file_manipulation.py +++ b/sport_activities_features/file_manipulation.py @@ -11,11 +11,10 @@ class FileManipulation: def count_missing_values(self, list): """Counts the number of elements with value Nona. - Args: - ---- + Args: list (list/ndarray): list to check Returns: - (int): number of elements with value None in list. + int: number of elements with value None in list. """ count = 0 for i in list: @@ -24,13 +23,14 @@ def count_missing_values(self, list): return count def __missing_from_to(self, lst, start): - """Finds to which index the values are missing + """Finds to which index the values are missing. Args: - lst (list/ndarray): list on which to search - for consecutive missing values - start(int): index from where to search forward + lst (list/ndarray): + list on which to search for consecutive missing values + start(int): + index from where to search forward Returns: - (int): ending index of consecutive missing values. + int: ending index of consecutive missing values. """ index = start while index < len(lst): @@ -44,8 +44,7 @@ def __set_value_type(self, baseline, value): """Private method that changes the value into baseline type (chooses between int and float). - Args: - ---- + Args: baseline: who to compare to value: who to compare Returns: @@ -64,16 +63,16 @@ def linear_fill_missing_values(self, activity, key, max_seconds=15): """Function that lineary fills missing values, if the successive missing values are up to (max_seconds) apart. - Args: - ---- - activity: TCXReader read file - key (str): dictionary key (e.g. 'heartrates', 'distances', ...) - max_seconds (int): maximum time between two valid values, - to still fill the missing values. + Args: + activity: + TCXReader read file + key (str): + dictionary key (e.g. 'heartrates', 'distances', ...) + max_seconds (int): + maximum time between two valid values, to still fill the missing values. - Returns: - ------- - / Transforms the sent array / list. + Returns: + Transformed sent array / list. """ index = 0 count = len(activity[key]) diff --git a/sport_activities_features/gpx_manipulation.py b/sport_activities_features/gpx_manipulation.py index d8bf8a7..5a35cda 100644 --- a/sport_activities_features/gpx_manipulation.py +++ b/sport_activities_features/gpx_manipulation.py @@ -86,18 +86,18 @@ def from_GPX( watts: int = None, ) -> None: """Helper method for initialising GPXTrackPoint - from the gpxpy.gpx.GpxTrackPoint.\n + from the gpxpy.gpx.GPXTrackPoint.\n Args: gpx (gpxpy.gpx.GPXTrackPoint): - gpxpy.gpx.GPXTrackPoint not to be confused - with class of the same name used in - gpx_manipulation + gpxpy.gpx.GPXTrackPoint to extract data from hr_value (int): heart beats per minute at given recording cadence (int): cadence watts (int): watts power rating. + Note: + Parameter gpx and its type gpxpy.gpx.GPXTrackPoint should not be confused with the class of the same name used in gpx_manipulation """ self.elevation = gpx.elevation self.latitude = gpx.latitude @@ -109,7 +109,6 @@ def from_GPX( class GPXFile(FileManipulation): - """Class for reading GPX files.""" def __init__(self) -> None: @@ -165,21 +164,21 @@ def read_one_file(self, filename, numpy_array=False): filename (str): name of the TCX file to be read numpy_array (bool): - if set to true dictionary lists are - transformed into numpy.arrays - Returns: activity: { - 'activity_type': activity_type, - 'positions': positions, - 'altitudes': altitudes, - 'distances': distances, - 'total_distance': total_distance, - 'timestamps': timestamps, - 'heartrates': heartrates, - 'speeds': speeds - }. - - Note: - ---- + if set to true dictionary lists are transformed into numpy arrays + Returns: + activity (dict): + { + 'activity_type': activity_type, + 'positions': positions, + 'altitudes': altitudes, + 'distances': distances, + 'total_distance': total_distance, + 'timestamps': timestamps, + 'heartrates': heartrates, + 'speeds': speeds + } + + Note: In the case of missing value in raw data, we assign None. """ NAMESPACE = '{http://www.garmin.com/xmlschemas/TrackPointExtension/v1}' @@ -288,20 +287,25 @@ def read_one_file(self, filename, numpy_array=False): def extract_integral_metrics(self, filename) -> dict: """Method for parsing one GPX file and extracting integral metrics.\n - Returns: int_metrics: { - "activity_type": activity_type, - "distance": distance, - "duration": duration, - "calories": calories, - "hr_avg": hr_avg, - "hr_max": hr_max, - "hr_min": hr_min, - "altitude_avg": altitude_avg, - "altitude_max": altitude_max, - "altitude_min": altitude_min, - "ascent": ascent, - "descent": descent, - }. + Args: + filename (str): + name of the GPX file to be read + Returns: + int_metrics (dict): + { + "activity_type": activity_type, + "distance": distance, + "duration": duration, + "calories": calories, + "hr_avg": hr_avg, + "hr_max": hr_max, + "hr_min": hr_min, + "altitude_avg": altitude_avg, + "altitude_max": altitude_max, + "altitude_min": altitude_min, + "ascent": ascent, + "descent": descent, + }. """ gpx = self.read_one_file(filename) diff --git a/sport_activities_features/hill_identification.py b/sport_activities_features/hill_identification.py index acaa2a1..090c3ec 100644 --- a/sport_activities_features/hill_identification.py +++ b/sport_activities_features/hill_identification.py @@ -8,7 +8,10 @@ class GradeUnit(Enum): """ Enum for selecting the type of data we want returned in - hill slope calculation (degrees / radians or gradient (%)) + hill slope calculations.\n + - degrees + - radians + - percents [%] (gradient) """ DEGREES = 1 @@ -25,7 +28,7 @@ class HillIdentification(object): ascent_threshold (float): parameter that defines the hill (hill >= ascent_threshold) distances (list): - optional, allows calculation of hill grades (steepnes) + optional, allows calculation of hill grades (steepness) """ def __init__( diff --git a/sport_activities_features/interval_identification.py b/sport_activities_features/interval_identification.py index 2b17726..40fb7b9 100644 --- a/sport_activities_features/interval_identification.py +++ b/sport_activities_features/interval_identification.py @@ -9,7 +9,7 @@ class IntervalIdentificationByPower(object): Class for identifying intervals based on power.\n Args: distances (list): - list of cummulative distances + list of cumulative distances timestamps (list): list of timestamps altitudes (list): @@ -32,7 +32,7 @@ def __init__( Initialisation method for IntervalIdentificationByPower class.\n Args: distances (list): - list of cummulative distances + list of cumulative distances timestamps (list): list of timestamps altitudes (list): @@ -187,7 +187,8 @@ def calculate_interval_statistics(self) -> dict: """ Method for calculating interval statistics.\n Returns: - data = { + dict: + { 'number_of_intervals': number_of_intervals, 'min_duration': min_duration_interval, 'max_duration': max_duration_interval, @@ -245,7 +246,7 @@ class IntervalIdentificationByHeartRate(object): Class for identifying intervals based on heart rate.\n Args: distances (list): - list of cummulative distances + list of cumulative distances timestamps (list): list of timestamps altitudes (list): @@ -412,7 +413,8 @@ def calculate_interval_statistics(self) -> dict: """ Method for calculating interval statistics.\n Returns: - data = { + dict: + { 'number_of_intervals': number_of_intervals, 'min_duration_interval': min_duration_interval, 'max_duration_interval': max_duration_interval, diff --git a/sport_activities_features/missing_elevation_identification.py b/sport_activities_features/missing_elevation_identification.py index f81f5b4..2720dff 100644 --- a/sport_activities_features/missing_elevation_identification.py +++ b/sport_activities_features/missing_elevation_identification.py @@ -4,6 +4,11 @@ from enum import Enum class ElevationApiType(Enum): + """Enum for selecting the type of Elevation API to be used.\n + - OPEN_ELEVATION_API + - OPEN_TOPO_DATA_API + + """ OPEN_ELEVATION_API = 1 OPEN_TOPO_DATA_API = 2 @@ -12,10 +17,9 @@ class ElevationIdentification(): """Class for retrieving elevation data using Elevation Api, Open-Elevation API and OpenTopoData API supported.\n Args: open_elevation_api (str): - address of the Api, - default https://api.open-elevation.com/api/v1/lookup + address of the Api, default https://api.open-elevation.com/api/v1/lookup positions (list[(lat1, lon1), (lat2, lon2) ...]): - list of tuples of latitudes and longitudes. + list of coordinates in the form of tuples of latitudes and longitudes. """ def __init__( @@ -30,8 +34,7 @@ def __init__( """Initialisation method for ElevationIdentification class.\n Args: open_elevation_api (str): - address of the Elevation Api, - default https://api.open-elevation.com/api/v1/lookup + address of the Elevation Api, default https://api.open-elevation.com/api/v1/lookup positions (list[(lat1, lon1), (lat2, lon2) ...]): list of tuples of latitudes and longitudes. open_topo_data_api (str): @@ -51,7 +54,8 @@ def __map_payload_open_elevation_api(self, position: tuple) -> dict: position (tuple): tuple of latitude and longitude Returns: - JSON like object { + dict: + { 'latitude': float(position[0]), 'longitude': float(position[1]), }. @@ -77,15 +81,13 @@ def __divide_chunks(self, elements: list, n: int) -> list: yield elements[i:i + n] def fetch_elevation_data(self, payload_formatting: bool = True) -> list: - """Method for making requests to the Elevation API - to retrieve elevation data.\n - Args: - payload_formatting (bool): - True -> break into chunks, - False -> don't break self.positions into chunks - Returns: - list[int]: list of elevations for the given positions. - """ + """Method for making requests to the Elevation API to retrieve elevation data.\n + Args: + payload_formatting (bool): + if True, then break into chunks, otherwise don't break self.positions into chunks. + Returns: + list: list of ints representing elevations for the given positions. + """ if self.elevation_api_type == ElevationApiType.OPEN_ELEVATION_API: return self.fetch_open_elevation_data(payload_formatting) elif self.elevation_api_type == ElevationApiType.OPEN_TOPO_DATA_API: @@ -93,14 +95,12 @@ def fetch_elevation_data(self, payload_formatting: bool = True) -> list: else: raise ValueError("Invalid Elevation API Type") def fetch_open_topo_data(self, payload_formatting: bool = True) -> list: - """Method for making requests to the Open Topo Data API - to retrieve elevation data.\n + """Method for making requests to the Open Topo Data API to retrieve elevation data.\n Args: payload_formatting (bool): - True -> break into chunks, - False -> don't break self.positions into chunks + if True, then break into chunks, otherwise don't break self.positions into chunks. Returns: - list[int]: list of elevations for the given positions. + list: list of ints representing elevations for the given positions. """ chunks = self.__divide_chunks(self.positions, 100) # into 100 because of the default limit of the API elevations = [] @@ -142,14 +142,12 @@ def fetch_open_topo_data(self, payload_formatting: bool = True) -> list: def fetch_open_elevation_data(self, payload_formatting: bool = True) -> list: - """Method for making requests to the Open Elevation API - to retrieve elevation data.\n + """Method for making requests to the Open Elevation API to retrieve elevation data.\n Args: payload_formatting (bool): - True -> break into chunks, - False -> don't break self.positions into chunks + if True, then break into chunks, otherwise don't break self.positions into chunks. Returns: - list[int]: list of elevations for the given positions. + list: list of ints representing elevations for the given positions. """ open_elevation_nodes = [] if payload_formatting: diff --git a/sport_activities_features/overpy_node_manipulation.py b/sport_activities_features/overpy_node_manipulation.py index 8479d58..4de2f9c 100644 --- a/sport_activities_features/overpy_node_manipulation.py +++ b/sport_activities_features/overpy_node_manipulation.py @@ -25,18 +25,19 @@ def __init__( Args: open_elevation_api (str): address of Open Elevation API, if a lot of altitudes - are needed, self hosting is prefferable. + are needed, self hosting is preferrable. """ self.open_elevation_api = open_elevation_api def __map_payload(self, node: tuple) -> dict: - """Method that converts touple into JSON like object - for equerying the Open Elevation API.\n + """Method that converts tuple into JSON like object + for querying the Open Elevation API.\n Args: position (tuple): tuple of latitude and longitude Returns: - JSON like object { + dict: + { 'latitude': float(position[0]), 'longitude': float(position[1]), }. @@ -61,7 +62,8 @@ def read_nodes( distance + distance between the nodes, else tells actual distance between two points. - Returns: dictionary of nodes. + Returns: + dictionary of nodes: { 'activity_type': str, 'positions': [...], diff --git a/sport_activities_features/plot_data.py b/sport_activities_features/plot_data.py index 2651889..9f49c1f 100644 --- a/sport_activities_features/plot_data.py +++ b/sport_activities_features/plot_data.py @@ -93,7 +93,8 @@ def plot_hills_on_map( identified_hills (list): list of identified hills Returns: - plt. + plt (matplotlib.pyplot): + plot of all hills idenitified in data on topographic map. """ y = [] x = [] @@ -162,7 +163,8 @@ def plot_intervals_in_map( identified_intervals (list): list of identified intervals Returns: - plt. + plt (matplotlib.pyplot): + plot of all intervals identified in data on topographic map. """ x_points = [] y_points = [] @@ -222,7 +224,8 @@ def plot_basic_map(self, altitude: list, distance: list) -> plt: distance (list): list of distances Returns: - plt. + plt (matplotlib.pyplot): + plot of the whole topographic map. """ ax = plt.axes() y = [] diff --git a/sport_activities_features/tcx_manipulation.py b/sport_activities_features/tcx_manipulation.py index db78769..7764368 100644 --- a/sport_activities_features/tcx_manipulation.py +++ b/sport_activities_features/tcx_manipulation.py @@ -22,7 +22,7 @@ def read_directory(self, directory_name: str) -> list: directory_name (str): name of the directory in which to identify TCX files Returns: - str: array of paths to the identified files. + list: array of paths to the identified files. """ files = os.listdir(directory_name) all_files1 = [i for i in files if i.endswith('.tcx')] @@ -37,10 +37,10 @@ def read_one_file(self, filename: str, numpy_array=False) -> dict: filename (str): name of the TCX file to be read numpy_array (bool): - if set to true dictionary lists are - transformed into numpy.arrays + if set to True dictionary lists are transformed into numpy arrays Returns: - activity = { + dict: + { 'activity_type': activity_type, 'positions': positions, 'altitudes': altitudes, @@ -52,7 +52,6 @@ def read_one_file(self, filename: str, numpy_array=False) -> dict: }. Note: - ---- In the case of missing value in raw data, we assign None. """ tcx = TCXReader().read(filename) @@ -127,7 +126,8 @@ def extract_integral_metrics(self, filename: str) -> dict: filename (str): name of the TCX file to be read Returns: - int_metrics = { + dict: + { 'activity_type': activity_type, 'distance': distance, 'duration': duration, @@ -273,11 +273,18 @@ def extract_integral_metrics(self, filename: str) -> dict: return int_metrics def write_gpx(self, gps_object, output_file_name=None): - """Write GPX object to file. - if output_file_name is not specified, - the output file name will be the same - as the input file name, - but with .gpx extension. + """ + Write GPX object to file.\n + Args: + gps_object: + TCX2GPX object from tcx2gpx + output_file_name (str): + name of the output file + Note: + If output_file_name is not specified, + the output file name will be the same + as the input file name, + but with .gpx extension. """ if output_file_name is None: output_file_name = str(gps_object.tcx_path.resolve()).replace( @@ -288,16 +295,38 @@ def write_gpx(self, gps_object, output_file_name=None): output.write(gps_object.gpx.to_xml()) def create_gps_object(self, path_to_the_file): - """Convert TCX file to GPX file.""" + """ + Convert TCX file to GPX file.\n + Args: + path_to_the_file (str): + path to the TCX file + Returns: + gps_object (tcx2gpx.TCX2GPX): + TCX2GPX object from tcx2gpx + """ gps_object = tcx2gpx.TCX2GPX(tcx_path=path_to_the_file) gps_object.read_tcx() gps_object.extract_track_points() gps_object.create_gpx() return gps_object - def convert_tcx_to_gpx( - self, local_path_to_original_file: str, output_file_name=None, - ): + def convert_tcx_to_gpx(self, local_path_to_original_file: str, output_file_name=None): + """ + Convert TCX file to GPX file.\n + Args: + local_path_to_original_file (str): + path to the TCX file + output_file_name (str): + name of the output file + Returns: + gps_object (tcx2gpx.TCX2GPX): + TCX2GPX object from tcx2gpx + Note: + If output_file_name is not specified, + the output file name will be the same + as the input file name, + but with .gpx extension. + """ try: """ This is a try-except block. diff --git a/sport_activities_features/topographic_features.py b/sport_activities_features/topographic_features.py index b90f44f..f19d654 100644 --- a/sport_activities_features/topographic_features.py +++ b/sport_activities_features/topographic_features.py @@ -6,14 +6,14 @@ class TopographicFeatures: """Class for feature extraction from topographic maps.\n Args: identified_hills (list): - identified hills are now passed to this class. + list of identified hills. """ def __init__(self, identified_hills: list) -> None: """Initialisation method of TopographicFeatures class.\n Args: identified_hills (list): - identified hills are now passed to this class. + list of identified hills. """ self.identified_hills = identified_hills self.features = [] diff --git a/sport_activities_features/training_loads.py b/sport_activities_features/training_loads.py index 851df03..2f593c4 100644 --- a/sport_activities_features/training_loads.py +++ b/sport_activities_features/training_loads.py @@ -7,7 +7,11 @@ class Gender(Enum): - """Gender Enum.""" + """ + Gender Enum for the BanisterTRIMPv2 class.\n + - MALE + - FEMALE + """ male = 1 female = 2 @@ -27,7 +31,7 @@ class BanisterTRIMPv1: """ def __init__(self, duration: float, average_heart_rate: float) -> None: - """Initialization method for BanisterTRIMP class.\n + """Initialisation method for BanisterTRIMP class.\n Args: duration (float): total duration in seconds @@ -47,11 +51,11 @@ def calculate_TRIMP(self) -> float: class BanisterTRIMPv2: - """Class for calculation of Banister's TRIMP.\n. - + """Class for calculation of Banister's TRIMP.\n Reference paper: Banister, Eric W. "Modeling elite athletic performance." Physiological testing of elite athletes 347 (1991): 403-422.\n + Args: duration (float): total duration in seconds @@ -90,20 +94,18 @@ def calculate_delta_hr_ratio(self: 'BanisterTRIMPv2') -> float: The ratio ranges from a low to a high value (i.e., ~ 0.2 — 1.0) for a low or a high raw heart rate, respectively. - Returns - ------- + Returns: float: delta heart rate. """ return (self.average_heart_rate - self.rest_heart_rate) / \ (self.max_heart_rate - self.rest_heart_rate) - def calculate_weighting_factor(self: 'BanisterTRIMPv2', - delta_hr_ratio: float, - ) -> float: - """Calculate the weighting factor. - - Returns - ------- + def calculate_weighting_factor(self: 'BanisterTRIMPv2', delta_hr_ratio: float) -> float: + """Calculate the weighting factor.\n + Args: + delta_hr_ratio (float): + delta heart rate ratio. + Returns: float: weighting factor (Y). """ # b defaults to b_male since only males contributed to the dataset @@ -114,8 +116,7 @@ def calculate_weighting_factor(self: 'BanisterTRIMPv2', def calculate_TRIMP(self: 'BanisterTRIMPv2') -> float: """Calculate TRIMP. - Returns - ------- + Returns: float: Banister TRIMP value. """ duration_minutes = self.duration / 60 @@ -131,9 +132,9 @@ class EdwardsTRIMP: Reference paper: https://www.frontiersin.org/articles/10.3389/fphys.2020.00480/full\n Args: - heart_rates (list[int]): - list of heart rates in beats per minute - timestamps (list[timestamp]): + heart_rates (list): + list of ints representing heart rates in beats per minute + timestamps (list): list of timestamps max_heart_rate (int): maximum heart rate of an athlete. @@ -145,11 +146,11 @@ def __init__( timestamps: list, max_heart_rate: int = 200, ) -> None: - """Initialization method for EdwardsTRIMP class.\n + """Initialisation method for EdwardsTRIMP class.\n Args: - heart_rates (list[int]): - list of heart rates in beats per minute - timestamps (list[timestamp]): + heart_rates (list): + list of ints representing heart rates in beats per minute + timestamps (list): list of timestamps max_heart_rate (int): maximum heart rate of an athlete. @@ -198,9 +199,9 @@ class LuciaTRIMP: Reference: https://www.trainingimpulse.com/lucias-trimp-0\n Args: - heart_rates (list[int]): - list of heart rates in beats per minute - timestamps (list[timestamp]): + heart_rates (list): + list of ints representing heart rates in beats per minute + timestamps (list): list of timestamps VT1 (int): ventilatory threshold to divide the low and the moderate zone @@ -215,11 +216,11 @@ def __init__( VT1: int = 160, VT2: int = 180, ) -> None: - """Initialization method for LuciaTRIMP class.\n + """Initialisation method for LuciaTRIMP class.\n Args: - heart_rates (list[int]): - list of heart rates in beats per minute - timestamps (list[timestamp]): + heart_rates (list): + list of ints representing heart rates in beats per minute + timestamps (list): list of timestamps VT1 (int): ventilatory threshold to divide the low and the moderate zone diff --git a/sport_activities_features/training_metrics.py b/sport_activities_features/training_metrics.py index c49e3e9..872fd21 100644 --- a/sport_activities_features/training_metrics.py +++ b/sport_activities_features/training_metrics.py @@ -146,9 +146,9 @@ def calculate_intensity_factor(self, normalized_power: float, ftp: float) -> flo """Calculate the intensity factor of a training session.\n Args: normalized_power (float): - The normalized power of the workout. [W] + The normalized power of the workout in watts. [W] ftp (float): - The functional threshold power of the athlete. [W] + The functional threshold power of the athlete in watts. [W] Returns: float: The intensity factor, which is the ratio of normalized power to FTP. Function: diff --git a/sport_activities_features/weather_identification.py b/sport_activities_features/weather_identification.py index 6f2abfb..e23c551 100644 --- a/sport_activities_features/weather_identification.py +++ b/sport_activities_features/weather_identification.py @@ -246,8 +246,8 @@ def get_average_weather_data( weather (list[Weather]): list of weather objects retrieved from VisualCrossing API Returns: - list[AverageWeather]: list which is an AverageWeather object - for each of the given timestamps. + list[AverageWeather]: + list which is an AverageWeather object for each of the given timestamps. """ weather_list = weather extended_weather_list = []