BIMETS2CSV: BIMETS2CSV
In bimets: Time Series and Econometric Modeling

BIMETS2CSV

R Documentation

BIMETS2CSV

Description

This function transforms a time series list into a CSV (Comma-Separated Values) file built with the ordered sequence of pairs, i.e., dates and observation values, copied from the input time series. The CSV file can then be easily manipulated by external spreadsheet programs or other econometric applications (e.g., MS Excel (R), Python, STATA(R), SAS(R), etc. ).

Heterogeneous frequency

If the time series to be exported have different frequencies, the CSV file will consist of as many pairs of columns as time series to be exported.

For each time series, a column for dates and a subsequent column for observation values will be created. The column header of the date column will contain the description of the related time series (see attributeOfNames argument).

The header of the observation column will contain the related time series frequency value in the format FREQ_f, f=1,2,3,4,6,12,53,366, etc. (see the freqHeaderPrefix argument and examples).

Any missing observation NA will be printed in the CSV file as the string defined in the missingString argument.

Homogeneous frequency

If all input time series have the same frequency, and mergeList=TRUE, the date column will be unique and will correspond to the first column in the CSV file (see the mergeList argument); in this case, the global frequency value will be printed in the date column header (in the same format as described before); other columns will contain observation values having the time series description in the column header (see attributeOfNames argument and examples).

Any missing observation NA will be printed in the CSV file as the string defined in the missingString argument.

Locale configuration

Users can change current locale (e.g., month names) by using the base R command locales, e.g.:

Sys.setlocale('LC_TIME','en_US.UTF8'),

Sys.setlocale('LC_TIME','fr_FR.UTF8'),

Sys.setlocale('LC_TIME','it_IT.UTF8'),

... etc (see examples).

Metadata specification

The first line of text in the CSV file will contain metadata information about the cell separator, e.g. "sep=,"

This metadata information is often inserted to allow the CSV file to be directly opened in MS Excel(R).

Usage

BIMETS2CSV( 
  input=NULL, 
  cellSeparator=',', 
  decimalSeparator='.', 
  filePath=NULL, 
  overWrite=FALSE,
  append=FALSE, 
  mergeList=FALSE, 
  TSRANGE=NULL,  
  attributeOfNames=NULL, 
  dateFormat='%Y/%m/%d', 
  missingString='NA', 
  plainTable=FALSE, 
  title=NULL, 
  freqHeaderPrefix='FREQ_', 
  avoidCompliance=FALSE,
  ...)

Arguments

`input`	Input time series list, or a single input time series. Time series must be compliant with the specifications defined in the `is.bimets` help page.
`cellSeparator`	Delimiter that separates individual data fields (i.e., cells) in the CSV file. Default to ","
`decimalSeparator`	The character in the CSV file that separates the integer part of a number from its fractional part. Default to "."
`filePath`	Path of the output CSV file.
`overWrite`	If the CSV file in the `filePath` already exists, and `overWrite=FALSE`, an error will be thrown; If `overWrite=TRUE`, the output CSV file will be overwritten.
`append`	If the CSV file in the `filePath` already exists, and `append=TRUE`, the new time series data will be appended to the existing CSV file.
`mergeList`	It is possible to export time series into two different types of CSV files. If `mergeList=FALSE`, the output CSV file will contain, for each time series to be exported, a couple of adjacent columns, i.e, a date column and an observation value column. Thus, it is possible to export time series that have different frequencies. The date column header will contain the time series description (see `attributeOfNames` argument). On the other hand, the observation header, will contain the frequency for the related time series, econded using the `freqHeaderPrefix` argument, e.g., `FREQ_12`, `FREQ_4`, etc. (see examples). If `mergeList=TRUE`, and all input time series have the same frequency, only a single date column will be exported, and it will be the first column in the CSV file, followed by as many columns as the time series to be exportd. The data header will contain the frequency for all the output time series, using the `freqHeaderPrefix` argument as stated above. The observation column headers will contain time series descriptions (see `attributeOfNames` argument and examples).
`TSRANGE`	If `mergeList=TRUE`, the 4-element integer array argument `TSRANGE=c(startY,startP,endY,endP)` allows users to select observations to be exported.
`attributeOfNames`	Both description and frequency for each input time series are exported in column headers. In particular, the time series description is copied from `input` list attributes, giving priority to: - `input` list names, i.e., `names(input)`; - the time series attribute whose name is specified in this argument `attributeOfNames`; - the time series attribute `Title`; - the input variable name, in the case of a single input time series; - the string "UNKNOWN SERIES";
`dateFormat`	The date format to be used when converting an observation `Date()` variable into the string to be exported into the CSV. Default to : `"%Y/%m/%d"`. In the the `GETDATE` help page all compatible tags are listed, e.g. `%Y, %m, %d`, etc...
`missingString`	Time series missing values `NA` will be exported into the CSV file as the string defined in this in argument `missingString`. Default to `NA`.
`plainTable`	If `plainTable=TRUE`, the following arguments will be definitively set to: `mergeList=TRUE` `cellSeparator=;` `decimalSeparator=.` `dateFormat=%d/%m/%Y` Date column header will be set to `"DATE"`
`title`	Users can insert, into the output CSV file, a header line containing the text passed as a string to the argument `title`. If `title` is defined as a string array, for each array's element, a new line will be inserted into the CSV file header.
`freqHeaderPrefix`	The tag prefix in the CSV file used when exporting a frequency value on the related time series header. Default to: `FREQ_`. The prefix will be followed by the numeric frequency value, e.g. `FREQ_4`, `FREQ_12`, etc. (see examples).
`avoidCompliance`	If `TRUE`, compliance control check of input time series will be skipped. See `is.bimets`.
`...`	Backward compatibility.

Value

This function produces a CSV file, in the provided filePath, built with time series observations, ordered by date, and copied from the input time series list.

Examples



#define file path
filePath <- tempfile(fileext = ".csv")

#Heterogeneous frequency -----------------------------

#create time series
ts1 <- TSERIES(1:10+0.000057,START=c(2000,1),FREQ=1)
ts2 <- TSERIES(1:11,START=c(2001,2),FREQ=12)
ts3 <- TSERIES(c(1:3,NA,9:19)+0.0023,START=c(2001,3),FREQ=4)

#create time series list
myList <- list(
  myTitle1=ts1,
  myTitle2=ts2,
  myTitle3=ts3)

#export time series to csv then import back from csv

#export
BIMETS2CSV(
  myList,
  cellSeparator=';',
  decimalSeparator=',',
  dateFormat='%Y%m%d',
  filePath=filePath,
  overWrite=TRUE)

#import from csv
outList <- CSV2BIMETS(
  filePath,
  cellSeparator=';',
  decimalSeparator=',',
  dateFormat='%Y%m%d')

#compare input and output time series
for (idx in paste0('myTitle',1:3)) TABIT(myList[[idx]],outList[[idx]])

#Homogeneous frequency -----------------------------

#re-define time series, same frequency, different time range
ts1 <- TSERIES(1:10+0.000057,START=c(2000,1),FREQ=12)
ts2 <- TSERIES(1:11,START=c(2001,2),FREQ=12)
ts3 <- TSERIES(c(1:3,NA,9:19)+0.0023,START=c(2001,3),FREQ=12)

#create time series list
myList <- list(
  myTitle1=ts1,
  myTitle2=ts2,
  myTitle3=ts3)

#export time series to csv then import from csv

#export with BIMETS2CSV and mergeList=TRUE 
#note: argument in CSV2BIMETS is "mergedList"
BIMETS2CSV(
  myList,
  mergeList=TRUE, 
  cellSeparator=';',
  decimalSeparator=',',
  dateFormat='%Y%m%d',
  filePath=filePath,
  overWrite=TRUE)
	
outList <- CSV2BIMETS(filePath,
  mergedList=TRUE,
  cellSeparator=';',
  decimalSeparator=',',
  dateFormat='%Y%m%d')

#compare input and output time series
for (idx in paste0('myTitle',1:3)) TABIT(myList[[idx]],outList[[idx]])

#Impose user frequency -----------------------------

#create a monthly CSV file to be imported as a quarterly, i.e., FREQ_4
cat(c(
"FREQ_4,myTitle1,myTitle2",
"2001/01/31,NA,NA",
"2001/02/28,1,NA",
"2001/03/31,2,1.0023",
"2001/04/30,3,2.0023",
"2001/05/31,4,3.0023",
"2001/06/30,5,NA",
"2001/07/31,6,9.0023",
"2001/08/31,7,10.0023",
"2001/09/30,8,11.0023",
"2001/10/31,9,12.0023",
"2001/11/30,10,13.0023",
"2001/12/31,11,14.0023"
),
sep='\n',
file=filePath)

#import CSV
outList <- CSV2BIMETS(
  filePath,
  mergedList=TRUE)

#print quarterly series
TABIT(outList$myTitle1,outList$myTitle2)

#Automatic frequency retrieval -----------------------------

#create a quarterly CSV file with no frequency indication
cat(c(
"DATE,myTitle1,myTitle2",
"2001/03/31,2,1.0023",
"2001/06/30,5,NA",
"2001/09/30,8,11.0023",
"2001/12/31,11,14.0023"
),
sep='\n',
file=filePath)

#import CSV
outList <- CSV2BIMETS(
  filePath,
  mergedList=TRUE)

#print quarterly series
TABIT(outList$myTitle1,outList$myTitle2)

#Change locale -----------------------------

#set language to french
Sys.setlocale('LC_TIME','fr_FR.UTF8')

#export with BIMETS2CSV, full month names, and mergeList=TRUE 
BIMETS2CSV(
  myList,
  mergeList=TRUE, 
  dateFormat='%Y %B %d',
  filePath=filePath,
  overWrite=TRUE)

#print file with french month names
cat(readLines(file(filePath)),sep='\n')

#read back file
outList <- CSV2BIMETS(
  filePath, 
  dateFormat='%Y %B %d',
  mergedList=TRUE)
	
#Custom TSRANGE, Title, missingString -----------------------------

#set language to US english
Sys.setlocale('LC_TIME','en_US.UTF8')

#define ts
ts1 <- TSERIES(1:10+0.000057,START=c(2000,1),FREQ=12)

#insert missing values
ts1[[c(2000,5),c(2000,7)]] <- NA

#set custom ts description
attributes(ts1)$MyDescription <- 'My Long Description'

#export to csv
BIMETS2CSV(
  ts1, 
  dateFormat='%Y %B %d',
  filePath=filePath,
  overWrite=TRUE,
  attributeOfNames='MyDescription',
  missingString='.',
  freqHeaderPrefix='MYFREQ_',
  title="CSV TITLE")
  
#print file with custom settings
cat(readLines(file(filePath)),sep='\n')
  
#reimport in R
outList <- CSV2BIMETS(
  filePath,
  dateFormat='%Y %B %d',
  filePath=filePath,
  freqHeaderPrefix='MYFREQ_',
  skipLines=1)

#print ts
TABIT(outList[['My Long Description']])

bimets documentation built on Nov. 11, 2025, 5:10 p.m.