ast-tdl 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e1cae6b9c56c969808cd16ff2d58ec838db46745cf3f6b9b1eb3583536ad93b
-  data.tar.gz: '0841bfa32e170d22ec587d027086ce4816a86d8116627c8f365000010ebd224a'
+  metadata.gz: 958f254f2b529fc7ebac3dbe7b8cea91cdc4aee005e92a3cdf3add30462b5c06
+  data.tar.gz: 07b57062cdbd2026c52d33fa6fea08be22eb32f413864b21ad8adab5dde4f468
 SHA512:
-  metadata.gz: 179ff4d41c5e51f81f2298bd6363fdbd58afe24b729274a4fc50eb04ffacb3eec453726da1817f4995c55d9923d5202e15c1083f5a7e762993fb7aab08edba48
-  data.tar.gz: 9e644b6a2f48ec60038a31c503a7d65fbfa4cc8bc89c19f8e9f2da31700f6299794eb292f37cfc2df72b05c9c8d92f8beb420f94c779055761d5fabfe9ca154c
+  metadata.gz: b27e545b912fb3dc74fd96b134e13540ecfbf799be3feb25009d1fdad3f29b8811f73a57f96beb18fc4ac84ea9a2ca74c55606fdb7b2c1a1606c52fe74bbcb88
+  data.tar.gz: f582e0a61eb96f7a89f004e041a80b753bbe3f5e302efc729b9f170c87d0904b027c22ed21a9b9ff19e8ab02ff8402cc778fba5c26da7ef0b5ffacc599dfa3c4

data/README.md

@@ -1,68 +1,83 @@
 # Training Description Language (TDL) for Artificial Sport Trainer (AST)
 
+---
+
+[![DOI](https://img.shields.io/badge/DOI-10.1109/ISCMI53840.2021.9654817-blue)](https://doi.org/10.1109/ISCMI53840.2021.9654817)
+
 ## Motivation
 ast-dsl is intended to be a small DSL for practical definition and description of sports training that can be automatically or manually defined and used in conjunction with Artificial Sport Trainer.
 
+According to sports theory, three major types of sports trainings exist:
+- speed trainings,
+- interval trainings and
+- power trainings.
+
+Speed trainings are intended for supplying an athlete with energy, coordination and power adaptation. This type of sports training is often used by middle-distance athletes, as they can be very useful for enhancing their performance.
+
+Interval training has been described for the first time by Reindell and Roskamm, however, it was popularized by the famous Chech athlete Emil Zatopek. This type of training consists of a speed phase that is followed by a recovery phase. This sequence is repeated for several times where the number of repetitions depends on interval training plan.
+
+Power trainings have been proven to be an effective method for increasing muscle mass. Consequently, in most cases they are used at extreme sports, such as weight lifting, where the lactate amount in blood is significant.
+
 ## Feature diagram
-![scheme](https://user-images.githubusercontent.com/73126820/177509075-977b2e18-ebb7-40ce-9af9-ed7715717bf3.png)
+![ast-tdl](https://user-images.githubusercontent.com/73126820/193033601-6c94b328-30a4-4b25-86a3-0fb81cebca3d.png)
 
 ## Installation
-    $ gem install ast-tdl
+```sh
+$ gem install ast-tdl
+```
 
 ## Language description
-Training Description Language (TDL) is implemented in Ruby. Currently, the description of sports training sessions and intervals is now supported. Those contain various data, such as duration, average heart rate, sport type, and many more.
+Training Description Language (TDL) is implemented in Ruby. All three major training types (speed, interval and power) can be described in TDL.
+
+Speed training sessions are described with their name, sport type, proposed average heart rate and total duration, while the additional information is optional. 
+
+Interval training sessions, as well as their speed counterparts, are described with their name, type of sport and optional information. However, heart rate and duration of intervals are described separately for both speed and recovery phase. Additionally, number of repetitions and interval training type are also described along with forementioned features.
+
+Power training sessions are described with their names and sport types, but opposed to speed and interval they are described with series, which are furtherly described with their name, intensity level from 1 to 10 and number of repetitions. 
 
 ## Examples
+### Example of a sports training
 ```ruby
-Ast.build('My first training') do
-  session('Short swimming session') do
-    sport               :swim
-    info                :"Very easy training"
-    average_heart_rate  :"130"
-    total_duration      :"30"
+Ast.build do
+  speed('Swimming with the dolphins') do
+    sport                   Sport::SWIMMING
+    info                    :"Very easy training"
+    average_heart_rate      :"130"
+    total_duration          :"30"
   end
 
-  session('Bike ride') do
-    sport               :cycling
-    info                :"Endurance ride with intervals"
-    average_heart_rate  :"140"
-    total_duration      :"120"
+  speed('Cross the country') do
+    sport                   Sport::CYCLING
+    info                    :"Endurance ride"
+    average_heart_rate      :"140"
+    total_duration          :"120"
   end
 
-  interval('Sample interval') do
-    sport                   :cycling
-    info                    :Moderate
-    speed_duration          :"5"
-    recovery_duration       :"5"
+  interval('Following Emil Zatopek') do
+    sport                   Sport::RUNNING
+    info                    :Hard
+    speed_duration          :"1"
+    recovery_duration       :"1"
     speed_heart_rate        :"180"
     recovery_heart_rate     :"90"
     repetitions             :"10"
+    type                    :fixed
   end
-end
-```
-
-### Session
-```ruby
-session('Bike ride') do
-  sport               :cycling
-  info                :"Endurance ride with intervals"
-  average_heart_rate  :"140"
-  total_duration      :"120"
-end
-```
 
-### Interval
-```ruby
-interval('Sample interval') do
-  sport                :cycling
-  info                 :Moderate
-  speed_duration       :"5"
-  recovery_duration    :"5"
-  speed_heart_rate     :"180"
-  recovery_heart_rate  :"90"
-  repetitions          :"10"
+  power('As strong as an ox') do
+    sport                   Sport::WEIGHT_LIFTING
+    series('Little ox') do
+      intensity:   :"5"
+      repetitions  :"20"
+    end
+    series('Big ox') do
+      intensity    :"10"
+      repetitions  :"80"
+    end
+  end
 end
 ```
+The description of the sports training consists of four sessions: two speed sessions, one interval sesssion and one power session. The first, swimming speed session is relatively easy, as the planned heart rate throughout the whole session is prescribed to be 130 bpm, and it lasts for half an hour. The next, cycling speed session is described as a 2-hour endurance ride with the prescribed average heart rate of 140 bpm. The third session is a hard, running interval training. It consists of 10 fixed intervals, where speed phase and recovery duration are 1 minute each. The proposed heart rate during speed phases is set at 180 bpm, while in recovery phases it is set to half the speed heart rate: 90 bpm. The final, weight lifting power session consists of two series, the first being of middle intensity with 20 repetitions and the second being of extreme intensity with 80 repetitions.
 
 ## License
 This package is distributed under the MIT License. This license can be found online at <http://www.opensource.org/licenses/MIT>.
@@ -71,5 +86,6 @@ This package is distributed under the MIT License. This license can be found onl
 This framework is provided as-is, and there are no guarantees that it fits your purposes or that it is bug-free. Use it at your own risk!
 
 ## References
-
 Fister Jr, I., Fister, I., Iglesias, A., Galvez, A., Deb, S., & Fister, D. (2021). On deploying the Artificial Sport Trainer into practice. arXiv preprint [arXiv:2109.13334](https://arxiv.org/abs/2109.13334).
+
+Lukač, L. (2022). Aplikacija koncepta digitalnega dvojčka v športu [online]. University of Maribor, Faculty of Electrical Engineering and Computer Science. [Access: 29th September, 2022].

data/lib/ast.rb

@@ -2,7 +2,9 @@
 
 require 'json'
 require_relative 'interval'
-require_relative 'session'
+require_relative 'power'
+require_relative 'speed'
+require_relative 'sport'
 
 ##
 # This module is intended to be used for building trainings
@@ -11,10 +13,9 @@ module Ast
   ##
   # Building a new training from the domain specific language.
   # Params:
-  # +name+:: the name of the training
   # +block+:: training data
-  def self.build(name, &block)
-    training = Training.new(name)
+  def self.build(&block)
+    training = Training.new()
     training.instance_eval(&block)
     training
   end
@@ -26,21 +27,21 @@ module Ast
     # Initialization method for the +Training+ class.
     # Params:
     # +name+:: the name of the training
-    def initialize(name)
-      @name = name
-      @session = []
+    def initialize
+      @speed = []
       @interval = []
+      @power = []
     end
 
     ##
-    # Building a new session from the domain specific language.
+    # Building a new speed session from the domain specific language.
     # Params:
-    # +name+:: the name of the session
-    # +block+:: session data
-    def session(name, &block)
-      training_type = Session.new(name)
+    # +name+:: the name of the speed session
+    # +block+:: speed session data
+    def speed(name, &block)
+      training_type = Speed.new(name)
       training_type.instance_eval(&block)
-      @session << training_type
+      @speed << training_type
     end
 
     ##
@@ -54,19 +55,37 @@ module Ast
       @interval << interval_data
     end
 
+    ##
+    # Building a new power session from the domain specific language.
+    # Params:
+    # +name+:: the name of the power session
+    # +block+:: power session data
+    def power(name, &block)
+      power_data = Power.new(name)
+      power_data.instance_eval(&block)
+      @power << power_data
+    end
+
     ##
     # Converting a training to a string.
     def to_s
-      "#{@name} #{@session[0]}"
+      speed_number = @speed.length
+      interval_number = @interval.length
+      power_number = @power.length
+
+      "TRAINING DATA:\n"\
+      "Speed sessions: #{speed_number}\n"\
+      "Interval sessions: #{interval_number}\n"\
+      "Power sessions: #{power_number}\n\n"
     end
 
     ##
     # Converting a training to a JSON-ized string.
     def json
       training_json = {
-        name: @name,
-        session: @session.collect(&:to_hash),
-        interval: @interval.collect(&:to_hash)
+        speed: @speed.collect(&:to_hash),
+        interval: @interval.collect(&:to_hash),
+        power: @power.collect(&:to_hash)
       }
       JSON.pretty_generate(training_json)
     end
@@ -76,7 +95,7 @@ module Ast
     # Params:
     # +filename+:: the desired name of the file
     def save_to_file(filename)
-      f = File.open(filename, 'w')
+      f = File.open("../trainings/#{filename}", 'w')
       f.puts(json)
       f.close
     end

data/lib/interval.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'sport'
+
 ##
 # This class represents an interval.
 class Interval
@@ -24,6 +26,8 @@ class Interval
   # Params:
   # +type+:: the type of the sport
   def sport(type)
+    raise 'The sport name has to be from the Sport class collection.' unless Sport.values.include? type
+
     @sport = type
   end
 
@@ -40,7 +44,12 @@ class Interval
   # Params:
   # +speed_duration+:: the duration of the speed segment in minutes
   def speed_duration(speed_duration)
-    @speed_duration = speed_duration.to_s.to_i
+    speed_duration_str = speed_duration.to_s
+    speed_duration_int = speed_duration.to_s.to_i
+    raise 'The given speed duration is not an integer.' if speed_duration_str != speed_duration_str.to_i.to_s
+    raise 'The speed duration has to be 1 minute at least.' if speed_duration_int < 1
+
+    @speed_duration = speed_duration_int
   end
 
   ##
@@ -48,7 +57,12 @@ class Interval
   # Params:
   # +recovery_duration+:: the duration of the recovery segment in minutes
   def recovery_duration(recovery_duration)
-    @recovery_duration = recovery_duration.to_s.to_i
+    recovery_duration_str = recovery_duration.to_s
+    recovery_duration_int = recovery_duration.to_s.to_i
+    raise 'The given recovery duration is not an integer.' if recovery_duration_str != recovery_duration_str.to_i.to_s
+    raise 'The recovery duration has to be 1 minute at least.' if recovery_duration_int < 1
+
+    @recovery_duration = recovery_duration_int
   end
 
   ##
@@ -56,7 +70,12 @@ class Interval
   # Params:
   # +speed_heart_rate+:: the average speed heart rate in bpm
   def speed_heart_rate(speed_heart_rate)
-    @speed_heart_rate = speed_heart_rate.to_s.to_i
+    speed_hr_str = speed_heart_rate.to_s
+    speed_hr_int = speed_heart_rate.to_s.to_i
+    raise 'The given average heart rate is not an integer.' if speed_hr_str != speed_hr_str.to_i.to_s
+    raise 'The speed heart rate should be between 60 and 205 bpm.' if speed_hr_int < 60 || speed_hr_int > 205
+
+    @speed_heart_rate = speed_hr_int
   end
 
   ##
@@ -64,7 +83,12 @@ class Interval
   # Params:
   # +recovery_heart_rate+:: the average speed heart rate in bpm
   def recovery_heart_rate(recovery_heart_rate)
-    @recovery_heart_rate = recovery_heart_rate.to_s.to_i
+    recovery_hr_str = recovery_heart_rate.to_s
+    recovery_hr_int = recovery_heart_rate.to_s.to_i
+    raise 'The given average heart rate is not an integer.' if recovery_hr_str != recovery_hr_str.to_i.to_s
+    raise 'The recovery heart rate should be between 60 and 205 bpm.' if recovery_hr_int < 60 || recovery_hr_int > 205
+
+    @recovery_heart_rate = recovery_hr_int
   end
 
   ##
@@ -72,7 +96,12 @@ class Interval
   # Params:
   # +repetitions+:: number of interval repetitions
   def repetitions(repetitions)
-    @repetitions = repetitions.to_s.to_i
+    repetitions_str = repetitions.to_s
+    repetitions_int = repetitions.to_s.to_i
+    raise 'The given number of repetitions is not an integer.' if repetitions_str != repetitions_str.to_i.to_s
+    raise 'The minimum number of repetitions is 1.' if repetitions_int < 1
+
+    @repetitions = repetitions_int
   end
 
   ##

data/lib/power.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'series'
+require_relative 'sport'
+
+##
+# This class represents a power training session.
+class Power
+  ##
+  # Initialization method for the +Power+ class.
+  # Params:
+  # +name+:: the name of the power session
+  def initialize(name)
+    @name = name
+    @series = []
+    @sport = ''
+  end
+
+  ##
+  # Building a new series from the domain specific language.
+  # Params:
+  # +name+:: the name of the series
+  # +block+:: power session data
+  def series(name, &block)
+    series_data = Series.new(name)
+    series_data.instance_eval(&block)
+    @series << series_data
+  end
+
+  ##
+  # Adding a sport type to the object.
+  # Params:
+  # +type+:: the type of the sport
+  def sport(type)
+    raise 'The sport name has to be from the Sport class collection.' unless Sport.values.include? type
+
+    @sport = type
+  end
+
+  ##
+  # Converting a speed session to a string.
+  def to_s
+    @name
+  end
+
+  ##
+  # Converting a session to a JSON-ized string.
+  def to_hash
+    {
+      name: @name,
+      sport: @sport,
+      series: @series.collect(&:to_hash)
+    }
+  end
+end

data/lib/series.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+##
+# This class represents a series in power training session.
+class Series
+  ##
+  # Initialization method for the +Series+ class.
+  # Params:
+  # +name+:: the name of the series
+  def initialize(name)
+    @name = name
+    @intensity = 0
+    @repetitions = 0
+  end
+
+  ##
+  # Adding an intensity in the range [1, 10] to the series.
+  # Params:
+  # +intensity+:: intensity level
+  def intensity(intensity)
+    intensity_str = intensity.to_s
+    intensity_int = intensity.to_s.to_i
+    raise 'The given intensity level is not an integer.' if intensity_str != intensity_str.to_i.to_s
+    raise 'The intensity level should be between 1 and 10.' if intensity_int < 1 || intensity_int > 10
+
+    @intensity = intensity_int
+  end
+
+  ##
+  # Adding a number of repetitions to the object.
+  # Params:
+  # +repetitions+:: number of repetitions inside of a series
+  def repetitions(repetitions)
+    repetitions_str = repetitions.to_s
+    repetitions_int = repetitions.to_s.to_i
+    raise 'The given number of repetitions is not an integer.' if repetitions_str != repetitions_str.to_i.to_s
+    raise 'The minimum number of repetitions is 1.' if repetitions_int < 1
+
+    @repetitions = repetitions_int
+  end
+
+  ##
+  # Converting a speed session to a string.
+  def to_s
+    @name
+  end
+
+  ##
+  # Converting a session to a JSON-ized string.
+  def to_hash
+    {
+      name: @name,
+      intensity: @intensity,
+      repetitions: @repetitions
+    }
+  end
+end

data/lib/speed.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative 'sport'
+
+##
+# This class represents a speed training session.
+class Speed
+  ##
+  # Initialization method for the +Speed+ class.
+  # Params:
+  # +name+:: the name of the speed session
+  def initialize(name)
+    @name = name
+    @sport = ''
+    @info = ''
+    @average_heart_rate = 0
+    @total_duration = 0
+  end
+
+  ##
+  # Adding a sport type to the object.
+  # Params:
+  # +type+:: the type of the sport
+  def sport(type)
+    raise 'The sport name has to be from the Sport class collection.' unless Sport.values.include? type
+
+    @sport = type
+  end
+
+  ##
+  # Adding a message to the object.
+  # Params:
+  # +message+:: the info message
+  def info(message)
+    @info = message
+  end
+
+  ##
+  # Adding an average heart rate to the object.
+  # Params:
+  # +heart_rate+:: the average heart rate in bpm
+  def average_heart_rate(heart_rate)
+    heart_rate_str = heart_rate.to_s
+    heart_rate_int = heart_rate.to_s.to_i
+    raise 'The given average heart rate is not an integer.' if heart_rate_str != heart_rate_str.to_i.to_s
+    raise 'The average heart rate should be between 60 and 205 bpm.' if heart_rate_int < 60 || heart_rate_int > 205
+
+    @average_heart_rate = heart_rate_int
+  end
+
+  ##
+  # Adding a total duration to the object.
+  # Params:
+  # +duration+:: the duration in minutes
+  def total_duration(duration)
+    duration_str = duration.to_s
+    duration_int = duration.to_s.to_i
+    raise 'The given average heart rate is not an integer.' if duration_str != duration_str.to_i.to_s
+    raise 'The duration has to be 1 minute at least.' if duration_int < 1
+
+    @total_duration = duration_int
+  end
+
+  ##
+  # Converting a speed session to a string.
+  def to_s
+    "#{@sport} #{@info}"
+  end
+
+  ##
+  # Converting a session to a JSON-ized string.
+  def to_hash
+    hash = {
+      name: @name,
+      sport:	@sport,
+      average_heart_rate: @average_heart_rate,
+      total_duration: @total_duration
+    }
+
+    hash[:info] = @info if @info != ''
+    hash
+  end
+end

data/lib/sport.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'ruby-enum'
+
+##
+# This class represents a collection of sports.
+class Sport
+  include Ruby::Enum
+
+  define :CYCLING, 'cycling'
+  define :RUNNING, 'running'
+  define :SWIMMING, 'swimming'
+  define :CROSS_COUNTRY_SKIING, 'cross country skiing'
+  define :WEIGHT_LIFTING, 'weight lifting'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-tdl
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - firefly-cpp
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-07-07 00:00:00.000000000 Z
+date: 2022-09-29 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -24,7 +24,10 @@ files:
 - lib/ast-tdl.rb
 - lib/ast.rb
 - lib/interval.rb
-- lib/session.rb
+- lib/power.rb
+- lib/series.rb
+- lib/speed.rb
+- lib/sport.rb
 homepage: https://github.com/firefly-cpp/ast-tdl
 licenses:
 - MIT

data/lib/session.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-##
-# This class represents a session.
-class Session
-  ##
-  # Initialization method for the +Session+ class.
-  # Params:
-  # +name+:: the name of the session
-  def initialize(name)
-    @name = name
-    @sport = ''
-    @info = ''
-    @average_heart_rate = 0
-    @total_duration = 0
-  end
-
-  ##
-  # Adding a sport type to the object.
-  # Params:
-  # +type+:: the type of the sport
-  def sport(type)
-    @sport = type
-  end
-
-  ##
-  # Adding a message to the object.
-  # Params:
-  # +message+:: the info message
-  def info(message)
-    @info = message
-  end
-
-  ##
-  # Adding an average heart rate to the object.
-  # Params:
-  # +heart_rate+:: the average heart rate in bpm
-  def average_heart_rate(heart_rate)
-    @average_heart_rate = heart_rate.to_s.to_i
-  end
-
-  ##
-  # Adding a total duration to the object.
-  # Params:
-  # +duration+:: the duration in minutes
-  def total_duration(duration)
-    @total_duration = duration.to_s.to_i
-  end
-
-  ##
-  # Converting a session to a string.
-  def to_s
-    "#{@sport} #{@info}"
-  end
-
-  ##
-  # Converting a session to a JSON-ized string.
-  def to_hash
-    hash = {
-      name: @name,
-      sport:	@sport,
-      average_heart_rate: @average_heart_rate,
-      total_duration: @total_duration,
-    }
-
-    hash[:info] = @info if @info != ''
-    hash
-  end
-end