Class: Market

CIQ. Market


new Market( [market_definition])

The market class is what the chart uses to to manage market hours for the different exchanges. It uses Market Definitions to decide when the market is open or closed. Although you can construct many market classes with different definitions to be used in your functions, only one market definition can be attached to the chart at any given time. Once a market is defined, an iterator can be created to traverse through time, taking into account the market hours. Additionally, a variety of convenience functions can be used to check the market status, such as CIQ.Market#isOpen or CIQ.Market#isMarketDay.

A chart will operate 24x7, unless a market definition is assigned to it. See CIQ.ChartEngine#setMarket and CIQ.ChartEngine#setMarketFactory for instructions on how to assign a market definition to a chart. The chart also provides convenience functions that allows you to traverse through time at the current chart periodicity without having to explicitly create a new iterator. See CIQ.ChartEngine#getNextInterval and CIQ.ChartEngine#standardMarketIterator for details.

It is also important to note that only data within the defined market hours will be displayed on the chart even if more data is loaded.

Market Definitions are JavaScript objects which must contain the following elements:

  • name : A string. Name of the market for which the rules are for.
  • rules : An array. The rules indicating the times the market is open or closed.
  • market_tz : A string. Time zone in which the market operates. A valid timezone from the timeZoneData.js library.
  • hour_aligned: A boolean. If set to true, market opening and closing times will be set to the exact start of the hour of time, ignoring any minutes, seconds or millisecond offsets.
  • convertOnDaily : A boolean. By default, daily charts are not converted for timezone. Set this to true to convert for daily charts.

Example:

    {
        name: "SAMPLE-MARKET",
        market_tz: "America/Chicago",
        hour_aligned: true,
        rules: [
                {"dayofweek": 1, "open": "09:00", "close": "17:00"}
        ]
    };

Instructions for creating Market Definitions:

  • By default a market assumes that it is always open unless otherwise defined.
  • Market rule times are specified in the market's local timezone.
  • Seconds are not considered for open or close times, but are okay for intra day data.
  • Rules are processed top to bottom.
  • Default market rules do not have a name parameter and are enabled by default.
  • Non-default market rules require a name parameter included.
  • All non-default market rules are disabled by default. To enable or disable non-default market rules by session name, use CIQ.Market#enableSession and CIQ.Market#disableSession. If using template-advanced.html, consider using CIQ.ExtendedHours.

      This is a rule for a 'pre' market session:
          `{"dayofweek": 1, "open": "08:00", "close": "09:30", name: "pre"}`
  • First, the dayofweek wild card rules are processed. As soon as a rule is matched, processing breaks.

      This rule says the market is open every Monday from 9:30 to 16:00:
          `{"dayofweek": 1, "open": "09:30", "close": "16:00"}`
  • After the dayofweek rules are processed all of the extra rules are processed.

  • Multiple open and close times can be set for the same day of week. To indicate the market is closed during lunch, for example.

          ```
          {"dayofweek": 1, "open": "09:00", "close": "12:00"}, // mon
          {"dayofweek": 1, "open": "13:00", "close": "17:00"}  // mon
          ```
  • Wildcard rules should be placed first and more specific rules should be placed later.

      This rule is a wildcard rule for Christmas. If Christmas is on Monday, the
      first set of rules will evaluate to true because the dayofweek rule for day
      one will match. Then this rule will match if the date is the 25th of
      December in any year.  Because open is 00:00 and close is 00:00, it will evaluate to false:
          `{"date": "*-12-25", "open": "00:00", "close": "00:00"}`
  • After wildcard exceptions, any specific day and time can be matched.

      This rule says closed on this day only. Note that open and closed attributes
      can be omitted to save typing if the market is closed the entire day:
          `{"date": "2016-01-18"} //Martin Luther King day.`
    
      This rules says closed on 12-26:
          `{"date": "2016-12-26"}, //Observed Christmas in 2016`
    
      This rule says partial session
          `{"date": "2015-12-24", "open": "9:30", "close": "13:00"} //Christmas eve`

See example section for a compete NYSE definition.

Once defined, it can be used to create a new market instance.

Example:

    var thisMarket = new CIQ.Market(marketDefinition);

If no definition is provided, the market will operate 24x7.

Example:

new CIQ.Market();
Parameters:
Name Type Argument Description
market_definition Object <optional>

A json object that contains the rules for some market. If not defined default market is always open.

Since:

  • 04-2016-08
    06-2016-02 - You can now specify times for different market sessions ('pre',post', etc) to be used with the sessions visualization tools. See CIQ.ExtendedHours.
Example
CIQ.Market.NYSE = {
			"name": "NYSE",
			"market_tz": "America/New_York",
			"hour_aligned": false,
			"rules": [
				//First open up the regular trading times
				//Note that sat and sun (in this example) are always closed because
				//everything is closed by default and we didn't explicitly open
				//them.
				{"dayofweek": 1, "open": "09:30", "close": "16:00"}, //mon
				{"dayofweek": 2, "open": "09:30", "close": "16:00"},
				{"dayofweek": 3, "open": "09:30", "close": "16:00"},
				{"dayofweek": 4, "open": "09:30", "close": "16:00"},
				{"dayofweek": 5, "open": "09:30", "close": "16:00"}, //fri

				//After Hours premarket
				{"dayofweek": 1, "open": "08:00", "close": "09:30", name: "pre"}, //mon
				{"dayofweek": 2, "open": "08:00", "close": "09:30", name: "pre"},
				{"dayofweek": 3, "open": "08:00", "close": "09:30", name: "pre"},
				{"dayofweek": 4, "open": "08:00", "close": "09:30", name: "pre"},
				{"dayofweek": 5, "open": "08:00", "close": "09:30", name: "pre"}, //fri

				//After Hours post
				{"dayofweek": 1, "open": "16:00", "close": "20:00", name: "post"}, //mon
				{"dayofweek": 2, "open": "16:00", "close": "20:00", name: "post"},
				{"dayofweek": 3, "open": "16:00", "close": "20:00", name: "post"},
				{"dayofweek": 4, "open": "16:00", "close": "20:00", name: "post"},
				{"dayofweek": 5, "open": "16:00", "close": "20:00", name: "post"}, //fri

				//Now Monday thru Friday is open. Close any exceptions

				//always closed on Christmas
				{"date": "*-12-25", "open": "00:00", "close": "00:00"},

				//always closed on 4th of July
				{"date": "*-07-04", "open": "00:00", "close": "00:00"},

				//always close on new years day
				{"date": "*-01-01", "open": "00:00", "close": "00:00"},

				//Some holidays are observed on different days each year or if
				//the day falls on a weekend. Each of those rules must be specified.
				{"date": "2012-01-02", "open": "00:00", "close": "00:00"},

				//As a special case if no open and close attributes are set they
				//will be assumed "00:00" and "00:00" respectively
				{"date": "2017-01-02"},

				{"date": "2016-01-18"},
				{"date": "2016-02-15"},
				{"date": "2016-03-25"},
				{"date": "2016-05-30"},
				{"date": "2016-09-05"},
				{"date": "2016-11-24"},
				{"date": "2016-11-25", "open": "8:00", "close": "9:30", name: "pre"},
				{"date": "2016-11-25", "open": "9:30", "close": "13:00"},
				{"date": "2016-12-26"},

				{"date": "2015-01-19"},
				{"date": "2015-02-16"},
				{"date": "2015-04-03"},
				{"date": "2015-05-25"},
				{"date": "2015-07-03"},
				{"date": "2015-09-07"},
				{"date": "2015-11-26"},
				{"date": "2015-11-27", "open": "8:00", "close": "9:30", name: "pre"},
				{"date": "2015-11-27", "open": "9:30", "close": "13:00"},
				{"date": "2015-12-24", "open": "8:00", "close": "9:30", name: "pre"},
				{"date": "2015-12-24", "open": "9:30", "close": "13:00"},

				{"date": "2014-01-20"},
				{"date": "2014-02-17"},
				{"date": "2014-04-18"},
				{"date": "2014-05-26"},
				{"date": "2014-09-01"},
				{"date": "2014-11-27"},
				{"date": "2014-07-03", "open": "8:00", "close": "9:30", name: "pre"},
				{"date": "2014-07-03", "open": "9:30", "close": "13:00"},
				{"date": "2014-11-28", "open": "8:00", "close": "9:30", name: "pre"},
				{"date": "2014-11-28", "open": "9:30", "close": "13:00"},
				{"date": "2014-12-24", "open": "8:00", "close": "9:30", name: "pre"},
				{"date": "2014-12-24", "open": "9:30", "close": "13:00"},

				{"date": "2013-01-21"},
				{"date": "2013-02-18"},
				{"date": "2013-03-29"},
				{"date": "2013-05-27"},
				{"date": "2013-09-02"},
				{"date": "2013-11-28"},
				{"date": "2013-07-03", "open": "8:00", "close": "9:30", name: "pre"},
				{"date": "2013-07-03", "open": "9:30", "close": "13:00"},
				{"date": "2013-11-29", "open": "8:00", "close": "9:30", name: "pre"},
				{"date": "2013-11-29", "open": "9:30", "close": "13:00"},
				{"date": "2013-12-24", "open": "8:00", "close": "9:30", name: "pre"},
				{"date": "2013-12-24", "open": "9:30", "close": "13:00"},

				{"date": "2012-01-16"},
				{"date": "2012-02-20"},
				{"date": "2012-04-06"},
				{"date": "2012-05-28"},
				{"date": "2012-09-03"},
				{"date": "2012-10-29"},
				{"date": "2012-10-30"},
				{"date": "2012-11-22"},
				{"date": "2012-07-03", "open": "8:00", "close": "9:30", name: "pre"},
				{"date": "2012-07-03", "open": "9:30", "close": "13:00"},
				{"date": "2012-11-23", "open": "8:00", "close": "9:30", name: "pre"},
				{"date": "2012-11-23", "open": "9:30", "close": "13:00"},
				{"date": "2012-12-24", "open": "8:00", "close": "9:30", name: "pre"},
				{"date": "2012-12-24", "open": "9:30", "close": "13:00"}
			]
		};

Classes

Iterator

Namespaces

Symbology

Methods


disableSession(session_name [, inverted])

Toggle on/off a market session by name.

Parameters:
Name Type Argument Description
session_name string

A session name matching a valid name present in the market definition.

inverted Object <optional>

Any true value (true, non-zero value or string) passed here will enable the session, otherwise the session will be disabled.

Since:
  • 06-2016-02

enableSession(session_name)

Enable a market session by name. See CIQ.Market#disableSession

Parameters:
Name Type Description
session_name string

A session name

Since:
  • 06-2016-02

getClose( [date] [, session_name] [, inZone] [, outZone])

Get the close date/time for the trading day or specific session.

Parameters:
Name Type Argument Default Description
date date <optional>
now

date The date on which to check.

session_name string <optional>

Specific market session. If session_name is not passed in, the first close time of the day will be returned, depending on the sessions that are enabled. If a session name is passed in, then not only does the market session need to be open on the day of date, but also within the time of the specified session. Otherwise, null will be returned. Pass in "" to specify only the default session when other session are also active.

inZone string <optional>

Optional datazone to translate from - If no market zone is present it will assume browser time.

outZone string <optional>

Optional datazone to translate to - If no market zone is present it will assume browser time.

Since:
  • 05-2016-10
Returns:

Close date/time for the trading session or null if the market is closed for the given date.

Type
date

getNextClose( [date] [, inZone] [, outZone])

Get the close time for the current market session, or if the market is closed, the close time for the next market session.

Parameters:
Name Type Argument Default Description
date date <optional>
now

date The date on which to check.

inZone string <optional>

Optional datazone to translate from - If no market zone is present it will assume browser time.

outZone string <optional>

Optional datazone to translate to - If no market zone is present it will assume browser time.

Since:
  • 05-2016-10
Returns:

A date set to the close time of the next open market session.

Type
date

getNextOpen( [date] [, inZone] [, outZone])

Get the next market session open time. If the requested date is the opening time for the session, then it will iterate to opening time for the next market session.

Parameters:
Name Type Argument Default Description
date date <optional>
now

date An The date on which to check.

inZone string <optional>

Optional datazone to translate from - If no market zone is present it will assume browser time.

outZone string <optional>

Optional datazone to translate to - If no market zone is present it will assume browser time.

Since:
  • 05-2016-10
Returns:

A date aligned to the open time of the next open session. If no rules are defined, it will return null.

Type
date

getOpen( [date] [, session_name] [, inZone] [, outZone])

Get the open date/time for a market day or specific session.

Parameters:
Name Type Argument Default Description
date date <optional>
now

date The date on which to check.

session_name string <optional>

Specific market session. If session_name is not passed in, the first open time of the day will be returned, depending on the sessions that are enabled. If a session name is passed in, then not only does the market session need to be open on the day of date, but also within the time of the specified session. Otherwise, null will be returned. Pass in "" to specify only the default session when other session are also active.

inZone string <optional>

Optional datazone to translate from - If no market zone is present it will assume browser time.

outZone string <optional>

Optional datazone to translate to - If no market zone is present it will assume browser time.

Since:
  • 05-2016-10
Returns:

A date time for the open of a session or null if the market is closed for the given date or there are no market rules to check.

Type
date

getPreviousClose( [date] [, inZone] [, outZone])

Get the previous session close time. If the date lands exactly on the close time for a session then it will still seek to the previous market session's close.

Parameters:
Name Type Argument Default Description
date date <optional>
now

date The date on which to check.

inZone string <optional>

Optional datazone to translate from - If no market zone is present it will assume browser time.

outZone string <optional>

Optional datazone to translate to - If no market zone is present it will assume browser time.

Since:
  • 05-2016-10
Returns:

A date aligned to the previous close date/time of a session. If no rules are defined, it will return null.

Type
date

getPreviousOpen( [date] [, inZone] [, outZone])

Get the previous session open time. If the date lands exactly on the open time for a session then it will still seek to the previous market session's open.

Parameters:
Name Type Argument Default Description
date date <optional>
now

date An The date on which to check.

inZone string <optional>

Optional datazone to translate from - If no market zone is present it will assume browser time.

outZone string <optional>

Optional datazone to translate to - If no market zone is present it will assume browser time.

Since:
  • 05-2016-10
Returns:

A date aligned to previous open date/time of a session. If no rules are defined, it will return null.

Type
date

isHourAligned()

Since:
  • 04-2016-08
Returns:

true if this market is hour aligned.

Type
boolean

isMarketDate(date)

Checks if a supplied date is a market day. Only the date is examined; hours, minutes, seconds are ignored

Parameters:
Name Type Description
date date

A date

Since:
  • 04-2016-08
Returns:

true if it is a market day.

Type
boolean

isMarketDay()

Checks if today it is a market day.

Since:
  • 04-2016-08
Returns:

true if it is a market day.

Type
boolean

isOpen()

Checks if the market is currently open.

Since:
  • 04-2016-08
Returns:

true if the market is open right now.

Type
boolean

marketZoneNow()

Since:
  • 04-2016-08
Returns:

Current time in the market zone

Type
date

newIterator(parms)

Creates iterators for the associated Market to traverse through time taking into account market hours. An iterator instance can go forward or backward in time any arbitrary amount. However, the internal state cannot be changed once it is constructed. A new iterator should be constructed whenever one of the parameters changes. For example, if the interval changes a new iterator will need to be built. If the displayZone or dataZone changes on the market, new iterators will also need to be constructed.

See CIQ.Market.Iterator for all available methods.

See the following convenience functions: CIQ.ChartEngine#getNextInterval and CIQ.ChartEngine#standardMarketIterator

Parameters:
Name Type Description
parms object

Parameters used to initialize the Market object.

Properties
Name Type Argument Description
interval string <optional>

A valid interval as required by CIQ.ChartEngine#setPeriodicity. Default is 1 (minute).

periodicity Integer <optional>

A valid periodicity as required by CIQ.ChartEngine#setPeriodicity. Default is 1.

timeUnit string <optional>

A valid timeUnit as required by CIQ.ChartEngine#setPeriodicity. Default is "minute"

begin Date <optional>

The date to set as the start date for this iterator instance. Default is now. Will be assumed to be inZone if one set.

inZone string <optional>

A valid timezone from the timeZoneData.js library. This should represent the time zone for any input dates such as parms.begin in this function or parms.end in CIQ.Market.Iterator#futureTick. Defaults to browser timezone if none set. - If no market zone is present it will assume browser time.

outZone string <optional>

A valid timezone from the timeZoneData.js library. This should represent the time zone for the returned dates. Defaults to browser timezone if none set. - If no market zone is present it will assume browser time.

Since:
  • 04-2016-08
Returns:

A new iterator.

Type
object
Example
var iter = stxx.market.newIterator(
				{
					'begin': now,
	                'interval': stxx.layout.interval,
	                'periodicity': stxx.layout.periodicity,
	                'timeUnit': stxx.layout.timeUnit,
	                'inZone': stxx.dataZone,
	                'outZone': stxx.displayZone
				}
		);