Command Line

Retail electricity data

Syntax: retail [OPTIONS ...]

Options

• -: run with no options
• --debug: enable traceback output of errors
• --format={csv}: override output format (see pandas.DataFrame.to_*)
• --group=[KEY:FUNCTION[,...]]: apply aggregate function by group key
• --header=[pack|unpack|none]: change header output (default 'pack')
• --index[=pack|unpack|none]: change index output (default 'pack')
• --keys[=KEY[,...]]: change index from default Year,Month,State
• --output=FILE[,OPTION,...]: output to file (default stdout)
• --precision=INT: change rounding
• --select=KEY:VALUE[,...]: select records based using keys and values
• --validate: perform data validation checks
• --units=glm: change units to GridLAB-D format

Description

The retail utility downloads EIA retail electricity price, sales, revenue, and customer count data. The data is collated and indexed by default by year, month, and state. Data is presented by default in multi-level columns for each data field by sector, e.g., residential, commercial, industrial, transportation and total.

The indexing can be changed using the --index= option. For example, you can specify indexing by state, year, and month by using the option --index=State,Year,Month.

Data can be grouped by any the index keys available, e.g., year, month, and/or sector, using the --group=... option. The group keys override the --index options.

To get a list of available key values, use the --keys=... option. For example, --keys=Year will return a list of available years. If multiple keys are specified, the list of keys is prefixed with the key name, followed by an equal sign, and each key list is output on a separate line.

By default all output is generated to stdout in Pandas display format. The output format can be changed using the --output=... option. The filename is used to determine the Pandas.DataFrame.to_*. If the extension is not valid, you can used the --format=... option to specify which output function to use. For example, --output=file.xlsx does not have a corresponding Pandas DataFrame output function named to_xlsx. But to_excel() handles that format, so specifying --format=excel should be specified as well.

Options for bool, int, str, and float parameters of the output functions are allowed, using comma separated tuples of the format option:value. For example, --output=file.xlsx,float_format:%g would result in the output call

pd.DataFrame.to_excel('file.xlsx',float_format='%g')

Multi headers and indexes may be packed using the --header=pack and --index=pack options. Other valid header and index options are unpack and none, which results in multi-index output or no output, respectively, of headers and indexes.

Using --units=glm automatically causes headers to be packed and drops the units columns. The index is also packed, so you must use --index=unpack to cause the index to be split into multiple columns.

See also

* EIA Electricity Data (https://www.eia.gov/electricity/data.php)

Python Library

RetailElectricity

Retail electricity data class

This class is used to select retail electricity supply data.

Examples

Create an accessor object

from retail import RetailElectricity
data = RetailElectricity()

To read the data for 2020, use

data[2020]

To read the data for August 2020, use

data[(2020,7)]

To read the data for August 2020 for California, use

data[(2020,7,"CA")]

To read the residential data for August 2020 for California, use

data[(2020,7,"CA","RESIDENTIAL")]

To read the residential price data for August 2020 for California, use

data[(2020,7,"CA","RESIDENTIAL","Price")]

To get the units of Price, use

data.units()["Price"]

To get a list of available sectors, use

data.keys(KEY_SECTOR)

To get a list of available values, use

data.key(KEY_VALUE)

RetailElectricity(url:str)

Class constructor

Arguments

• url (str): URL from which data is downloaded (default is RetailElectricity.URL)

RetailElectricity.keys(key:str, unique:bool) → set | list

Get keys used for indexing data

Arguments

• key (str): the key level for which the keys are sought (default None)
• unique (bool): specifies whether to return the distinct values

Returns

• set|list: keys at that level or all keys if level is None

RetailElectricity.units() → dict

Get units of data

Returns

• dict: mapping of value keys to units of values

main(argv:list) → int

Main CLI

Runs the main retail program.

Arguments

• argv (list[str]): argument list (default is sys.argv)

Returns

• int: exit code

Properties

• DEBUG (bool): enable debugging traceback on exception

Exceptions

• Exception: exceptions are only raised if DEBUG is True.
• FileNotFoundError: exception raised when an input file is not found.
• RetailError: exception raised when an invalid command argument is encountered.

Python Constants

E_ERROR = 1

E_OK = 0

KEY_MONTH = 'Month'

KEY_SECTOR = 'Sector'

KEY_STATE = 'State'

KEY_VALUE = 'Value'

KEY_YEAR = 'Year'

Package Metadata

Name	:	retail
Version	:	0.0.0a0
Description	:	Retail electricity data
Authors	:	David P. Chassin
Maintainers	:	David P. Chassin
Requires-Python	:	>= 3.10
Dependencies	:	pandas openpyxl
Keywords	:	retail electricity data
License	:	MIT License
Classifiers	:	Development Status :: 3 - Alpha Intended Audience :: Developers License :: OSI Approved :: MIT License Programming Language :: Python :: 3 :: Only Topic :: Software Development :: Libraries
Urls	:	Homepage = https://github.com/eudoxys/retail Documentation = https://retail.gitub.io/ Repository = https://github.com/eudoxys/retail.git Issues = https://github.com/eudoxys/retail/issues
Scripts	:	retail → main()

---

Copyright © 2024 David P. Chassin