API Reference
Namespaces
Classes
Events
Global
Externals

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 with rules 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.

Important:

  • If the CIQ.ExtendedHours visualization and filtering add-on is enabled, only data within the defined market hours will be displayed on the chart even if more data is loaded.
  • Once a market definition is assigned to a chart, it will be used to roll up any data requested by the periodicity, which will result in any data outside the market hours to be combined with the prior candle.
    This may at times look like data is being filtered, but it is just being aggregated. To truly filter data, you must use the above add-on.

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. close time must always be later than open time. Use the proper market time zone (market_tz) to prevent hours from spanning across days.
  • market_tz : A string. Time zone in which the market operates. See CIQ.timeZoneMap to review a list of all ChartIQ supported time zones and instructions on how to add more.
  • hour_aligned: A boolean. If set to true, market opening and closing times will be forced to the exact start of the hour of time, ignoring any minutes, seconds or millisecond offsets.

    You should set this to false if your market opening and closing times are not aligned to the beginning to each hour. Otherwise, forcing them to do so causes the iterator to generate previous and next times that could prevent it from properly moving trough the market hours.

  • convertOnDaily : A boolean. By default, daily charts are not converted for time zone. Set this to true to convert for daily charts.
  • beginningDayOfWeek : Weekday number (0-6) to optionally override CIQ.Market prototype setting of same name.
  • normal_daily_open: A string defining a time in HH:mm format. Set this to specify the normal open time for a market.
  • normal_daily_close: A string defining a time in HH:mm format. Set this to specify the normal close time for a market.
  • minimum_session_length: The minimum interval of time used to test for a market session open. See CIQ.Market#minimumSessionLength.

Example:

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

Instructions for creating Market Definitions:

  • An empty market definition ( {} ) assumes the market is always open.

  • Once a definition has rules in it, the market will be assumed open only for those defined rules. The absence of a rule indicates the market is closed for that timeframe.

  • Market's time rules are specified in the market's local time zone.

  • Seconds are not considered for open or close times, but are okay for intra-day data.

  • Rules are processed top to bottom.

  • Rules can be defined for both primary and secondary market sessions.

  • Rules for the market's primary session do not have a name parameter and are enabled by default.

  • Rules for the market's primary session are mandatory.

  • Rules for secondary market sessions, such as pre-market or post-market trading hours sessions, require a name parameter.

  • All secondary market session are disabled by default.

      This is a rule for a 'pre' market session:
      	`{"dayofweek": 1, "open": "08:00", "close": "09:30", name: "pre"}`
    
  • To enable or disable secondary market session rules by session name, use CIQ.Market#enableSession and CIQ.Market#disableSession.

  • Important: Enabling/Disabling market sessions will not automatically filter-out data from the chart, but simply adjust the market iterators so the x-axis can be displayed accordingly in the absence of data for the excluded sessions.

  • Data filtering can be done:

  • 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
    
    • close time must always be later than open time.
    • Use the proper market time zone (market_tz) to prevent hours from spanning across days.
  • 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

Members


beginningDayOfWeek :number

The day on which to begin a week: 0 = Sunday, 1 = Monday, ..., 6 = Saturday.

This is a global setting, but can be overridden with a market-specific setting in the market definition.

Type:
  • number
Since:
  • 8.2.0

Default Value:
  • 0
Example
stxx.chart.market.beginningDayOfWeek = 5;  // Start week on Friday.

minimumSessionLength :number

The shortest session length for the market. The higher this number, the more performant iterations through the times will be. However, too high a number may result in skipping over shorter market sessions. Make sure this number is smaller than the number of minutes in the shortest session for this market.

Type:
  • number
Since:
  • 8.4.0

Default Value:
  • 30
Example
stxx.chart.market.minimumSessionLength = 1;  // The lowest possible setting

sessions :array

An array of objects containing information about the current market's extended sessions. Each element has a name prop (for the name of the session) and an enabled prop. See CIQ.ExtendedHours for more information on extended sessions.

Type:
  • array
Example
marketSessions=stxx.chart.market.sessions

Methods


_convertFromMarketTZ(dt [, tz])

Converts to the given timezone from the market's native time zone. If no market zone is present, the date will be returned un changed.

Parameters:
Name Type Argument Description
dt date

JavaScript Date

tz string <optional>

timezoneJS timezone, or null to indicate browser localtime/UTC (displayZone)

Returns:

A JavaScript Date offset by the timezone change

Type
date

_convertToMarketTZ(dt [, tz])

Converts from the given timezone into the market's native time zone If no market zone is present, the date will be returned unchanged.

Parameters:
Name Type Argument Description
dt date

JavaScript Date

tz string <optional>

timezoneJS timezone, or null to indicate browser localtime/UTC (dataZone)

Returns:

A JavaScript Date offset by the timezone change

Type
date

_tzDifferenceMillis(date, src_tz_str, target_tz_str)

Get the difference in milliseconds between two time zones. May be positive or negative depending on the time zones. The purpose is to shift the source time zone some number of milliseconds to the target timezone. For example shifting a data feed from UTC to Eastern time. Or shifting Eastern time to Mountain time for display purposes. Note that it is important to pass the source and the target in the correct order. The algorithm does source - target. This will calculate the correct offset positive or negative.

Parameters:
Name Type Description
date date

A date object. Could be any date object the JavaScript one or for example the timezone.js one. Must implement getTime() and getTimezoneOffset()

src_tz_str string

The source time zone. For example the data feed

target_tz_str string

The target time zone for example the market.

Returns:

The number of milliseconds difference between the time zones.

Type
number

_wasClosed(testDate)

Convenience function for unit testing.

Parameters:
Name Type Description
testDate date

A date

Returns:

True if the market was closed on the given date

Type
boolean

_wasOpen(testDate)

Convenience function for unit testing.

Parameters:
Name Type Description
testDate date

A date

Returns:

True if the market was open on the given date

Type
boolean

disableSession(session_name [, inverted])

Toggle on/off a market session by name.

  • Important: Enabling/Disabling market sessions will not automatically filter-out data from the chart, but simply adjust the market iterators so the x-axis can be displayed accordingly in the absence of data for the excluded sessions.
  • Data filtering can be done:
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


enableAllAvailableSessions()

Parses the market definition for a list of market names, and enables each one-by-one, see CIQ.Market#enableSession and CIQ.Market#disableSession.

  • Important: Enabling/Disabling market sessions will not automatically filter-out data from the chart, but simply adjust the market iterators so the x-axis can be displayed accordingly in the absence of data for the excluded sessions.
Since:
  • 6.0.0


enableSession(session_name)

Enable a market session by name. See CIQ.Market#disableSession for full usage details.

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

getNormalClose()

Gets the normal close time for the current market; that is, the time the market typically closes. In cases where there are two trading sessions, the second is used.

Since:
  • 8.1.0

Returns:

The normal close in HH:mm format.

Type
string

getNormalOpen()

Gets the normal open time for the current market; that is, the time the market typically opens. In cases where there are two trading sessions, the first is used.

Since:
  • 8.1.0

Returns:

The normal open in HH:mm format.

Type
string

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

getSession(date [, inZone])

Return the session name for a date. If the name is defined and if the date lands in a session that is open. Otherwise return null.

Parameters:
Name Type Argument Description
date date

A date object

inZone string <optional>

Timezone of incoming date - If no market zone is present it will assume browser time.

Returns:

String or null

Type
object

getSessionNames()

Returns an array of objects containing a list of sessions and whether or not they are enabled

Since:
  • 6.0.0

Returns:

String array of market session names, and corresponding status (e.g. [{ name: 'pre', enabled: false } { name: 'post', enabled: true }])

Type
array

isFirstMarketDayOfMonth(date)

Checks if a supplied date is the first market day of the month.

Parameters:
Name Type Description
date date

A date

Since:
  • 8.4.0

Returns:

True if first market day, false otherwise.

Type
boolean

isFirstMarketDayOfWeek(date)

Checks if a supplied date is the first market day of the week.

Parameters:
Name Type Description
date date

A date

Since:
  • 8.4.0

Returns:

True if first market day, false otherwise.

Type
boolean

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:

An object with the open market session's details, if it is a market day. Or null if it is not a market day.

Type
object

isMarketDay()

Checks if today it is a market day.

Since:
  • 04-2016-08

Returns:

An object with the open market session's details, if it is a market day. Or null if it is not a market day.

Type
object

isOpen()

Checks if the market is currently open.

Since:
  • 04-2016-08

Returns:

An object with the open market session's details, if the market is open right now. Or null if no sessions are currently open.

Type
object

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 number <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 time zone 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 time zone if none set. - If no market zone is present it will assume browser time.

outZone string <optional>

A valid time zone from the timeZoneData.js library. This should represent the time zone for the returned dates. Defaults to browser time zone 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.chart.market.newIterator(
			{
				'begin': now,
                'interval': stxx.layout.interval,
                'periodicity': stxx.layout.periodicity,
                'timeUnit': stxx.layout.timeUnit,
                'inZone': stxx.dataZone,
                'outZone': stxx.displayZone
			}
	);

tradingDays()

An array of days on which trading occurs. This function uses the current market definitions to create a list of trading days for the week. If there are no rules set in the market definition, then all days of the week are returned.

If there are no rules set in the market definition, all days of the week are returned.

Since:
  • 8.4.0

Returns:

Sorted array of days on which trading occurs.

Type
Array.<number>

_createTimeSegments(market)

Static function that reads the json rules in the market definition and creates in memory time segments that are used later to match market dates.

Parameters:
Name Type Description
market object

An instance of a market.