TimeSeriesClient {DatastreamR}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

useNaNforNotANumber

If Enabled, NaN is appears in output response instead of NULL

TimeseriesResponseType

Response 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
config

Configuration File path

username

Your Datastream Id

password

Your Password

proxies

Proxies if any

sslCer

Path 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
tsItem

Timeseries 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
tsItem

Timeseries 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
jsonDict

JSON Response

Returns

DSUserObjectGetAllResponse object

Method .asGetResponse()

A helper method which converts the JSON response to GetResponse Object

Usage
TimeSeriesClient$.asGetResponse(jsonDict)
Arguments
jsonDict

JSON Response

Returns

DSUserObjectResponse object

Method .jsonRequestEncoder()

A helper method that reformats the raw request to JSON format

Usage
TimeSeriesClient$.jsonRequestEncoder(request)
Arguments
request

Raw 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
jsonResp

JSON Response

responseType

GetResponse 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
newItem

A DSTimeSeriesRequestObject containing the data used for creating the Timeseries.

overWrite

If 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
item

A DSTimeSeriesRequestObject containing the data used for creating the 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 DeleteItem()

DeleteItem allows you to delete an existing timeseries

Usage
TimeSeriesClient$DeleteItem(itemId)
Arguments
itemId

a 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
startDate

A date specifying the beginning of the date range

endDate

A date specifying the end of the date range

frequency

A 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
deep

Whether 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)

     }
   }
 }
}
[Package DatastreamR version 2.0.4 Index]