timesteps 0.9.3 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9b039e00dac34bb9cf616ea94da9465feb696179d550c1b6f7f511ddf06756f
-  data.tar.gz: ac64b576636a5d9f45bbca34fd21ea479911a4dc260df2ef5a3adb2b5071ae6d
+  metadata.gz: 5c66eb1faabea2c6a697af1b84d2b6e4b36419a7fe67f11a04d448476485697e
+  data.tar.gz: d32805b977369e85e0bacdce593275b6f5b30569be978cd74f61a355f9b4c67f
 SHA512:
-  metadata.gz: 237fa23fec58640aa1ab3ec9863a8f546016bc978d1b5258e5d5021fb875a55115696a3fb387dd4dc42e47cc561530b3de83604cf4cb7e2f708748183a011c67
-  data.tar.gz: 978d9e97ced5f11868018fc895fddb261eaf402e937a1371f0395c5f13c857dd1b3122d4e412cc723717fae8860a396fad804ffe316c80277c2516ed79b6de2e
+  metadata.gz: f3aba6dae421df42fd53fa5aaaf7b273c9aec3a99d48bd95f9ffd3c0f9b2e6b5a694cc6b8e0c59f3d87355ddb803258dec77d1830280e41e504f85a11ed3b87a
+  data.tar.gz: 835e7de674cc0dea1b51571b119bfd55922e8fe4215124048bdc0d519dfcd1ec0bcec176f3a918b844e60e4fe68105c7878b165695f6ec82e1da8e87cdb61d6e

data/Note.ja.md

@@ -74,3 +74,17 @@
 #### 360_day
 
 * すべての月が30日であるとした暦
+
+
+ts = TimeStep.new("6 hours since 2012-01-10 09:00:00")
+ts = ts.shift_origin_with_days(-256.quo(24))
+
+
+
+
+
+
+
+
+
+

data/README.md

@@ -9,49 +9,301 @@ Features
 --------
 
 * TimeStep consists of a pair of origin time and a time interval.
-* An instance of a TimeStep can be constructed by parsing an expression like "hours since 2001-01-01 00:00:00" (originate from udunits library)
-* DateTime object can be obtained from the index value (0 for the origin time).
-* The index value can be calculated from the date and time.
-* TimeStep can handle special calendar-type time series such as noleap, allleap, and 360_day.
-* "24:00:00" can be parsed as a valid timestamp.
-* You can pairert the index values between different TimeStep instances using TimeStepConv.
+* Parsing a time step expression like "hours since 2001-01-01 00:00:00" (originate from udunits library)
+* Obtaining time value for index value (0 for the origin time)
+* Obtaining index value for time value
+* Treating non-standard calendar-type such as 'noleap', 'allleap', and '360_day'
+* Comparing the index values between different time step definitions
 
-Usage
------
+Installation
+------------
 
-### TimeStep
+    gem install timesteps
+
+To use the library in your Ruby script, 
 
 ```ruby
 require "timesteps"
+```
+
+Description
+-----------
+
+This library was created for time conversion and intercomparison of multiple time series data in the case of handling time series data of the type that specifies the time using indexes of time steps since origin time. 
+
+#### Time steps
+
+The main class of this library is the TimeStep class, which holds the origin time and the interval representing the unit time step. When the TimeStep class is initialized, the following notation is used.
 
-ts = TimeStep.new("3 hours since 2001-01-01 09:00:00", calendar: "standard")
+  * "second since 1970-01-01 00:00:00 +00:00" 
+  * "hour since 2001-01-01 00:00:00 JST" 
+  * "3 days since 2001-01-01 00:00:00 +00:00" 
+  * "10 years since 1901-01-01 00:00:00 +00:00" 
 
-p ts                ### => #<TimeStep definition='3 hours since 2001-01-01 09:00:00.000000000 +00:00' calendar='standard'>
-  
-p ts.origin         ### => #<DateTime: 2001-01-01T09:00:00+00:00 ...>
+This is a notation used as a time unit in Unidata's [UDUNITS](https://www.unidata.ucar.edu/software/udunits/) library, and is also used as a unit of time axis in [CF conventions](http://cfconventions.org) of NetCDF (this notation is borrowed from the UDUnit library, but it should be noted that there are many differences).
 
-p ts.time_at(1)     ### => #<DateTime: 2001-01-01T12:00:00+00:00 ...>
-p ts.time_at(8)     ### => #<DateTime: 2001-01-02T09:00:00+00:00 ...>
+In this library, the elapsed time from the origin is expressed as an index value. For the case of "3 hours since 2001-01-01 00:00:00", the index values
+are expressed as, 
 
-time = DateTime.parse("2001-01-02 09:00:00 +00:00")
-p ts.index_at(time) ### => (8/1)    <Rational>
+  * "2001-01-01 00:00:00" => 0  (0 / 3 hours) (    0 days)
+  * "2001-01-01 03:00:00" => 1  (1 / 3 hours) ((1/8) days)
+  * "2001-01-02 00:00:00" => 8  (8 / 3 hours) (    1 days)
+
+This is expressed as a Ruby script.
+
+```ruby
+ts = TimeStep.new("3 hours since 2001-01-01 00:00:00")
+ts.index_at("2001-01-01 00:00:00")  ### => 0
+ts.index_at("2001-01-01 03:00:00")  ### => 1
+ts.index_at("2001-01-02 00:00:00")  ### => 8
+ts.time_at(0)  ### => #<DateTime 2001-01-01T00:00:00 ...>
+ts.time_at(1)  ### => #<DateTime 2001-01-01T03:00:00 ...>
+ts.time_at(8)  ### => #<DateTime 2001-01-02T00:00:00 ...>
+ts.days_at(0)  ### => 0      [Integer]
+ts.days_at(1)  ### => (1/8)  [Rational]
+ts.days_at(8)  ### => 1      [Integer] 
 ```
 
-### TimeStepPair
+#### Treatment of year and month units
+
+The time units like day, hour, minute, second have constant intervals,
+but the time units like years and months are not. So, the year and 
+month units are given special treatment in this library. 
+One year is counted at the same month and day as the origin time, and
+one month is counted at the same day as the origin time.
 
 ```ruby
-require "timesteps"
+ts = TimeStep.new("year since 2000-01-15 00:00:00")
+ts.index_at("2001-01-14 23:59:59")  ### => 0
+ts.index_at("2001-01-15 00:00:00")  ### => 1
+ts.index_at("2010-01-14 23:59:59")  ### => 9
+ts.index_at("2010-01-15 00:00:00")  ### => 10
+
+ts = TimeStep.new("month since 2000-01-15 00:00:00")
+ts.index_at("2000-02-14 23:59:59")  ### => 0
+ts.index_at("2000-02-15 00:00:00")  ### => 1
+ts.index_at("2000-11-14 23:59:59")  ### => 9
+ts.index_at("2000-11-15 00:00:00")  ### => 10
+```
+
+And, it is not possible to give a fractional index 
+for the units of year and month (some methods return a fractional index).
+
+```ruby
+ts = TimeStep.new("year since 2000-01-15 00:00:00")
+ts.time_at(0.5) ### => RuntimeError raised
+# => in `time_at': index for years should be an integer (RuntimeError)
+```
+
+#### Calendars
+
+The following calendars, including non-standard calendars, can be handled.
+
+  * standard, gregorian      
+  * proleptic_gregorian      
+  * proleptic_julian, julian 
+  * noleap, 365_day          
+  * allleap, 366_day         
+  * 360_day                  
+
+You can find the description for these calendar at the document of CF-Convensions ([4.4.1 Calendar](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#calendar)).
+
+```ruby
+ts = TimeStep.new("day since 2000-01-01", calendar: "standard")
+ts.time_at(59)  ### => #<DateTime: 2000-02-29T00:00:00+00:00 ...>
+
+ts = TimeStep.new("day since 2000-01-01", calendar: "noleap")
+ts.time_at(59)  ### => #<DateTime::NoLeap: 2000-03-01T00:00:00+00:00 ...>
+
+ts = TimeStep.new("day since 2000-01-01", calendar: "360_day")
+ts.time_at(59)  ### => #<DateTime::Fixed360Day: 2000-02-30T00:00:00+00:00 ...>
+```
+
+In this library, DateTime class is adopted as the object that represents date and time (not Time class). Non-standard calendars ("proleptic_gregorian", "Julian") can be handled by the DateTime class, with appropriate use of the start parameter. But, other non-standard calendars ("noleap", "allleap", "360_day") can not. So, DateTimeLike class and its subclasses DateTime::NoLeap, DateTime::AllLeap, DateTime::Fixed360Day are introduced. Since many (not all) of methods in DateTime class are also implemented in DateTimeLike class, users don't need to be too aware of these class differences.
+
+#### Parsing datetime string
+
+In `standard` calendar, use DateTime.parse as usual.
+In other calendar, you can use DateTime.parse_timestamp, which is 
+special method to parse date time string with specification of calendar.
+
+```ruby
+DateTime.parse_timestamp("1200-01-01") ### "standard"
+DateTime.parse_timestamp("1200-01-01", calendar: "proleptic_gregorian")
+DateTime.parse_timestamp("1200-01-01", calendar: "julian")
+DateTime.parse_timestamp("1200-01-01", calendar: "noleap")
+DateTime.parse_timestamp("1200-01-01", calendar: "allleap")
+DateTime.parse_timestamp("1200-01-01", calendar: "360_day")
+```
+
+If you already have the instance of TimeStep, you can use the method named TimeStep#parse, which is called when it is necessary to convert from the string to the date and time internally.
+
+```ruby
+ts = TimeStep.new("days since 2001-01-01", calendar: "allleap")
+ts.parse("2001-02-29") ### => #<DateTime::AllLeap 2001-02-29T ...>
+```
+
+In the UDUNITS library, negative years are treated as BCs and A.D. 0 is treated as non-existent. This is different from how it is handled in Ruby's DateTime class. To parse date time string of UDUNITS type, `bc` option for `Date.parse_timestamp` method.
+
+```ruby
+DateTime.parse_timestamp("-0001-01-01") 
+   # => #<DateTime: -0001-01-01T00:00:00+00:00 ...>
+   # B.C. 2
+
+DateTime.parse_timestamp("-0001-01-01", bc: true) 
+   # => #<DateTime: 0000-01-01T00:00:00+00:00 ...>
+   # B.C. 1
+
+DateTime.parse_timestamp("BC 0001-01-01") 
+   # => #<DateTime: 0000-01-01T00:00:00+00:00 ...>
+   # B.C. 1
+```
 
+#### Comparing two time series
+
+TimeStep::Pair is a class to compare indices of two time series,
+which is initialized by two time step object. It is possible to 
+compute the other index corresponding to the time represented 
+by one of the indices using TimeStep::Pair.
+
+
+```ruby
+# Create TimeStepPair object
 ts1 = TimeStep.new("3 hours since 2001-01-01 21:00:00")
 ts2 = TimeStep.new("hour since 2001-01-01 09:00:00")
 pair = TimeStep::Pair.new(ts1, ts2)
 
-p pair            ### => <TimeStepConv from='<TimeSteps unit='3 hour since 2001-01-01 21:00:00.000000000' calendar='standard'>' to='<TimeSteps unit='hour since 2001-01-01 09:00:00.000000000' calendar='standard'>'>
-  
-p pair.forward(0) ### 12/1  (12)
-p pair.forward(2) ### 18/1  (12 + 2*3h/1h)
+# You can create same object with,
+# pair = TimeStep::Pair.new("3 hours since 2001-01-01 21:00:00", 
+#                           "hour since 2001-01-01 09:00:00")
+
+# Forward conversion
+pair.forward(0)
+   # => 12
+pair.forward(2) 
+   # => 18        (12 + 2*3h/1h)
+
+# Inverse conversion
+pair.inverse(0) 
+   # => -4        ((-12h)/3h)
+pair.inverse(2) 
+   # => (-10/3)   ((-12h+2*1h)/3h)
+```
+
+Examples
+========
+
+### Construct a TimeStep object
+
+```ruby
+# standard calendar
+ts = TimeStep.new("3 hours since 2001-01-01 09:00:00")
+
+# noleap calendar
+ts = TimeStep.new("3 hours since 2001-01-01 09:00:00", calendar: "noleap")
+
+# specify origin time with DateTime object
+ts = TimeStep.new("3 hours", since: DateTime.parse("2001-01-01 09:00:00"))
+```
+
+### Attributes of TimeStep object
+
+```ruby
+ts = TimeStep.new("3 hours since 2001-01-01 09:00:00")
+
+# specification
+ts.definition
+   # => "3 hours since 2001-01-01 09:00:00.000000000 +00:00"
+ts.intervalspec
+   # => "3 hours"
+ts.originspec
+   # => "2001-01-01 09:00:00.000000000 +00:00"
+
+# data for time interval
+ts.numeric
+   # => (3/1)
+ts.symbol
+   # => :hours
+ts.interval
+   # => (10800/1)
+
+# origin time
+ts.origin
+   # => #<DateTime: 2001-01-01T09:00:00+00:00 ((2451911j,32400s,0n),+0s,2299161j)>
+
+# calendar 
+ts.calendar
+   # => #<TimeStep::Calendar calendar='standard' bc='false'>
+```
+
+### What is the index value of the time step 'TS' corresponding to time 'T' ?
+
+```ruby
+# hours
+ts = TimeStep.new("6 hours since 2000-01-15 00:00:00")
+ts.index_at("2000-01-25 00:00:00")
+   # => 40
+ts.index_at("2000-01-25 03:00:00")
+   # => (81/2)
+```
+
+### What is the time corresponding to index 'I' of time step 'TS' ?
+
+```ruby
+# hours
+ts = TimeStep.new("6 hours since 2000-01-15 00:00:00")
+ts.time_at(40)
+   # => #<DateTime: 2000-01-25T00:00:00+00:00 ...>
+ts.time_at(40.5)
+   # => #<DateTime: 2000-01-25T03:00:00+00:00 ...>
+````
+
+### What is the UNIX time stamp for the time corresponding to index 'I' of time step 'TS' ?
+
+```ruby
+ts = TimeStep.new("hour since 2000-01-01 00:00:00")
+unixtime = TimeStep.new("seconds since 1970-01-01 00:00:00")
+pair = TimeStep::Pair.new(ts, unixtime)
+
+# UNIX time for index 0
+pair.forward(0)
+   # => 946684800
+
+# UNIX time for index 10
+pair.forward(10)
+   # => 946720800
+````
+
+### How to get each index for a certain time of multiple time steps having different origin times ?
+
+```ruby
+conv = TimeStep::Converter.new("hour since 2000-01-01 00:00:00", name: "ts0")
+conv["ts1"] = "hour since 2000-01-02 00:00:00"
+conv["ts2"] = "hour since 2000-01-03 00:00:00"
+conv["ts3"] = "hour since 2000-01-04 00:00:00"
+
+# index 0 for ts0
+conv.forward(0)
+   # => {"ts0"=>0, "ts1"=>-24, "ts2"=>-48, "ts3"=>-72}
+
+# index 56 for ts0
+conv.forward(56)
+   # => {"ts0"=>56, "ts1"=>32, "ts2"=>8, "ts3"=>-16}
+
+# index 81 for ts0
+conv.forward(81)
+   # => {"ts0"=>81, "ts1"=>57, "ts2"=>33, "ts3"=>9}
+
+# indices [0, 56, 81] for ts0 with time
+conv.forward(0, 56, 81, with_time: true)
+   # {"time"=>
+   #   [#<DateTime: 2000-01-01T00:00:00+00:00 ((2451545j,0s,0n),+0s,2299161j)>,
+   #    #<DateTime: 2000-01-03T08:00:00+00:00 ((2451547j,28800s,0n),+0s,2299161j)>,
+   #   #<DateTime: 2000-01-04T09:00:00+00:00 ((2451548j,32400s,0n),+0s,2299161j)>],
+   #  "ts0"=>[0, 56, 81],
+   #  "ts1"=>[-24, 32, 57],
+   #  "ts2"=>[-48, 8, 33],
+   #  "ts3"=>[-72, -16, 9]}
 
-p pair.inverse(0) ### -4/1  ((-12h)/3h)
-p pair.inverse(2) ### -10/3 ((-12h+2*1h)/3h)
 ```
 

data/lib/timesteps.rb

@@ -1,10 +1,13 @@
 
 require "date"
 require "timesteps/datetimelike"
+require "timesteps/datetime_noleap"
+require "timesteps/datetime_allleap"
+require "timesteps/datetime_360day"
 require "timesteps/parse_timestamp"
 require "timesteps/format"
-require "timesteps/timestepdatetimeext"
+require "timesteps/timestep_datetime_ext"
 require "timesteps/calendar"
 require "timesteps/timestep"
-require "timesteps/timesteppair"
-require "timesteps/timestepconverter"
+require "timesteps/timestep_pair"
+require "timesteps/timestep_converter"

data/lib/timesteps/calendar.rb

@@ -12,9 +12,18 @@ class TimeStep
     # @private
     SYM_360_day = "360_day".intern
 
+    DateTimeType = {
+      :standard => DateTime,
+      :proleptic_gregorian => DateTime,
+      :proleptic_julian => DateTime,
+      :noleap => DateTime::NoLeap,
+      :allleap => DateTime::AllLeap,
+      SYM_360_day => DateTime::Fixed360Day,
+    }
+
     def initialize (calendar = "standard", bc: false)
-      @name     = calendar
-      @bc       = bc
+      @name = calendar
+      @bc   = bc
       case @name.downcase.intern
       when :standard, :gregorian
         @calendar = :standard
@@ -33,6 +42,10 @@ class TimeStep
     
     attr_reader :name, :calendar
     
+    def inspect 
+      "#<TimeStep::Calendar calendar='#{@calendar.to_s}' bc='#{@bc}'>"
+    end
+    
     def == (other)
       return @calendar == other.calendar && bc? == other.bc?
     end
@@ -41,26 +54,26 @@ class TimeStep
       return @bc ? true : false
     end
     
-    # Parses the given representation of date and time in the calendar, 
-    # and creates an date time instance.
-    # 
-    # @return [DateTime object]
-    def parse (timespec)
+    def valid_datetime_type? (time)
+      return false unless time.is_a?(DateTimeType[@calendar])
       case @calendar
       when :standard
-        time = DateTime.parse_timestamp(timespec, Date::ITALY, bc: @bc)
+        return time.start == Date::ITALY
       when :proleptic_gregorian
-        time = DateTime.parse_timestamp(timespec, Date::GREGORIAN, bc: @bc)
+        return time.start == Date::GREGORIAN
       when :proleptic_julian
-        time = DateTime.parse_timestamp(timespec, Date::JULIAN, bc: @bc)
-      when :noleap
-        time = DateTime::NoLeap.parse_timestamp(timespec, bc: @bc)
-      when :allleap
-        time = DateTime::AllLeap.parse_timestamp(timespec, bc: @bc)
-      when SYM_360_day
-        time = DateTime::Fixed360Day.parse_timestamp(timespec, bc: @bc)
-      end
-      return time
+        return time.start == Date::JULIAN
+      else
+        return true
+      end 
+    end
+    
+    # Parses the given representation of date and time in the calendar, 
+    # and creates an date time instance.
+    # 
+    # @return [DateTime object]
+    def parse (timespec, format: nil)
+      return DateTime.parse_timestamp(timespec, calendar: @calendar.to_s, bc: @bc, format: format)
     end
     
     def jday2date (jday)

data/lib/timesteps/datetime_360day.rb

@@ -0,0 +1,38 @@
+class DateTime
+
+  # datetime class represents `360_day` calendar
+  #
+  class Fixed360Day < DateTimeLike
+
+    extend DateTimeLikeExtension
+
+    # Number of days per year
+    DPY = 360
+
+    # Numbers of days per months
+    DPM = [0,30,30,30,30,30,30,30,30,30,30,30,30]
+
+    # Astronomical Julian day number of UNIX epoch
+    UNIX_EPOCH_IN_AJD = Rational(4811039,2)
+
+    def valid_date?
+      if @day >= 31
+        return false
+      end
+      if @month != 2
+        return Date.valid_date?(@year, @month, @day)
+      else
+        return ( @day >= 1 and @day <= 30 )
+      end
+    end
+
+    private :valid_date?
+
+    def leap?
+      raise NotImplementedError
+    end
+  
+  end
+
+end
+