Interface to the Macrobond API for Windows

Description

Interface to the Macrobond API for Windows, which allows you to access the time series in the Macrobond database. You need to have the Macrobond application installed and configured with a valid user account.

Details

With the MacrobondAPI you can download time series from the Macrobond database. You can also upload in-house series.

The most important methods are FetchTimeSeries and FetchOneTimeSeries. These allows you to download time series along with metadata for the series. A powerful option is to use the built-in ratios when downloading series. There is an example below that uses the PerCapita ratio.

The methods CreateUnifiedTimeSeriesRequest is used when you want to download and convert a set of time series to a common frequency and calendar. You can specify the frequency conversion method as well as the method to use for filling in any missing values. The series can be converted to a common currency. If you are happy with the default conversion settings, you can use the method FetchUnifiedTimeSeriesDefault instead.

You can create new time series and upload them to the in-house database by using the method UploadOneOrMoreTimeSeries.

With the method getMetadata you can get Metadata for TimeSeries and Entity objects. Read more about metadata here.

The method as.xts and MakeXtsFromUnifiedResponse converts Macrobond time series objects to xts objects.

If you have a Data Scientist license you can download series with revision history using FetchOneTimeSeriesWithRevisions or FetchTimeSeriesWithRevisions as well as searching for series by calling Search.

Author(s)

Thomas Olsson at Macrobond, uses parts of RDCOMClient written by Duncan Temple Lang <duncan@wald.ucdavis.edu>

Maintainer: Macrobond support <support.removethis@removethis.rt.macrobond.com>

References

https://help.macrobond.com/add-ins/, http://www.omegahat.net/RDCOMClient/

See Also

FetchOneTimeSeries FetchOneTimeSeriesWithRevisions FetchTimeSeries FetchTimeSeriesWithRevisions getMetadata CreateUnifiedTimeSeriesRequest FetchUnifiedTimeSeriesDefault UploadOneOrMoreTimeSeries as.xts.TimeSeries Search SearchByConcept

Examples

	# Load the series "usgdp". If you want to load several series you can use "FetchTimeSeries(listOfSeriesNames)" instead.
	seriesGdp <- FetchOneTimeSeries("usgdp")
	# Check that the series loaded OK
	if (getIsError(seriesGdp))
		stop(getErrorMessage(seriesGdp))

	# Show a summary of the series object (same as "show(seriesGdp)")
	seriesGdp

	# Show the title
	getTitle(seriesGdp)

	# Get the values and dates
	vectorOfValues <- getValues(seriesGdp)
	vectorOfObservationDates <- getDatesAtStartOfPeriod(seriesGdp)

	# Make a simple plot of the series
	plot(seriesGdp)

	# Get the currency of the series
	metaGdp <- getMetadata(seriesGdp)
	currency <- getFirstMetadataValue(metaGdp, "Currency")

	# Convert the Macrobond time series object to an xts series
	seriesGdp.xts <- as.xts(seriesGdp)

	# Use the PerCapita ratio to get a series of the US GDP per capita.
	# There are several other ratios available that can be applied to series where it makes sense.
	# See https://help.macrobond.com/tutorials-training/3-analyzing-data/ratios-in-macrobond/calculated-macrobond-ratios/
	seriesGdpPerCapita <- FetchOneTimeSeries("#PerCapita(usgdp)")
	
	# Upload an in-house time series
	seriesNew = CreateTimeSeriesObject("ih:mb:priv:s1", "My forecast", "us", "Forecasts", "Monthly", as.Date("1990-01-01"), c(12.2, 12.7, 12.8, 13.0))
	UploadOneOrMoreTimeSeries(seriesNew)

	# Get information about a release.
	# The name of the release is a metadata property of the time series.
	# The release has a corresponding "entity" in the database.
	releaseGdpName <- getFirstMetadataValue(metaGdp, "Release")
	if (!is.null(releaseGdpName))
	{
		releaseGdp <- FetchOneEntity(releaseGdpName)
		# The NextReleaseEventTime attribute contains information about the next scheduled release of updated series.
		# The date might be missing if no release date is known.
		getFirstMetadataValue(getMetadata(releaseGdp), "NextReleaseEventTime")
	}

	# Download two series, convert them to the same frequency using default settings, and then create an xts data frame
	twoSeries <- FetchUnifiedTimeSeriesDefault(c("usgdp", "uscpi"))
	series.xts <- MakeXtsFromUnifiedResponse(twoSeries)

	# Download two series, convert them to quarterly, set missing value method for one of them, and then create an xts data frame
	seriesRequest <- CreateUnifiedTimeSeriesRequest()
	setFrequency(seriesRequest, "Quarterly")
	addSeries(seriesRequest, "usgdp")
	seriesExpressionCpi <- addSeries(seriesRequest, "uscpi")
	setMissingValueMethod(seriesExpressionCpi, "None")
	twoSeries <- FetchTimeSeries(seriesRequest)
	series.xts <- MakeXtsFromUnifiedResponse(twoSeries)

	# The methods below requires a Data Scientist license and MB app >= 1.23

	# Search for time series defined for the concept "gdp_total" for four countries and then download those series.
	gdp_names <- SearchByConcept(c("us", "gb", "jp", "cn"), "gdp_total")
	series <- FetchUnifiedTimeSeriesDefault(gdp_names)

	# Fetch revision history for usgdp and get series for first and second release
	seriesGdp <- FetchOneTimeSeriesWithRevisions("usgdp")
	firstRelease <- getNthRelease(seriesGdp, 0)
	secondRelease <- getNthRelease(seriesGdp, 1)
	series.xts <- MakeXtsFromUnifiedResponse(c(firstRelease, secondRelease))
	plot(series.xts)

  	# Load the series revisions and get the vintage series that shows what it looked like at 2018-01-01
	seriesWithRevisions <- FetchOneTimeSeriesWithRevisions("usgdp")
  	series2018 <- getVintage(seriesWithRevisions, as.POSIXct("2018-01-01 18:00:00", tz = "EST"))