TimeSeriesClient: TimeSeriesClient
In DatastreamR: Datastream API
TimeSeriesClient R Documentation
TimeSeriesClient
Description
This is the client class that manages the connection to the API server on your behalf.
It allows you to query for all your timeseries and to create/modify new timeseries.
Details
Methods Supported
GetAllItems : Allows you to query for all the current timeseries available for your use.
GetItem : Allows you to download the details of a specific timeseries item.
GetTimeseriesDateRange : Allows you to determine the supported timeseries dates between supplied start and
end dates at a specified frequency.
CreateItem : Allows you to create a new timeseries item with up to 130 years of daily data.
UpdateItem : Allows you to update an existing timeseries.
DeleteItem : Allows you to delete an existing timeseries.
Value
TimeSeriesClient object
Super class
DatastreamR::DSConnect -> TimeSeriesClient
Public fields
useNaNforNotANumberIf Enabled, NaN is appears in output response instead of NULL
TimeseriesResponseTypeResponse type
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Inherited methods
Method new()
User details can be supplied from a config file or passed directly as parameters
in the constructor of the derived user object type class.
(See the DSConnect superclass for a description of the connection parameters required)
Usage
TimeSeriesClient$new(
config = NULL,
username = NULL,
password = NULL,
proxies = NULL,
sslCer = NULL
)
Arguments
configConfiguration File path
usernameYour Datastream Id
passwordYour Password
proxiesProxies if any
sslCerPath to CA bundle certificates file
Details
Timeseries Properties:
useNaNforNotANumber : Non-trading days are stored as double NaNs on Datastream, JSON protocol permits NaNs as valid numbers.
Thus, all the NULLs in the converted to NaNs in the JSON requests. Responses contain the NULLs, But this should be converted
to Nans for Plotting purposes. If you want to receive NaN float values, set useNaNforNotANumber to TRUE, any NULLs in the returned
array of float values will be converted to NaNs.
Returns
TimeSeriesClient object
Method .checkValidTimeseriesId()
A helper method to check the timeseries Id
Usage
TimeSeriesClient$.checkValidTimeseriesId(inputId)
Arguments
inputId: Timeseries Id
Returns
NULL if Timeseries id is valid else error string
Method .checkTimeSeriesReqValidity()
A helper method to check some of the mandatory fields of timeseries for its validity
Usage
TimeSeriesClient$.checkTimeSeriesReqValidity(tsItem)
Arguments
tsItemTimeseries Item
Returns
NULL if Timeseries id is valid else error string
Method .checkKeyTimeseriesProperties()
A helper method to check the Timeseries properties
Usage
TimeSeriesClient$.checkKeyTimeseriesProperties(tsItem)
Arguments
tsItemTimeseries Item
Returns
NULL if Timeseries id is valid else error string
Method .asGetAllResponse()
A helper method which converts the JSON response to GetAllResponse Object
Usage
TimeSeriesClient$.asGetAllResponse(jsonDict)
Arguments
jsonDictJSON Response
Returns
DSUserObjectGetAllResponse object
Method .asGetResponse()
A helper method which converts the JSON response to GetResponse Object
Usage
TimeSeriesClient$.asGetResponse(jsonDict)
Arguments
jsonDictJSON Response
Returns
DSUserObjectResponse object
Method .jsonRequestEncoder()
A helper method that reformats the raw request to JSON format
Usage
TimeSeriesClient$.jsonRequestEncoder(request)
Arguments
requestRaw request
Returns
return JSON formatted list
Method .jsonResponseDecoder()
A helper method that converts JSON Response to a given class response type
Usage
TimeSeriesClient$.jsonResponseDecoder(jsonResp, responseType)
Arguments
jsonRespJSON Response
responseTypeGetResponse or GetAllResponse type
Returns
return DSUserObjectGetAllResponse or DSUserObjectGetResponse object
Method GetAllItems()
This method returns all the current timeseries you can use in Datastream queries.
Usage
TimeSeriesClient$GetAllItems()
Returns
DSUserObjectGetAllResponse object
Method GetItem()
GetItem returns the details for an individual timeseries.
Usage
TimeSeriesClient$GetItem(itemId)
Arguments
itemId: a valid timeseries Id.
Returns
DSUserObjectResponse object
Method CreateItem()
This method attempts to create the given DSTimeSeriesRequestObject via the API service
Usage
TimeSeriesClient$CreateItem(newItem, overWrite = FALSE, skipItemReturn = FALSE)
Arguments
newItemA DSTimeSeriesRequestObject containing the data used for creating the Timeseries.
overWriteIf the given Timeseries Id already exists on the system, the create call will be rejected.
Set overWrite = True to overwrite the existing item with new Timeseries.
skipItemReturn: Upon successful creation of an item, the server requests the new item from the mainframe
and returns it in the response object. For faster processing, set skipItemReturn = True to skip returning the
object in the response
Returns
DSUserObjectResponse object
Method UpdateItem()
This method attempts to modify a timeseries item using the given DSTimeSeriesRequestObject via
the API service
Usage
TimeSeriesClient$UpdateItem(item, skipItemReturn = FALSE)
Arguments
itemA DSTimeSeriesRequestObject containing the data used for creating the Timeseries.
skipItemReturnUpon successful creation of an item, the server requests the new item from the
mainframe and returns it in the response object. For faster processing, set skipItemReturn = True to
skip returning the object in the response.
Returns
DSUserObjectResponse object
Method DeleteItem()
DeleteItem allows you to delete an existing timeseries
Usage
TimeSeriesClient$DeleteItem(itemId)
Arguments
itemIda valid timeseries Id.
Returns
No return value
Method GetTimeseriesDateRange()
This method allows you to determine the supported dates between supplied start and end dates
at a specified frequency.
Usage
TimeSeriesClient$GetTimeseriesDateRange(
startDate,
endDate,
frequency = DSUserObjectFrequency$Daily
)
Arguments
startDateA date specifying the beginning of the date range
endDateA date specifying the end of the date range
frequencyA DSUserObjectFrequency enumeration defining if the frequency should be daily,
weekly, monthly, quarterly or yearly.
Returns
DSTimeSeriesDateRangeResponse object
Method clone()
The objects of this class are cloneable with this method.
Usage
TimeSeriesClient$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Note
: You need a Datastream ID which is permissioned to access the Datastream APIs. In addition, this ID also needs
to be permissioned to access the custom user object service. Attempting to access this service without these permissions
will result in a permission denied error response.
: For Daily and Weekly frequencies, if the supplied startDate falls on a weekend or a trading holiday, the returned
starting date will be the first trading day before the given start date. If the supplied endDate falls on a weekend or a
trading holiday, the returned final date will be the last trading day before the given end date. For Weekly frequencies,
this will be the last date which matches the day of the week for the first returned start date.
For Monthly, Quarterly and Yearly frequencies, the returned dates are always the 1st day of each month, quarter or year.
The returned start and end dates are always the 1st days of the requested month, quarter or year that the given start
and end dates fall within.
: For Daily and Weekly frequencies, if the supplied startDate falls on a weekend or a trading holiday, the returned
starting date will be the first trading day before the given start date. If the supplied endDate falls on a weekend or a
trading holiday, the returned final date will be the last trading day before the given end date. For Weekly frequencies,
this will be the last date which matches the day of the week for the first returned start date.
For Monthly, Quarterly and Yearly frequencies, the returned dates are always the 1st day of each month, quarter or year.
The returned start and end dates are always the 1st days of the requested month, quarter or year that the given start
and end dates fall within.
Examples
{
# first logon with your credentials.
# Creating a TimeSeriesClient instance with your credentials
# automatically logs on for you.
timeseriesClient = TimeSeriesClient$new(NULL, 'YourID', 'YourPwd')
# query for all your current timeseries items
itemsResp = timeseriesClient$GetAllItems()
if (!is.null(itemsResp))
{
if (itemsResp$ResponseStatus != DSUserObjectResponseStatus$UserObjectSuccess)
{
# Your Datastream Id might not be permissioned for managing
# user created items on this API
print(paste('GetAllItems failed with error ',
names(DSUserObjectResponseStatus)[[itemsResp$ResponseStatus + 1]],
': ', itemsResp$ErrorMessage))
}
else if (!is.null(itemsResp$UserObjects) & itemsResp$UserObjectsCount > 0)
{
# You do have access to some timeseries
# Here we just put the timeseries details into a dataframe and list them
print(paste('GetAllItems returned', itemsResp$UserObjectsCount, 'timeseries items.'))
df = data.frame()
for (tsItem in itemsResp$UserObjects)
{
if (!is.null(tsItem))
{
rowdata = list(Id = tsItem$Id,
LastModified = tsItem$LastModified,
StartDate = ifelse(!is.null(tsItem$DateInfo),as.character(tsItem$DateInfo$StartDate),""),
EndDate =ifelse(!is.null(tsItem$DateInfo),as.character(tsItem$DateInfo$EndDate), ""),
Frequency = ifelse(!is.null(tsItem$DateInfo), tsItem$DateInfo$Frequency, 0),
NoOfValues = ifelse(!is.null(tsItem$DateRange), tsItem$DateRange$ValuesCount , 0),
Desc = tsItem$Description)
df = rbind(df, rowdata)
}
}
print(df)
}
}
#Example to show how to GetItem
# query for a specific timeseries
tsName = 'TSZZZ001'
tsResponse = timeseriesClient$GetItem(tsName)
# You may want to put the timeseries request response handling into a common function.
if (!is.null(tsResponse))
{
# Any request dealing with a single user created item returns a DSUserObjectResponse.
# This has ResponseStatus property that indicates success or failure
if (tsResponse$ResponseStatus != DSUserObjectResponseStatus$UserObjectSuccess)
{
print(paste('Request failed for timeseries', tsName, 'with error',
names(DSUserObjectResponseStatus)[[tsResponse$ResponseStatus+1]],
':', tsResponse$ErrorMessage))
}
else if (!is.null(tsResponse$UserObject))
{
# The timeseries item won't be returned if you set SkipItem true
# in CreateItem or UpdateItem
# Here we simply display the timeseries data using a dataframe.
tsItem = tsResponse$UserObject
metadata = c (Id = tsItem$Id,
Desc = tsItem$Description,
LastModified = as.character(tsItem$LastModified),
StartDate = ifelse (!is.null(tsItem$DateInfo), as.character(tsItem$DateInfo$StartDate), NULL),
EndDate = ifelse(!is.null(tsItem$DateInfo),as.character(tsItem$DateInfo$EndDate), NULL),
Frequency = ifelse(!is.null(tsItem$DateInfo),
names(DSUserObjectFrequency)[[tsItem$DateInfo$Frequency + 1]], NULL),
NoOfValues = ifelse(!is.null(tsItem$DateRange), tsItem$DateRange$ValuesCount , 0))
df = data.frame(metadata)
print(df)
if (!is.null(tsItem$DateRange))
{
df = data.frame(Dates = sapply(tsItem$DateRange$Dates,
FUN = function(x){ return (as.character(x)) }),
Values = sapply(tsItem$DateRange$Values,
FUN = function(x){ ifelse (is.null(x),
return (NA_character_ ), return (x) )} ))
# Values if NULL, is printed as <NA> because, while
# convertind list to vector either by using as.vector or sapply,
# the NULL values in the list are deleted. and thus there will
# be mismatch in no of rows and cannot be put in a dataframe
print(df)
}
}
}
}
DatastreamR documentation built on May 29, 2024, 12:05 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| TimeSeriesClient | R Documentation |
TimeSeriesClient
Description
This is the client class that manages the connection to the API server on your behalf. It allows you to query for all your timeseries and to create/modify new timeseries.
Details
Methods Supported
GetAllItems : Allows you to query for all the current timeseries available for your use.
GetItem : Allows you to download the details of a specific timeseries item.
GetTimeseriesDateRange : Allows you to determine the supported timeseries dates between supplied start and
end dates at a specified frequency.
CreateItem : Allows you to create a new timeseries item with up to 130 years of daily data.
UpdateItem : Allows you to update an existing timeseries.
DeleteItem : Allows you to delete an existing timeseries.
Value
TimeSeriesClient object
Super class
DatastreamR::DSConnect -> TimeSeriesClient
Public fields
useNaNforNotANumberIf Enabled, NaN is appears in output response instead of NULL
TimeseriesResponseTypeResponse type
Methods
Public methods
Inherited methods
Method new()
User details can be supplied from a config file or passed directly as parameters in the constructor of the derived user object type class. (See the DSConnect superclass for a description of the connection parameters required)
Usage
TimeSeriesClient$new( config = NULL, username = NULL, password = NULL, proxies = NULL, sslCer = NULL )
Arguments
configConfiguration File path
usernameYour Datastream Id
passwordYour Password
proxiesProxies if any
sslCerPath to CA bundle certificates file
Details
Timeseries Properties:
useNaNforNotANumber : Non-trading days are stored as double NaNs on Datastream, JSON protocol permits NaNs as valid numbers.
Thus, all the NULLs in the converted to NaNs in the JSON requests. Responses contain the NULLs, But this should be converted
to Nans for Plotting purposes. If you want to receive NaN float values, set useNaNforNotANumber to TRUE, any NULLs in the returned
array of float values will be converted to NaNs.
Returns
TimeSeriesClient object
Method .checkValidTimeseriesId()
A helper method to check the timeseries Id
Usage
TimeSeriesClient$.checkValidTimeseriesId(inputId)
Arguments
inputId: Timeseries Id
Returns
NULL if Timeseries id is valid else error string
Method .checkTimeSeriesReqValidity()
A helper method to check some of the mandatory fields of timeseries for its validity
Usage
TimeSeriesClient$.checkTimeSeriesReqValidity(tsItem)
Arguments
tsItemTimeseries Item
Returns
NULL if Timeseries id is valid else error string
Method .checkKeyTimeseriesProperties()
A helper method to check the Timeseries properties
Usage
TimeSeriesClient$.checkKeyTimeseriesProperties(tsItem)
Arguments
tsItemTimeseries Item
Returns
NULL if Timeseries id is valid else error string
Method .asGetAllResponse()
A helper method which converts the JSON response to GetAllResponse Object
Usage
TimeSeriesClient$.asGetAllResponse(jsonDict)
Arguments
jsonDictJSON Response
Returns
DSUserObjectGetAllResponse object
Method .asGetResponse()
A helper method which converts the JSON response to GetResponse Object
Usage
TimeSeriesClient$.asGetResponse(jsonDict)
Arguments
jsonDictJSON Response
Returns
DSUserObjectResponse object
Method .jsonRequestEncoder()
A helper method that reformats the raw request to JSON format
Usage
TimeSeriesClient$.jsonRequestEncoder(request)
Arguments
requestRaw request
Returns
return JSON formatted list
Method .jsonResponseDecoder()
A helper method that converts JSON Response to a given class response type
Usage
TimeSeriesClient$.jsonResponseDecoder(jsonResp, responseType)
Arguments
jsonRespJSON Response
responseTypeGetResponse or GetAllResponse type
Returns
return DSUserObjectGetAllResponse or DSUserObjectGetResponse object
Method GetAllItems()
This method returns all the current timeseries you can use in Datastream queries.
Usage
TimeSeriesClient$GetAllItems()
Returns
DSUserObjectGetAllResponse object
Method GetItem()
GetItem returns the details for an individual timeseries.
Usage
TimeSeriesClient$GetItem(itemId)
Arguments
itemId: a valid timeseries Id.
Returns
DSUserObjectResponse object
Method CreateItem()
This method attempts to create the given DSTimeSeriesRequestObject via the API service
Usage
TimeSeriesClient$CreateItem(newItem, overWrite = FALSE, skipItemReturn = FALSE)
Arguments
newItemA DSTimeSeriesRequestObject containing the data used for creating the Timeseries.
overWriteIf the given Timeseries Id already exists on the system, the create call will be rejected. Set overWrite = True to overwrite the existing item with new Timeseries.
skipItemReturn: Upon successful creation of an item, the server requests the new item from the mainframe and returns it in the response object. For faster processing, set skipItemReturn = True to skip returning the object in the response
Returns
DSUserObjectResponse object
Method UpdateItem()
This method attempts to modify a timeseries item using the given DSTimeSeriesRequestObject via the API service
Usage
TimeSeriesClient$UpdateItem(item, skipItemReturn = FALSE)
Arguments
itemA DSTimeSeriesRequestObject containing the data used for creating the Timeseries.
skipItemReturnUpon successful creation of an item, the server requests the new item from the mainframe and returns it in the response object. For faster processing, set skipItemReturn = True to skip returning the object in the response.
Returns
DSUserObjectResponse object
Method DeleteItem()
DeleteItem allows you to delete an existing timeseries
Usage
TimeSeriesClient$DeleteItem(itemId)
Arguments
itemIda valid timeseries Id.
Returns
No return value
Method GetTimeseriesDateRange()
This method allows you to determine the supported dates between supplied start and end dates at a specified frequency.
Usage
TimeSeriesClient$GetTimeseriesDateRange( startDate, endDate, frequency = DSUserObjectFrequency$Daily )
Arguments
startDateA date specifying the beginning of the date range
endDateA date specifying the end of the date range
frequencyA DSUserObjectFrequency enumeration defining if the frequency should be daily, weekly, monthly, quarterly or yearly.
Returns
DSTimeSeriesDateRangeResponse object
Method clone()
The objects of this class are cloneable with this method.
Usage
TimeSeriesClient$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Note
: You need a Datastream ID which is permissioned to access the Datastream APIs. In addition, this ID also needs to be permissioned to access the custom user object service. Attempting to access this service without these permissions will result in a permission denied error response.
: For Daily and Weekly frequencies, if the supplied startDate falls on a weekend or a trading holiday, the returned
starting date will be the first trading day before the given start date. If the supplied endDate falls on a weekend or a
trading holiday, the returned final date will be the last trading day before the given end date. For Weekly frequencies,
this will be the last date which matches the day of the week for the first returned start date.
For Monthly, Quarterly and Yearly frequencies, the returned dates are always the 1st day of each month, quarter or year.
The returned start and end dates are always the 1st days of the requested month, quarter or year that the given start
and end dates fall within.
: For Daily and Weekly frequencies, if the supplied startDate falls on a weekend or a trading holiday, the returned
starting date will be the first trading day before the given start date. If the supplied endDate falls on a weekend or a
trading holiday, the returned final date will be the last trading day before the given end date. For Weekly frequencies,
this will be the last date which matches the day of the week for the first returned start date.
For Monthly, Quarterly and Yearly frequencies, the returned dates are always the 1st day of each month, quarter or year.
The returned start and end dates are always the 1st days of the requested month, quarter or year that the given start
and end dates fall within.
Examples
{
# first logon with your credentials.
# Creating a TimeSeriesClient instance with your credentials
# automatically logs on for you.
timeseriesClient = TimeSeriesClient$new(NULL, 'YourID', 'YourPwd')
# query for all your current timeseries items
itemsResp = timeseriesClient$GetAllItems()
if (!is.null(itemsResp))
{
if (itemsResp$ResponseStatus != DSUserObjectResponseStatus$UserObjectSuccess)
{
# Your Datastream Id might not be permissioned for managing
# user created items on this API
print(paste('GetAllItems failed with error ',
names(DSUserObjectResponseStatus)[[itemsResp$ResponseStatus + 1]],
': ', itemsResp$ErrorMessage))
}
else if (!is.null(itemsResp$UserObjects) & itemsResp$UserObjectsCount > 0)
{
# You do have access to some timeseries
# Here we just put the timeseries details into a dataframe and list them
print(paste('GetAllItems returned', itemsResp$UserObjectsCount, 'timeseries items.'))
df = data.frame()
for (tsItem in itemsResp$UserObjects)
{
if (!is.null(tsItem))
{
rowdata = list(Id = tsItem$Id,
LastModified = tsItem$LastModified,
StartDate = ifelse(!is.null(tsItem$DateInfo),as.character(tsItem$DateInfo$StartDate),""),
EndDate =ifelse(!is.null(tsItem$DateInfo),as.character(tsItem$DateInfo$EndDate), ""),
Frequency = ifelse(!is.null(tsItem$DateInfo), tsItem$DateInfo$Frequency, 0),
NoOfValues = ifelse(!is.null(tsItem$DateRange), tsItem$DateRange$ValuesCount , 0),
Desc = tsItem$Description)
df = rbind(df, rowdata)
}
}
print(df)
}
}
#Example to show how to GetItem
# query for a specific timeseries
tsName = 'TSZZZ001'
tsResponse = timeseriesClient$GetItem(tsName)
# You may want to put the timeseries request response handling into a common function.
if (!is.null(tsResponse))
{
# Any request dealing with a single user created item returns a DSUserObjectResponse.
# This has ResponseStatus property that indicates success or failure
if (tsResponse$ResponseStatus != DSUserObjectResponseStatus$UserObjectSuccess)
{
print(paste('Request failed for timeseries', tsName, 'with error',
names(DSUserObjectResponseStatus)[[tsResponse$ResponseStatus+1]],
':', tsResponse$ErrorMessage))
}
else if (!is.null(tsResponse$UserObject))
{
# The timeseries item won't be returned if you set SkipItem true
# in CreateItem or UpdateItem
# Here we simply display the timeseries data using a dataframe.
tsItem = tsResponse$UserObject
metadata = c (Id = tsItem$Id,
Desc = tsItem$Description,
LastModified = as.character(tsItem$LastModified),
StartDate = ifelse (!is.null(tsItem$DateInfo), as.character(tsItem$DateInfo$StartDate), NULL),
EndDate = ifelse(!is.null(tsItem$DateInfo),as.character(tsItem$DateInfo$EndDate), NULL),
Frequency = ifelse(!is.null(tsItem$DateInfo),
names(DSUserObjectFrequency)[[tsItem$DateInfo$Frequency + 1]], NULL),
NoOfValues = ifelse(!is.null(tsItem$DateRange), tsItem$DateRange$ValuesCount , 0))
df = data.frame(metadata)
print(df)
if (!is.null(tsItem$DateRange))
{
df = data.frame(Dates = sapply(tsItem$DateRange$Dates,
FUN = function(x){ return (as.character(x)) }),
Values = sapply(tsItem$DateRange$Values,
FUN = function(x){ ifelse (is.null(x),
return (NA_character_ ), return (x) )} ))
# Values if NULL, is printed as <NA> because, while
# convertind list to vector either by using as.vector or sapply,
# the NULL values in the list are deleted. and thus there will
# be mismatch in no of rows and cannot be put in a dataframe
print(df)
}
}
}
}
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.