Dataset

A CityLearn dataset combines a JSON schema with the time series and optional models needed by a scenario. Load a public dataset by name, a local schema path or an in-memory schema dictionary; see How to Load an Environment.

V3 supports CSV and Parquet time series with the same column contract. The CSV snippets below illustrate the main inputs; Dataset Reference also covers EV schedules, flexible-appliance cycles, topology events and demand-response requests. Match the timestep and energy units to Data Unit Contract.

Data Files

The schema references the input files read when citylearn.citylearn.CityLearnEnv is initialized. They provide exogenous inputs such as demand, weather and prices; device states and action-dependent outputs are computed during the simulation.

Building Data File

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

month,hour,day_type,daylight_savings_status,indoor_dry_bulb_temperature,average_unmet_cooling_setpoint_difference,indoor_relative_humidity,non_shiftable_load,dhw_demand,cooling_demand,heating_demand,solar_generation,occupant_count,indoor_dry_bulb_temperature_cooling_set_point,indoor_dry_bulb_temperature_heating_set_point,hvac_mode
6,1,1,1,28.121962,0.0,49.774185,0.5676419,0.0,0.0,0.0,0.0,0.0,30.0,30.0,0
6,2,1,1,27.939466,0.0,49.843094,0.5676419,0.0,0.0,0.0,0.0,0.0,30.0,30.0,0
6,3,1,1,27.780298,0.0,49.965446,0.5676419,0.0,0.0,0.0,0.0,0.0,30.0,30.0,0
6,4,1,1,27.642626,0.0,50.026028,0.5676419,0.0,0.0,0.0,0.0,0.0,30.0,30.0,0
6,5,1,1,27.526384,0.0,50.043957,0.5676419,0.0,0.0,0.0,0.0,0.0,30.0,30.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_dry_bulb_temperature,outdoor_relative_humidity,diffuse_solar_irradiance,direct_solar_irradiance,outdoor_dry_bulb_temperature_predicted_1,outdoor_dry_bulb_temperature_predicted_2,outdoor_dry_bulb_temperature_predicted_3,outdoor_relative_humidity_predicted_1,outdoor_relative_humidity_predicted_2,outdoor_relative_humidity_predicted_3,diffuse_solar_irradiance_predicted_1,diffuse_solar_irradiance_predicted_2,diffuse_solar_irradiance_predicted_3,direct_solar_irradiance_predicted_1,direct_solar_irradiance_predicted_2,direct_solar_irradiance_predicted_3
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:

carbon_intensity
0.1707244
0.15731905
0.15450256
0.15094487
0.15181987

Pricing Data File

The pricing 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,electricity_pricing_predicted_1,electricity_pricing_predicted_2,electricity_pricing_predicted_3
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

LSTM Model File

The LSTM model file is an optional PyTorch state dictionary used to initialize the cooling_dynamics and heating_dynamics temperature dynamics model attributes in citylearn.building.DynamicsBuilding and its descendant classes.

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.

Use the column names documented in Dataset Reference and ensure all time-series inputs cover the requested simulation interval.