citylearn.data module

class citylearn.data.CarbonIntensity(carbon_intensity: Iterable[float], start_time_step: int = None, end_time_step: int = None)[source]

Bases: TimeSeriesData

Building carbon_intensity data class.

Parameters:

  • carbon_intensity (np.array) – Grid carbon emission rate time series in [kg_co2/kWh].

  • start_time_step (int, optional) – Time step to start reading variables.

  • end_time_step (int, optional) – Time step to end reading variables.

class citylearn.data.DataSet(github_account: str = None, repository: str = None, tag: str = None, datasets_path: str = None, misc_path: str = None, logging_level: int = None)[source]

Bases: object

CityLearn input data set and schema class.

BATTERY_CHOICES_FILENAME = 'battery_choices.yaml'
DEFAULT_CACHE_DIRECTORY = '/home/runner/.cache/citylearn/v2.3.0'
GITHUB_ACCOUNT = 'intelligent-environments-lab'
GITHUB_API_CONTENT_URL = 'https://api.github.com/repos/intelligent-environments-lab/CityLearn/contents'
PV_CHOICES_FILENAME = 'lbl-tracking_the_sun-res-pv.csv'
REPOSITORY_DATA_DATASETS_PATH = 'data/datasets'
REPOSITORY_DATA_MISC_PATH = 'data/misc'
REPOSITORY_DATA_PATH = 'data'
REPOSITORY_NAME = 'CityLearn'
REPOSITORY_TAG = 'v2.3.0'
property cache_directory: Path | str
clear_cache()[source]
property datasets_path: str
get_battery_sizing_data() → Mapping[str, float | str][source]

Reads and returns internally defined real world manufacturer models.

Returns:

data

Return type:

Mapping[str, Union[float, str]]

get_dataset(name: str, directory: Path | str = None) → str[source]
get_dataset_names() → List[str][source]
get_github_contents(path: str = None) → List[Mapping[str, Any]][source]
get_pv_sizing_data() → DataFrame[source]

Reads and returns NREL’s Tracking The Sun dataset that has been prefilered for completeness.

Returns:

data

Return type:

pd.DataFrame

static get_requests_session(**kwargs) → Session[source]
get_schema(name: str) → dict[source]
property github_account: str
property logging_level: int
property misc_path: str
property repository: str
property tag: str
class citylearn.data.ElectricVehicleSimulation(state: Iterable[str], charger: Iterable[str], estimated_departure_time: Iterable[int], required_soc_departure: Iterable[float], estimated_arrival_time: Iterable[int], estimated_soc_arrival: Iterable[float], start_time_step: int = None, end_time_step: int = None)[source]

Bases: TimeSeriesData

Electric_Vehicle electric_vehicle_simulation data class.

Month,Hour,Day Type,Location,Estimated Departure Time,Required Soc At Departure

electric_vehicle_charger_state

State of the electric_vehicle indicating whether it is ‘parked ready to charge’ represented as 0, ‘in transit’, represented as 1.

Type:

np.array

charger

(available only for ‘in transit’ state) Charger where the electric_vehicle will plug in the next “parked ready to charge” state. It can be nan if no destination charger is specified or the charger id in the format “Charger_X_Y”, where X is the number of the building and Y the number of the charger within that building.

Type:

np.array

electric_vehicle_departure_time

Number of time steps expected until the vehicle departs (available only for ‘parked ready to charge’ state)

Type:

np.array

electric_vehicle_required_soc_departure

Estimated SOC percentage required for the electric_vehicle at departure time. (available only for ‘parked ready to charge’ state)

Type:

np.array

electric_vehicle_estimated_arrival_time

Number of time steps expected until the vehicle arrives at the charger (available only for ‘in transit’ state)

Type:

np.array

electric_vehicle_estimated_soc_arrival

Estimated SOC percentage for the electric_vehicle at arrival time. (available only for ‘in transit’ state)

Type:

np.array

class citylearn.data.EnergySimulation(month: Iterable[int], hour: Iterable[int], day_type: Iterable[int], indoor_dry_bulb_temperature: Iterable[float], non_shiftable_load: Iterable[float], dhw_demand: Iterable[float], cooling_demand: Iterable[float], heating_demand: Iterable[float], solar_generation: Iterable[float], daylight_savings_status: Iterable[int] = None, average_unmet_cooling_setpoint_difference: Iterable[float] = None, indoor_relative_humidity: Iterable[float] = None, occupant_count: Iterable[int] = None, indoor_dry_bulb_temperature_cooling_set_point: Iterable[int] = None, indoor_dry_bulb_temperature_heating_set_point: Iterable[int] = None, hvac_mode: Iterable[int] = None, power_outage: Iterable[int] = None, comfort_band: Iterable[float] = None, start_time_step: int = None, end_time_step: int = None)[source]

Bases: TimeSeriesData

Building energy_simulation data class.

Parameters:

  • month (np.array) – Month time series value ranging from 1 - 12.

  • hour (np.array) – Hour time series value ranging from 1 - 24.

  • day_type (np.array) – Numeric day of week time series ranging from 1 - 8 where 1 - 7 is Monday - Sunday and 8 is reserved for special days e.g. holiday.

  • indoor_dry_bulb_temperature (np.array) – Average building dry bulb temperature time series in [C].

  • non_shiftable_load (np.array) – Total building non-shiftable plug and equipment loads time series in [kWh].

  • dhw_demand (np.array) – Total building domestic hot water demand time series in [kWh].

  • cooling_demand (np.array) – Total building space cooling demand time series in [kWh].

  • heating_demand (np.array) – Total building space heating demand time series in [kWh].

  • solar_generation (np.array) – Inverter output per 1 kW of PV system time series in [W/kW].

  • daylight_savings_status (np.array, optional) – Daylight saving status time series signal of 0 or 1 indicating inactive or active daylight saving respectively.

  • average_unmet_cooling_setpoint_difference (np.array, optional) – Average difference between indoor_dry_bulb_temperature and cooling temperature setpoints time series in [C].

  • indoor_relative_humidity (np.array, optional) – Average building relative humidity time series in [%].

  • occupant_count (np.array, optional) – Building occupant count time series in [people].

  • indoor_dry_bulb_temperature_cooling_set_point (np.array) – Average building dry bulb temperature cooling set point time series in [C].

  • indoor_dry_bulb_temperature_heating_set_point (np.array) – Average building dry bulb temperature heating set point time series in [C].

  • hvac_mode (np.array, default: 1) – Cooling and heating device availability. If 0, both HVAC devices are unavailable (off), if 1, the cooling device is available for space cooling and if 2, the heating device is available for space heating only. Automatic (auto) mode is 3 and allows for either cooling or heating depending on the control action. The default is to set the mode to cooling at all times. The HVAC devices are always available for cooling and heating storage charging irrespective of the hvac mode.

  • np.array (comfort_band) – Signal for power outage. If 0, there is no outage and building can draw energy from grid. If 1, there is a power outage and building can only use its energy resources to meet loads.

  • default (2) – Signal for power outage. If 0, there is no outage and building can draw energy from grid. If 1, there is a power outage and building can only use its energy resources to meet loads.

  • np.array – Occupant comfort band above the indoor_dry_bulb_temperature_cooling_set_point and below the indoor_dry_bulb_temperature_heating_set_point [C]. The value is added to and subtracted from the set point to set the upper and lower bounds of comfort bound.

  • default – Occupant comfort band above the indoor_dry_bulb_temperature_cooling_set_point and below the indoor_dry_bulb_temperature_heating_set_point [C]. The value is added to and subtracted from the set point to set the upper and lower bounds of comfort bound.

  • start_time_step (int, optional) – Time step to start reading variables.

  • end_time_step (int, optional) – Time step to end reading variables.

DEFUALT_COMFORT_BAND = 2.0
class citylearn.data.LogisticRegressionOccupantParameters(a_increase: Iterable[float], b_increase: Iterable[float], a_decrease: Iterable[float], b_decrease: Iterable[float], start_time_step: int = None, end_time_step: int = None)[source]

Bases: TimeSeriesData

class citylearn.data.Pricing(electricity_pricing: Iterable[float], electricity_pricing_predicted_1: Iterable[float], electricity_pricing_predicted_2: Iterable[float], electricity_pricing_predicted_3: Iterable[float], start_time_step: int = None, end_time_step: int = None)[source]

Bases: TimeSeriesData

Building pricing data class.

Parameters:

  • electricity_pricing (np.array) – Electricity pricing time series in [$/kWh].

  • electricity_pricing_predicted_1 (np.array) – Electricity pricing n hours ahead prediction time series in [$/kWh]. n can be any number of hours and is typically 1 or 6 hours in existing datasets.

  • electricity_pricing_predicted_2 (np.array) – Electricity pricing n hours ahead prediction time series in [$/kWh]. n can be any number of hours and is typically 2 or 12 hours in existing datasets.

  • electricity_pricing_predicted_3 (np.array) – Electricity pricing n hours ahead prediction time series in [$/kWh]. n can be any number of hours and is typically 3 or 24 hours in existing datasets.

  • start_time_step (int, optional) – Time step to start reading variables.

  • end_time_step (int, optional) – Time step to end reading variables.

class citylearn.data.TimeSeriesData(variable: Iterable = None, start_time_step: int = None, end_time_step: int = None)[source]

Bases: object

Generic time series data class.

Parameters:

  • variable (np.array, optional) – A generic time series variable.

  • start_time_step (int, optional) – Time step to start reading variables.

  • end_time_step (int, optional) – Time step to end reading variables.

class citylearn.data.Weather(outdoor_dry_bulb_temperature: Iterable[float], outdoor_relative_humidity: Iterable[float], diffuse_solar_irradiance: Iterable[float], direct_solar_irradiance: Iterable[float], outdoor_dry_bulb_temperature_predicted_1: Iterable[float], outdoor_dry_bulb_temperature_predicted_2: Iterable[float], outdoor_dry_bulb_temperature_predicted_3: Iterable[float], outdoor_relative_humidity_predicted_1: Iterable[float], outdoor_relative_humidity_predicted_2: Iterable[float], outdoor_relative_humidity_predicted_3: Iterable[float], diffuse_solar_irradiance_predicted_1: Iterable[float], diffuse_solar_irradiance_predicted_2: Iterable[float], diffuse_solar_irradiance_predicted_3: Iterable[float], direct_solar_irradiance_predicted_1: Iterable[float], direct_solar_irradiance_predicted_2: Iterable[float], direct_solar_irradiance_predicted_3: Iterable[float], start_time_step: int = None, end_time_step: int = None)[source]

Bases: TimeSeriesData

Building weather data class.

Parameters:

  • outdoor_dry_bulb_temperature (np.array) – Outdoor dry bulb temperature time series in [C].

  • outdoor_relative_humidity (np.array) – Outdoor relative humidity time series in [%].

  • diffuse_solar_irradiance (np.array) – Diffuse solar irradiance time series in [W/m^2].

  • direct_solar_irradiance (np.array) – Direct solar irradiance time series in [W/m^2].

  • outdoor_dry_bulb_temperature_predicted_1 (np.array) – Outdoor dry bulb temperature n hours ahead prediction time series in [C]. n can be any number of hours and is typically 6 hours in existing datasets.

  • outdoor_dry_bulb_temperature_predicted_2 (np.array) – Outdoor dry bulb temperature n hours ahead prediction time series in [C]. n can be any number of hours and is typically 12 hours in existing datasets.

  • outdoor_dry_bulb_temperature_predicted_3 (np.array) – Outdoor dry bulb temperature n hours ahead prediction time series in [C]. n can be any number of hours and is typically 24 hours in existing datasets.

  • outdoor_relative_humidity_predicted_1 (np.array) – Outdoor relative humidity n hours ahead prediction time series in [%]. n can be any number of hours and is typically 6 hours in existing datasets.

  • outdoor_relative_humidity_predicted_2 (np.array) – Outdoor relative humidity n hours ahead prediction time series in [%]. n can be any number of hours and is typically 12 hours in existing datasets.

  • outdoor_relative_humidity_predicted_3 (np.array) – Outdoor relative humidity n hours ahead prediction time series in [%]. n can be any number of hours and is typically 24 hours in existing datasets.

  • diffuse_solar_irradiance_predicted_1 (np.array) – Diffuse solar irradiance n hours ahead prediction time series in [W/m^2]. n can be any number of hours and is typically 6 hours in existing datasets.

  • diffuse_solar_irradiance_predicted_2 (np.array) – Diffuse solar irradiance n hours ahead prediction time series in [W/m^2]. n can be any number of hours and is typically 12 hours in existing datasets.

  • diffuse_solar_irradiance_predicted_3 (np.array) – Diffuse solar irradiance n hours ahead prediction time series in [W/m^2]. n can be any number of hours and is typically 24 hours in existing datasets.

  • direct_solar_irradiance_predicted_1 (np.array) – Direct solar irradiance n hours ahead prediction time series in [W/m^2]. n can be any number of hours and is typically 6 hours in existing datasets.

  • direct_solar_irradiance_predicted_2 (np.array) – Direct solar irradiance n hours ahead prediction time series in [W/m^2]. n can be any number of hours and is typically 12 hours in existing datasets.

  • direct_solar_irradiance_predicted_3 (np.array) – Direct solar irradiance n hours ahead prediction time series in [W/m^2]. n can be any number of hours and is typically 24 hours in existing datasets.

  • start_time_step (int, optional) – Time step to start reading variables.

  • end_time_step (int, optional) – Time step to end reading variables.

citylearn.data.get_settings()[source]