Merge pull request #175 from lahovniktadej/main

Synchronised documentation

docs/index.rst

@@ -7,40 +7,55 @@ sport-activities-features is a minimalistic toolbox for extracting features from
 
 * **Free software:** MIT license
 * **Github repository:** https://github.com/firefly-cpp/sport-activities-features
-* **Python versions:** 3.6.x, 3.7.x, 3.8.x, 3.9.x, 3.10.x, 3.11.x, 3.12.x
+* **Python versions:** 3.8.x, 3.9.x, 3.10.x, 3.11.x, 3.12.x
 
-General outline of the framework
----------------------------------
-Monitoring sports activities produce many geographic, topologic, and personalized data, with a vast majority of details hidden :cite:p:`rajvsp2020systematic`. Thus, a rigorous ex-post data analysis and statistic evaluation are required to extract them. Namely, most mainstream solutions for analyzing sports activities files rely on integral metrics, such as total duration, total distance, and average hearth rate, which may suffer from the "overall (integral) metrics problem". Among others, such problems are expressed in capturing sports activities in general only (omitting crucial components), calculating potentially fallacious and misleading metrics, not recognizing different stages/phases of the sports activity (warm-up, endurance, intervals), and others :cite:p:`fister2019computational`.
+Unleashing the Power of Sports Activity Analysis: A Framework Beyond Ordinary Metrics 🚀
+----------------------------------------------------------------------------------------
+Prepare to dive into the thrilling world of sports activity analysis, where hidden geographic, topological, and personalized data await their grand unveiling. In this captivating journey, we embark on a quest to extract the deepest insights from the wealth of information generated by monitoring sports activities. Brace yourself for a framework that transcends the limitations of conventional analysis techniques. 💪🔍
 
-The sport-activities-framework, on the other side, offers a detailed insight into the sports activity files. The framework supports both identification and extraction methods, such as identifying the number of hills, extracting the average altitudes of identified hills, measuring the total distance of identified hills, deriving climbing ratios (total distance of identified hills vs. total distance), average/total ascents of hills and so much more. The framework also integrates many other extensions, among others, historical weather parsing, statistical evaluations, and ex-post visualizations. Previous work on these topical questions was addressed in :cite:p:`fister2013data` `relevant scientific papers on data mining <http://iztok-jr-fister.eu/static/publications/42.pdf>`_, also in combination with the `generating/predicting automated sport training sessions <http://iztok-jr-fister.eu/static/publications/189.pdf)>`_.
+Traditional approaches often rely on integral metrics like total duration, total distance, and average heart rate, but they fall victim to the dreaded "overall metrics problem." These metrics fail to capture the essence of sports activities, omitting crucial components and leading to potentially flawed and misleading conclusions. They lack the ability to recognize distinct stages and phases of the activity, such as the invigorating warm-up, the endurance-testing main event, and the heart-pounding intervals. ⏱️🚴‍♀️📈
 
-Detailed insights
------------------------
-The sport-activities-features framework is compatible with TCX & GPX activity files and `Overpass API <https://wiki.openstreetmap.org/wiki/Overpass_API>`_ nodes. Current version withholds (but is not limited to) the following functions:
-
-- extracting integral metrics, such as total distance, total duration, calories (`see example <https://github.com/firefly-cpp/sport-activities-features/blob/main/examples/integral_metrics_extraction.py>`_),
-- extracting topographic features, such as number of hills, the average altitude of identified hills, a total distance of identified hills, climbing ratio, the average ascent of hills, total ascent, total descent (`see example <https://github.com/firefly-cpp/sport-activities-features/blob/main/examples/hill_data_extraction.py>`_),
-- plotting identified hills (`see example <https://github.com/firefly-cpp/sport-activities-features/blob/main/examples/draw_map_with_identified_hills.py>`_),
-- extracting the intervals, such as number of intervals, maximum/minimum/average duration of intervals, maximum/minimum/average distance of intervals, maximum/minimum/average heart rate during intervals,
-- plotting the identified intervals (`see example <.https://github.com/firefly-cpp/sport-activities-features/blob/main/examples/draw_map_with_identified_intervals.py>`_),
-- calculating the training loads, such as Bannister TRIMP, Lucia TRIMP (`see example <https://github.com/firefly-cpp/sport-activities-features/blob/main/examples/calculate_training_load.py>`_),
-- parsing the historical weather data from an external service,
-- extracting the integral metrics of the activity inside the area given with coordinates (distance, heartrate, speed) (`see example <https://github.com/firefly-cpp/sport-activities-features/blob/main/examples/extract_data_inside_area.py>`_),
-- extracting the activities from CSV file(s) and randomly selecting the specific number of activities (`see example <../examples/extract_random_activities_from_csv.py>`_),
-- extracting the dead ends (`see example <https://github.com/firefly-cpp/sport-activities-features/blob/main/examples/dead_end_extraction.py>`_),
-- converting TCX to GPX (`see example <https://github.com/firefly-cpp/sport-activities-features/blob/main/examples/convert_tcx_to_gpx.py>`_),
-- and much more.
-
-The framework comes with two (testing) benchmark datasets, which are freely available to download from: `DATASET1 <http://iztok-jr-fister.eu/static/publications/Sport5.zip>`_, `DATASET2 <http://iztok-jr-fister.eu/static/css/datasets/Sport.zip>`_.
-
-Historical Weather Data
+Fortunately, our sport-activities-framework rises above these limitations, revealing a comprehensive panorama of your sports activity files. This framework combines the power of identification and extraction methods to unlock a treasure trove of valuable data. Picture this 📷 : effortlessly identifying the number of hills, extracting average altitudes of these remarkable formations, measuring the total distance conquered on those inclines, and even deriving climbing ratios for a true measure of accomplishment (total distance of hills vs. total distance). But that's just the tip of the iceberg! The framework seamlessly integrates a multitude of extensions, including historical weather parsing, statistical evaluations, and ex-post visualizations that bring your data to life. 🗻📊🌦️
+
+For those seeking to venture further, we invite you to explore the realms of scientific papers on data mining that delve into these captivating topics. Discover how our framework complements the world of generating and predicting automated sport training sessions, creating a harmonious synergy between theory and practice. 📚🔬💡
+
+Detailed insights 🔍
+--------------------
+Prepare to be astounded by the capabilities of the sport-activities-features framework. It effortlessly handles TCX & GPX activity files and harnesses the power of the `Overpass API <https://wiki.openstreetmap.org/wiki/Overpass_API>`_ nodes. Presenting the range of functions at your disposal:
+
+- **Unleash the integral metrics**: From total distance to total duration and even calorie count, witness the extraction of these vital statistics with a single glance. 📏⏰🔥 (`Integral Metrics Extraction example <examples/integral_metrics_extraction.py>`_)
+
+- **Conquer the peaks**: Ascend to new heights by extracting topographic features like the number of hills, their average altitudes, the total distance covered on these majestic slopes, and the thrilling climbing ratio. Prepare for a breathtaking adventure! ⛰️📈🧗‍♂️ (`Hill Data Extraction example <examples/hill_data_extraction.py>`_)
+
+- **Embark on a visual journey**: Immerse yourself in the beauty of your accomplishments as you plot the identified hills on a mesmerizing map. Witness the landscape come alive before your eyes. 🗺️🏞️🖌️ (`Draw Map with Identified Hills example <examples/draw_map_with_identified_hills.py>`_)
+
+- **Embrace the rhythm of intervals**: Explore the intervals within your sports activities, uncovering their numbers, durations, distances, and heart rates. Unveil the heartbeat of your performance! 🏃‍♀️📊💓 (`Draw Map with Identified Intervals example <examples/draw_map_with_identified_intervals.py>`_)
+
+- **Calculate the training loads**: Dive deep into the intricate world of training loads and discover the Banister TRIMP and Lucia TRIMP methods. Gain invaluable insights into optimizing your training regimen. 📈⚖️🏋️‍♂️ (`Calculate Training Load example <examples/calculate_training_load.py>`_)
+
+- **Weather the storm**: Unlock the power of historical weather data from external services, adding a fascinating layer of context to your sports activities. ☀️🌧️⛈️
+
+- **Unveil the secrets within coordinates**: Explore the integral metrics of your activities within specific geographical areas, uncovering valuable data on distance, heart rate, and speed. Peer into the depths of your performance! 🌍📍📉 (`Extract Data Inside Area example <examples/extract_data_inside_area.py>`_)
+
+- **Embrace randomness**: Extract activities from CSV files and indulge in the excitement of randomly selecting a specific number of activities. Embrace the element of surprise! 🎲📂🎉 (`Extract Random Activities from CSV example <examples/extract_random_activities_from_csv.py>`_)
+
+- **Conquer the dead ends**: Unravel the mysteries of your sports activities by identifying the dead ends. Prepare to navigate the uncharted territories of your performance! 🚧🗺️🔍 (`Dead End Extraction example <examples/dead_end_extraction.py>`_)
+
+- **Unlock the format**: Seamlessly convert TCX files to GPX, opening doors to even more possibilities. Adapt and conquer! ⚙️🔄✨ (`Convert TCX to GPX example <examples/convert_tcx_to_gpx.py>`_)
+
+And that's just the beginning! The sport-activities-framework holds countless other features, awaiting your exploration. Brace yourself for an exhilarating journey of discovery, where the ordinary becomes extraordinary, and your sports activities come alive like never before. 🌟🔥🏃‍♂️
+
+The framework comes with two (testing) `benchmark datasets <https://github.com/firefly-cpp/sports-activity-dataset-collections>`_, which are freely available to download from: `DATASET1 <http://iztok-jr-fister.eu/static/publications/Sport5.zip>`_, `DATASET2 <http://iztok-jr-fister.eu/static/css/datasets/Sport.zip>`_.
+
+Historical weather data
 -----------------------
 
-Weather data is collected from the `Visual Crossing Weather API <https://www.visualcrossing.com/>`_.
-Please note that this is an external unaffiliated service, and users must register to use the API.
-The service has a free tier (1000 Weather reports/day) but otherwise operates on a pay-as-you-go model.
-For pricing and terms of use, please read the `official documentation <https://www.visualcrossing.com/weather-data-editions>`_ of the API provider.
+Weather data parsed is collected from the `Visual Crossing Weather API <https://www.visualcrossing.com/>`_. Please note that this is an external unaffiliated service, and users must register to use the API. The service has a free tier (1000 Weather reports/day) but is otherwise operating on a pay-as-you-go model. For pricing and terms of use, please read the `official documentation <https://www.visualcrossing.com/weather-data-editions>`_ of the API provider.
+
+Overpass API & Open Elevation API integration
+---------------------------------------------
+
+Without performing activities, we can use the `OpenStreetMap <https://www.openstreetmap.org/>`_ for the identification of hills, total ascent, and descent. This is done using the `Overpass API <https://wiki.openstreetmap.org/wiki/Overpass_API>`_, which is a read-only API that allows querying of OSM map data. In addition to that altitude, data is retrieved by using the `Open-Elevation API <https://open-elevation.com/>`_, which is an open-source and free alternative to the Google Elevation API. Both of the solutions can be used by using free publicly accessible APIs (`Overpass <https://wiki.openstreetmap.org/wiki/Overpass_API>`_, `Open-Elevation Public API <https://open-elevation.com/#public-api>`_) or can be self-hosted on a server or as a Docker container (`Overpass Self-hosting <https://wiki.openstreetmap.org/wiki/Overpass_API/Installation>`_, `Open-Elevation Self-hosting <https://github.com/Jorl17/open-elevation/blob/master/docs/host-your-own.md>`_).
 
 Documentation
 =============

docs/installation.rst

@@ -32,29 +32,27 @@ List of sport-activities-features dependencies:
 +----------------+--------------+------------+
 | matplotlib     | ^3.3.3       | All        |
 +----------------+--------------+------------+
-| tcxreader      | ^0.3.10      | All        |
+| tcxreader      | ^0.4.4       | All        |
 +----------------+--------------+------------+
-| requests       | ^2.25.1      | All        |
+| niaaml         | ^1.2.0       | All        |
 +----------------+--------------+------------+
-| niaaml         | ^1.1.6       | All        |
-+----------------+--------------+------------+
-| overpy         | ^1.23.1      | All        |
+| overpy         | ^0.6         | All        |
 +----------------+--------------+------------+
 | gpxpy          | ^1.4.2       |  All       |
 +----------------+--------------+------------+
 | geotiler       | ^0.14.5      |  All       |
 +----------------+--------------+------------+
-| numpy          | ^1.23.1      |  All       |
-+----------------+--------------+------------+
-| dotmap         | ^1.3.25      |  All       |
+| numpy          | *            |  All       |
 +----------------+--------------+------------+
 
 List of development dependencies:
 
-+--------------------+-----------+------------+
-| Package            | Version   | Platform   |
-+====================+===========+============+
-| Sphinx             | ^3.5.1    | Any        |
-+--------------------+-----------+------------+
-| sphinx-rtd-theme   | ^0.5.1    | Any        |
-+--------------------+-----------+------------+
++----------------------+-----------+------------+
+| Package              | Version   | Platform   |
++======================+===========+============+
+| Sphinx               | ^5.0.0    | Any        |
++----------------------+-----------+------------+
+| sphinx-rtd-theme     | ^1.0.0    | Any        |
++----------------------+-----------+------------+
+| sphinxcontrib-bibtex | ^2.4.1    | Any        |
++----------------------+-----------+------------+