Skip to content
Branch: master
Go to file
Code

Latest commit

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Merch Calendar

Gem Version Build Status Code Climate Coverage Status

This gem allows for finding retail/merchandising weeks for a given date, along with manipulating the retail calendar. This gem is used at Stitch Fix.

Installation

$ gem install merch_calendar

Add the following line to your Gemfile:

gem "merch_calendar"

Ruby Version Compatibility

This gem has been tested against Ruby 2.0 - 2.4.

Support for Ruby 1.9.3 was discontinued as of version 0.3.0 of this gem. If you're on Ruby 1.9.3, you'll want to install the gem like so:

gem "merch_calendar", "0.3.0"

Usage

For converting a date into a MerchWeek object.

merch_week = MerchCalendar::MerchWeek.from_date("2014-01-01", calendar: MerchCalendar::RetailCalendar.new)

merch_week.year                 # 2013 (the merch year associated with this date)
merch_week.month                # 12 (the julian month that the date falls in)
merch_week.week                 # 5 (the week number within the month)
merch_week.year_week            # 48 (the week number within the retail calendar year)
merch_week.quarter              # 4

merch_week.start_of_week        # <Date: 2013-12-29>
merch_week.end_of_week          # <Date: 2014-01-04>

merch_week.start_of_month       # <Date: 2013-12-01>
merch_week.end_of_month         # <Date: 2014-01-04>

merch_week.start_of_year        # <Date: 2013-02-03>
merch_week.end_of_year          # <Date: 2014-02-01>

merch_week.calendar             # <MerchCalendar::RetailCalendar> (the calendar we're using)
                                # if you don't initialize a calendar, it defaults to RetailCalendar

# Formatting
merch_week.to_s                 # "Dec W5"
merch_week.to_s(:short)         # "Dec W5"
merch_week.to_s(:long)          # "2013:48 Dec W5"
merch_week.to_s(:elasticsearch) # "2013-12w05"

Merch retail calendar

Retail calendars have their first month in February, and the last (12th) month is in January of the following year.

# This is asking "In the Merch year of 2014, what is the Gregorian calendar date of
# the start of the first month?"
retail_calendar = MerchCalendar::RetailCalendar.new

retail_calendar.start_of_month(2014, 1)
# => 2014-02-02

retail_calendar.start_of_month(2014, 12)
# => 2015-01-04

This table should describe the progression of dates:

N start_of_month(2014, N)
1 2014-02-02
2 2014-03-02
3 2014-04-06
4 2014-05-04
5 2014-06-01
6 2014-07-06
7 2014-08-03
8 2014-08-31
9 2014-10-05
10 2014-11-02
11 2014-11-30
12 2015-01-04

Other useful methods:

# 52 or 53 (depending on leap year)
retail_calendar.weeks_in_year(2016)
# => 52
retail_calendar.weeks_in_year(2017)
# => 53

# get the start date of a given merch week
retail_calendar.start_of_week(2017, 4, 1)
# => #<Date: 2017-04-30 ((2457874j,0s,0n),+0s,2299161j)>

# get the end date of a given merch week
retail_calendar.end_of_week(2017, 4, 1)
#=> #<Date: 2017-05-06 ((2457880j,0s,0n),+0s,2299161j)>

Stitch Fix Fiscal Year Calendars

Some companies, one of which being Stitch Fix, operate on a fiscal year calendar that instead starts in August rather than in February in a the traditional retail calendar. The MerchCalendar::StitchFixFiscalYearCalendar class allows you to easily translate Gregorian dates to a Stitch Fix Fiscal Year date.

fiscal_calendar = MerchCalendar::StitchFixFiscalYearCalendar.new

fiscal_calendar.weeks_in_year(2018)
# => 52
fiscal_calendar.weeks_in_year(2019)
# => 53

# get the start date of a given merch week
fiscal_calendar.start_of_week(2017, 1, 1)
# => #<Date: 2016-07-31 ((2457601j,0s,0n),+0s,2299161j)>

# get the end date of a given merch week
fiscal_calendar.end_of_week(2017, 4, 1)
#=> #<Date: 2017-05-06 ((2457880j,0s,0n),+0s,2299161j)>

Stitch Fix Fiscal Year Calendar in Relation to MerchWeek object

You can set MerchWeek object respond to the Stitch Fix Fiscal Calendar, by passing in StitchFixFiscalYearCalendar.new in the calendar parameter:

merch_week = MerchCalendar::MerchWeek.from_date("2018-07-02", calendar: MerchCalendar::StitchFixFiscalYearCalendar.new)

merch_week.year                 # 2018 (the merch year associated with this date)
merch_week.month                # 7 (the julian month that the date falls in)
merch_week.merch_month          # 12 (this fiscal month the date falls in)
merch_week.week                 # 1 (the week number within the month)
merch_week.year_week            # 49 (the week number within the retail calendar year)
merch_week.quarter              # 4

merch_week.start_of_week        # <Date: 2018-07-01>
merch_week.end_of_week          # <Date: 2018-07-07>

merch_week.start_of_month       # <Date: 2018-07-01>
merch_week.end_of_month         # <Date: 2018-07-28>

merch_week.start_of_year        # <Date: 2017-07-30>
merch_week.end_of_year          # <Date: 2018-07-28>

merch_week.calendar             # <MerchCalendar::StitchFixFiscalYearCalendar> (the calendar
                                # we're using)
                                # if you don't initialize a calendar, it defaults to RetailCalendar

# Formatting
merch_week.to_s                 # "Jul W1"
merch_week.to_s(:short)         # "Jul W1"
merch_week.to_s(:long)          # "2018:49 Jul W1"
merch_week.to_s(:elasticsearch) # "2018-07w01"

Documentation

You can view the documentation for this gem on RubyDoc.info.

License

MerchCalendar is released under the MIT License.

About

Calculations around the National Retail Federation's 4-5-4 calendar

Resources

License

Languages

You can’t perform that action at this time.