economic-surveys-data

name	economic-surveys-data
description	Use whenever a strategy needs US macroeconomic survey data — CPI/inflation, nonfarm payrolls and earnings (CES), producer prices (PPI), or job openings (JOLTS). Covers the point-in-time BLS Economic Surveys datasets, their release-date semantics, the field tables for each survey, and the non-seasonally-adjusted caveat and how to handle it.

US economic-survey data — point-in-time BLS Economic Surveys

For macro signals built on US economic releases (inflation, employment, producer prices, labor turnover), use the BLS Economic Surveys datasets. They are delivered point-in-time — each data point is stamped with its actual release date — so a backtest sees a number only once it was really published, exactly as live trading would. This is the property that makes a macro-timing strategy reproducible live; do not substitute a revised/latest-vintage macro series, which would leak data a live strategy could never see.

The four integrated surveys

Subscribe in pyinitializecsInitialize with pyadd_data(<Class>, "<TICKER>")csAddData<Class>("<TICKER>") and keep the returned symbol. The class lives in QuantConnect.DataSource.

Survey	Class	Ticker	Coverage starts	Released
Consumer Price Index	BLSEconomicSurveysCpi	"CPI"	Jan 2000	~monthly, 08:30 ET
Current Employment Statistics	BLSEconomicSurveysCes	"CES"	Jan 2000	~monthly, 08:30 ET
Producer Price Index	BLSEconomicSurveysPpi	"PPI"	Jan 2000	~monthly, 08:30 ET
Job Openings & Labor Turnover	BLSEconomicSurveysJolts	"JOLTS"	Nov 2007	~monthly, 10:00 ET

self._cpi = self.add_data(BLSEconomicSurveysCpi, "CPI").symbol

_cpi = AddData<BLSEconomicSurveysCpi>("CPI").Symbol;

The coverage start bounds your backtest — a CPI strategy cannot start before Jan 2000 on this data, and a signal that needs N years of history to warm up effectively begins that much later. If the backtest start precedes coverage, hold the defensive/cash leg until the data exists rather than idling on empty signals.

Accessing the data — live and history (verified by probe)

Live, in pyon_datacsOnData, read the named property off the data point and key off pyend_timecsEndTime:

def on_data(self, data):
    if self._cpi in data:
        point = data[self._cpi]
        all_items = point.all_items      # headline CPI index level
        release_date = point.end_time    # the real BLS release date (point-in-time)

public override void OnData(Slice slice)
{
    if (slice.ContainsKey(_cpi))
    {
        var point = slice[_cpi];
        var allItems = point.AllItems;       // headline CPI index level
        var releaseDate = point.EndTime;     // the real BLS release date (point-in-time)
    }
}

To seed a signal from history, prefer the typed (dataset-object) history overload — it returns the actual data-point objects, so you read the SAME .all_items / .end_time properties as in on_data, with no DataFrame column-name surprises:

To seed a signal from history, prefer the typed (dataset-object) history overload — it returns the actual data-point objects, so you read the SAME .AllItems / .EndTime properties as in OnData:

for point in self.history[BLSEconomicSurveysCpi](self._cpi, 2000, Resolution.DAILY):
    level = point.all_items            # same property name as live
    release_date = point.end_time      # real release date

foreach (var point in History<BLSEconomicSurveysCpi>(_cpi, 2000, Resolution.Daily))
{
    var level = point.AllItems;          // same property name as live
    var releaseDate = point.EndTime;     // real release date
}

The plain DataFrame overload also works, but it renames the columns — the property all_items becomes column allitems, core_cpi → corecpi, final_demand → finaldemand (lower-cased, underscores stripped); its index is the release date. Prefer the typed overload above to avoid the rename:

df = self.history(self._cpi, 2000, Resolution.DAILY)   # then row["allitems"], NOT row["all_items"]

Notes:

• These are monthly releases, so a count-based daily history request must be large — a few-day window returns nothing; request enough trading days to span the months you need.
• A history request returns points from before the start date, so seed once at startup rather than idling.
• The value each point carries describes the prior month (a CPI point released mid-May is April's CPI). Every named field is an index level or a count (not a rate of change) — compute MoM/YoY/etc. yourself.

Common fields — every survey

These base fields are present on every BLS Economic Surveys data point (CPI, CES, PPI, JOLTS).

Field	Description
pyend_timecsEndTime	The actual BLS release date of this observation (point-in-time). Date every observation by this.
pytimecsTime	LEAN timestamp — unreliable for these datasets; do not use it to date the observation (use pyend_timecsEndTime).
pyvaluecsValue	Generic BaseData value — not a specific named series here; read one of the named fields below instead.

CPI fields — BLSEconomicSurveysCpi

All series non-seasonally-adjusted, base period 1982-84=100.

Field	Description
pyall_itemscsAllItems	Headline All-Items CPI index (series CUUR0000SA0)
pycore_cpicsCoreCpi	All items less food and energy — Core CPI (CUUR0000SA0L1E)
pyfoodcsFood	Food
pyfood_at_homecsFoodAtHome	Food at home
pyfood_away_from_homecsFoodAwayFromHome	Food away from home
pyenergycsEnergy	Energy
pygasolinecsGasoline	Gasoline (all types)
pysheltercsShelter	Shelter
pyrent_of_primary_residencecsRentOfPrimaryResidence	Rent of primary residence
pymedical_carecsMedicalCare	Medical care
pyapparelcsApparel	Apparel
pyeducation_and_communicationcsEducationAndCommunication	Education and communication
pynew_vehiclescsNewVehicles	New vehicles
pyused_cars_and_truckscsUsedCarsAndTrucks	Used cars and trucks
pycollege_tuition_and_feescsCollegeTuitionAndFees	College tuition and fees

CES (employment) fields — BLSEconomicSurveysCes

All series non-seasonally-adjusted, from the monthly Employment Situation report.

Field	Description
pytotal_nonfarmcsTotalNonfarm	Total nonfarm payrolls, all employees (thousands)
pytotal_privatecsTotalPrivate	Total private, all employees (thousands)
pymanufacturingcsManufacturing	Manufacturing, all employees (thousands)
pygoods_producingcsGoodsProducing	Goods-producing, all employees (thousands)
pyprivate_service_providingcsPrivateServiceProviding	Private service-providing, all employees (thousands)
pyconstructioncsConstruction	Construction, all employees (thousands)
pyretail_tradecsRetailTrade	Retail trade, all employees (thousands)
pyfinancial_activitiescsFinancialActivities	Financial activities, all employees (thousands)
pyeducation_and_health_servicescsEducationAndHealthServices	Education and health services, all employees (thousands)
pyleisure_and_hospitalitycsLeisureAndHospitality	Leisure and hospitality, all employees (thousands)
pymining_and_loggingcsMiningAndLogging	Mining and logging, all employees (thousands)
pyaverage_hourly_earningscsAverageHourlyEarnings	Average hourly earnings, total private (dollars)
pyaverage_weekly_hourscsAverageWeeklyHours	Average weekly hours, total private (hours)
pyaverage_weekly_earningscsAverageWeeklyEarnings	Average weekly earnings, total private (dollars)
pyproduction_hourly_earningscsProductionHourlyEarnings

PPI fields — BLSEconomicSurveysPpi

All series non-seasonally-adjusted. Base date varies by series (noted below).

Field	Description
pyfinal_demandcsFinalDemand	Headline Final Demand PPI index, base Nov 2009=100 (WPUFD4)
pycore_ppicsCorePpi	Final demand less foods and energy — Core PPI, base Oct 2004=100
pyfinal_demand_less_food_energy_tradecsFinalDemandLessFoodEnergyTrade	Final demand less foods, energy, and trade services, base Aug 2013=100
pyfinal_demand_goodscsFinalDemandGoods	Final demand goods, base Nov 2009=100
pyfinal_demand_servicescsFinalDemandServices	Final demand services, base Nov 2009=100
pyfinal_demand_constructioncsFinalDemandConstruction	Final demand construction, base Nov 2009=100
pyfinal_demand_goods_less_foodscsFinalDemandGoodsLessFoods	Final demand goods less foods
pyall_commoditiescsAllCommodities	All commodities, base 1982=100
pyfarm_productscsFarmProducts	Farm products, base 1982=100
pyprocessed_foods_and_feedscsProcessedFoodsAndFeeds	Processed foods and feeds, base 1982=100
pycrude_petroleumcsCrudePetroleum	Crude petroleum (domestic), base 1982=100

JOLTS fields — BLSEconomicSurveysJolts

All series non-seasonally-adjusted, total nonfarm.

Field	Description
pyjob_openingscsJobOpenings	Job openings, level (thousands)
pyjob_openings_ratecsJobOpeningsRate	Job openings rate (percent)
pyhirescsHires	Hires, level (thousands)
pyhires_ratecsHiresRate	Hires rate (percent)
pyquitscsQuits	Quits, level (thousands)
pyquits_ratecsQuitsRate	Quits rate (percent)
pytotal_separationscsTotalSeparations	Total separations, level (thousands)
pylayoffs_and_dischargescsLayoffsAndDischarges	Layoffs and discharges, level (thousands)

The series are non-seasonally-adjusted (NSA)

Every series here is non-seasonally-adjusted (NSA). This is a property of the data to be aware of — not something to "fix" by default. Whether to seasonally adjust is the strategy spec's decision, not this skill's; use the NSA series as-is unless the spec calls for a seasonally-adjusted signal.

What the NSA property means for a signal:

• Year-over-year (12-month) change is seasonality-free on NSA — comparing the same calendar month across years cancels the seasonal pattern: yoy_t = level_t / level_{t-12} − 1.
• Month-over-month change on NSA carries a strong seasonal component (gasoline up every spring, post-holiday drops every January), mixing the seasonal calendar with the underlying trend.

Only if the spec calls for a seasonally-adjusted signal, build it point-in-time from the NSA series (no point-in-time SA series is available, so you must construct it using only past data): for the calendar month c of date t, subtract the expanding-window mean of that same calendar month's values observed strictly before t (excluding the current one). Never use a centered/two-sided filter or any data dated at or after t.