A quantitative notebook should make its data request as explicit as its model. Currency, indicator, date window and revision selection determine what observations enter the calculation. Changing any of them can change the meaning of a result.
This guide uses FXMacroData.jl to load a bounded US inflation history and a release calendar. It prepares the inputs for research without treating a current history response as proof of what was available at an earlier trading decision.
Who this is for: Teams using Julia who want a repeatable macro-data workflow with explicit inputs and understandable failure states.
Prerequisites
A Julia environment, the FXMacroData.jl package from the linked GitHub repository, and access to the requested history. The example historical range requires subscription coverage. Store the subscription key in FXMACRODATA_API_KEY before starting Julia.
- Client
- Bound history
- Inspect vintages
1. Add the client to the project
The SDK guide lists the repository installation route:
using Pkg
Pkg.add(url="https://github.com/fxmacrodata/FXMacroData.jl")Use a project environment so the notebook's dependencies can be reproduced. Record the resolved package revision with the research materials. Installing from a repository is a distribution route; it does not imply a Julia General registry listing.
2. Request the history you intend to study
Create the client and make the date range and revision option visible in the notebook:
using Dates
using FXMacroData
client = Client()
inflation = announcements(
client, "USD", "inflation";
start_date=Date(2025, 1, 1),
end_date=Date(2025, 12, 31),
revisions="all",
)
calendar = release_calendar(client, "USD")Client reads FXMACRODATA_API_KEY from the environment. Inspect the returned objects before selecting columns for analysis; retain the response's identities and metadata alongside the numeric observations.
3. Keep reference periods and revisions distinct
With all revisions requested, more than one record can concern the same reference period. Do not collapse those rows accidentally during a join or aggregation. First decide whether the research needs a current series, an initial print or a sequence of published vintages.
A date range alone does not reconstruct historical availability. For a strategy replay, use the fields and coverage that establish the relevant vintage's availability. If those are absent for the requested record, the notebook should report the limitation rather than assign an assumed decision-time value.
4. Keep calendar planning separate
The calendar response describes official scheduled events. It belongs in an event-planning table, separate from the observations used to calculate a signal. Link through explicit currency and release identities when the model needs both.
Finish the notebook's data section with the requested series, date window, revision scope and retrieval time. Preserve the raw response as a research input before creating a derived table. The next calculation can then explain exactly which observations it consumes.
Workflow checks
| Part | Purpose |
|---|---|
| Currency and indicator | Identify one statistical series |
| Date window | Bound the requested observations |
| Revision scope | Specify which versions are retained |
| Calendar response | Plan around scheduled events |
Choose the research sample before calculating the result
A descriptive notebook and an event-study notebook may request the same inflation series while needing different samples. The descriptive notebook can explain the returned history as it stands. The event study asks a different question: which version was eligible at a particular market decision? Make that choice before calculating a change or joining observations to prices.
Repeated reference periods in an all-revisions response are therefore information to inspect, not duplicate rows to discard automatically. Retain the version evidence until the study’s selection rule is explicit. A convenient group-by operation can silently turn a revision history into a different dataset, especially when it keeps an arbitrary first or last row.
Write a short sample definition beside the first calculation: the series, period window, revision choice and treatment of unavailable evidence. A colleague should be able to identify which observations the calculation consumed without reading the plotting code. When the notebook is rerun with a later retrieval, compare the selected sample before explaining any change in a statistic. That keeps computational convenience subordinate to the question the research is meant to answer.
Continue from the working example
Continue with the linked setup guide for supported installation and request options. Keep the selected series and its response context together as the workflow expands.
Sources and related guides
AI was used for research, creating images and editing.
