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 thanopen
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 totrue
, 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 generateprevious
andnext
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 inHH:mm
format. Set this to specify the normal open time for a market.normal_daily_close
: A string defining a time inHH: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:
- Manually by requesting pertinent data from your feed and calling CIQ.ChartEngine#loadChart
- Automatically by using the CIQ.ExtendedHours visualization and filtering add-on.
-
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
andclose
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 thanopen
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
Namespaces
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:
- Manually by requesting pertinent data from your feed and calling CIQ.ChartEngine#loadChart
- Automatically by using the CIQ.ExtendedHours visualization and filtering add-on.
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 ofdate
, 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 ofdate
, 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 thedisplayZone
ordataZone
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 beinZone
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 orparms.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.