Dataset

CityLearn makes use of datasets that are a collection of data files. The data files are used to define the simulation environment as well as provide some observation values. See Data Files for more information.

Data Files

The data files refer to flat files containing time series data that are used to set observations that are agent action agnostic (i.e. observations that are not a function of the control actions). These files are referenced in the environment schema.json and read when citylearn.citylearn.CityLearnEnv is initialized. The data files are desrcribes as follows:

Building Data File

The building file is a csv file that contains a building’s temporal (calendar), end-use loads, solar generation and indoor environment variables time series data including. There are as many building files as buildings in the environment. The end-use loads, solar generation and indoor environment data may come from simulation in energy modeling software e.g. EnergyPlus or from smart meter or Building Automation System (BAS) measurements. The file structure is shown in the snippet below:

Month,Hour,Day Type,Daylight Savings Status,Indoor Temperature [C],Average Unmet Cooling Setpoint Difference [C],Indoor Relative Humidity [%],Equipment Electric Power [kWh],DHW Heating [kWh],Cooling Load [kWh],Heating Load [kWh],Solar Generation [W/kW]
1,1,8.0,0.0,18.93,0.0,77.92,9.8,0.0,0.0,0.0,0.0
1,2,8.0,0.0,18.82,0.0,77.97,10.41,0.0,0.0,0.0,0.0
1,3,8.0,0.0,18.76,0.0,77.89,10.39,0.0,0.0,0.0,0.0
1,4,8.0,0.0,18.66,0.0,77.74,10.33,0.0,0.0,0.0,0.0
1,5,8.0,0.0,18.62,0.0,77.37,9.41,0.0,0.0,0.0,0.0

Weather Data File

The weather file is a .csv file that contains outdoor weather variables time series for the desired simulation geographical location. It is used as the source for citylearn.building.Building.weather, which is the source for weather related observations. Typical Meteorological Year (TMY) or Actual Meteorological Year (AMY) data can be used. The file structure is shown in the snippet below:

Outdoor Drybulb Temperature [C],Relative Humidity [%],Diffuse Solar Radiation [W/m2],Direct Solar Radiation [W/m2],6h Prediction Outdoor Drybulb Temperature [C],12h Prediction Outdoor Drybulb Temperature [C],24h Prediction Outdoor Drybulb Temperature [C],6h Prediction Relative Humidity [%],12h Prediction Relative Humidity [%],24h Prediction Relative Humidity [%],6h Prediction Diffuse Solar Radiation [W/m2],12h Prediction Diffuse Solar Radiation [W/m2],24h Prediction Diffuse Solar Radiation [W/m2],6h Prediction Direct Solar Radiation [W/m2],12h Prediction Direct Solar Radiation [W/m2],24h Prediction Direct Solar Radiation [W/m2]
20.0,84.0,0.0,0.0,18.3,22.8,20.0,81.0,68.0,81.0,25.0,964.0,0.0,100.0,815.0,0.0
20.1,79.0,0.0,0.0,19.4,22.8,19.4,79.0,71.0,87.0,201.0,966.0,0.0,444.0,747.0,0.0
19.7,78.0,0.0,0.0,21.1,22.2,19.4,73.0,73.0,87.0,420.0,683.0,0.0,592.0,291.0,0.0
19.3,78.0,0.0,0.0,22.2,22.8,19.4,71.0,71.0,90.0,554.0,522.0,0.0,491.0,153.0,0.0
18.9,78.0,0.0,0.0,21.7,22.2,18.9,73.0,71.0,90.0,778.0,444.0,0.0,734.0,174.0,0.0

Carbon Intensity Data File

The carbon intensity file is a .csv file that contains CO:sub:2 emission rate time series. It is used as the source for citylearn.building.Building.carbon_intensity, which is the source for the carbon_intensity observation. The data can be sourced from grid operators e.g. ERCOT, NYISO or third-party sources WattTime. The file structure is shown in the snippet below:

kg_CO2/kWh
0.17072441264038085
0.15731905810375976
0.1545025601953125
0.15094487789819336
0.1518198641750488

Pricing Data File

The carbon intensity file is a .csv file that contains current time-step and forecasted electricity price time series. It is used as the source for citylearn.building.Building.pricing, which is the source for pricing related observations. The data can be sourced from specific utility providers for a desired location e.g. Edison. The file structure is shown in the snippet below:

Electricity Pricing [$],6h Prediction Electricity Pricing [$],12h Prediction Electricity Pricing [$],24h Prediction Electricity Pricing [$]
0.22,0.22,0.22,0.22
0.22,0.22,0.22,0.22
0.22,0.22,0.22,0.22
0.22,0.22,0.22,0.22
0.22,0.22,0.54,0.22

Schema Data File

The schema file is a .json file that references all other data files and is used to define the simulation environment. Refer to Schema for more information.

Warning

Do not change the order of columns in any of the .csv data files!