//
//   Copyright 2020  SenX S.A.S.
//
//   This program is free software: you can redistribute it and/or modify it
//   under the terms of the GNU Affero General Public License as published
//   by the Free Software Foundation, version 3.
//
//   This program is distributed in the hope that it will be useful,
//   but WITHOUT ANY WARRANTY; without even the implied warranty
//   of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
//   See the GNU Affero General Public License for more details.
//
//   You should have received a copy of the GNU Affero General Public License
//   along with this program. If not, see <https://www.gnu.org/licenses/>
//

{
    'name' 'senx/cal/BUCKETIZE.byyear'
    'since' '2.4.1'
    'tags' [ 'framework' 'bucketize' 'gts' 'bucketizer' 'cal' ]
    'desc' 
    <'
Creates bucketized Geo Time Series with yearly buckets that start at the begining of a year. The lastbucket and the bucketcount are computed automatically.

In the resulting series, the tick associated to each bucket is its year index (the number of years that are ended since Unix Epoch).
For example, bucket 0 spans the interval ['1970-01-01T00:00:00.000000Z', '1970-12-31T23:59:59.999999Z'] (if the platform is configured with microseconds precision).

Timestamp ticks can be restored using the macro UNBUCKETIZE.CALENDAR. In that case, each bucket's tick will be replaced by the last timestamp of their year.

For more control on other parameters of the bucketization process, use instead BUCKETIZE.CALENDAR.
    '>
    'sig' [ 
      [ [ [ 'bucketizer:BUCKETIZER' 'gts:GTS+' ] ]  [ 'result:LIST<GTS>' ] ]
      [ [ [ 'macro:MACRO' 'gts:GTS+' ] ]  [ 'result:LIST<GTS>' ] ]
      [ [ [ 'timezone:STRING' 'bucketizer:BUCKETIZER' 'gts:GTS+' ] ]  [ 'result:LIST<GTS>' ] ]
      [ [ [ 'timezone:STRING' 'macro:MACRO' 'gts:GTS+' ] ]  [ 'result:LIST<GTS>' ] ]
      ]
    'params' {
      'gts' 'One or more Geo Time Series™ or lists of Geo Time Series™'
      'bucketizer' 'Bucketizer function to apply'
      'macro' 'Macro to apply. Must expect a GTS as input. Must push onto the stack either [value], or [tick,value], or [tick,elev,value], or [tick,lat,lon,value], or [tick,lat,lon,elev,value], or tick, lat, lon, elev and value.'
      'timezone' 'The timezone to consider. Default to UTC'
      'result' 'List of bucketized GTS in the new time referential'
    }
    'related' [
      'BUCKETIZE.CALENDAR' 'BUCKETIZE' 'UNBUCKETIZE.CALENDAR' '@senx/cal/BUCKETIZE.bymonth'
    ]
    'examples' [
      <'
[ 2019 ] TSELEMENTS-> 'end' STORE
NEWGTS 1 2000 <% $end SWAP -1 * ADDDAYS NaN NaN NaN 1 ADDVALUE %> FOR
[ SWAP bucketizer.count ] @senx/cal/BUCKETIZE.byyear UNBUCKETIZE.CALENDAR
      '>
    ]
} 'info' STORE

<%
  !$info INFO
  SAVE 'context' STORE

    // handle optional timezone
    REVERSE
    0 REMOVE DUP TYPEOF 'STRING' ==
    <% 'tz' STORE 0 REMOVE %>
    <% 'UTC' 'tz' STORE %>
    IFTE

    // handle bucketizer
    'bucketizer' STORE
    $bucketizer TYPEOF 'MACRO' !=
    $bucketizer TYPEOF 'MAPPER' != &&
    $bucketizer TYPEOF 'AGGREGATOR' != &&
    <% 'Expects a macro or a bucketizer after input GTS.' MSGFAIL %> IFT
    
    // apply yearly bucketize
    REVERSE FLATTEN
    <%
      DROP
      'gts' STORE

      $gts SIZE 0 ==
      <%
        // empty gts, return a calendar-bucketized gts bucketoffset is 0
        [ $gts $bucketizer -1 'P1Y' 0 $tz ] BUCKETIZE.CALENDAR
      %>
      <%
        // non empty gts
        $gts LASTTICK $tz ->TSELEMENTS [ 0 ] SUBLIST $tz TSELEMENTS-> $tz 1 ADDYEARS 1 - 'lastbucket' STORE
        [ $gts $bucketizer $lastbucket 'P1Y' 0 $tz ] BUCKETIZE.CALENDAR
      %> IFTE

    %>
    LFLATMAP

  $context RESTORE
%>