1name: Analyze datasets and ship reports1# Analyze datasets and ship reports | Codex use cases

2tagline: Turn messy data into clear analysis and visualizations.

3summary: Use Codex to clean data, join sources, explore hypotheses, model

4 results, and package the output as a reusable artifact.

5skills:

6 - token: $spreadsheet

7 description: Inspect CSV, TSV, and Excel files when formulas, exports, or quick

8 spreadsheet checks matter.

9 - token: $jupyter-notebook

10 url: https://github.com/openai/skills/tree/main/skills/.curated/jupyter-notebook

11 description: Create or refactor notebooks for exploratory analysis, experiments,

12 and reusable walkthroughs.

13 - token: $doc

14 url: https://github.com/openai/skills/tree/main/skills/.curated/doc

15 description: Produce stakeholder-ready `.docx` reports when layout, tables, or

16 comments matter.

17 - token: $pdf

18 url: https://github.com/openai/skills/tree/main/skills/.curated/pdf

19 description: Render PDF outputs and check the final analysis artifact before you

20 share it.

21bestFor:

22 - Data analysis that starts with messy files and should end with a chart,

23 memo, dashboard, or report

24 - Analysts who want Codex to help with cleanup, joins, exploratory analysis,

25 and reproducible scripts

26 - Teams that need reviewable artifacts instead of one-off notebook state

27starterPrompt:

28 title: Turn the Dataset Into a Reproducible Analysis

29 body: >-

30 I'm doing a data analysis project in this workspace.

31 2 

3Need

32 4 

33 Goal:5Analysis stack

34 6 

35 - Figure out whether houses near the highway have lower property valuations.7Default options

36 8 

9[pandas](https://pandas.pydata.org/) with [matplotlib](https://matplotlib.org/) or [seaborn](https://seaborn.pydata.org/)

37 10 

38 Start by:11Why it's needed

39 12 

40 - reading `AGENTS.md` and explaining the recommended Python environment13Good defaults for import, profiling, joins, cleaning, and the first round of charts.

41 14 

42 - loading the dataset(s) at [dataset path]

43 

44 - describing what each file contains, likely join keys, and obvious data

45 quality issues

46 

47 - proposing a reproducible workflow from import and tidy through

48 visualization, modeling, and report output

49 

50 

51 Constraints:

52 

53 - prefer scripts and saved artifacts over one-off notebook state

54 

55 - do not invent missing values or merge keys

56 

57 - suggest any skills or worktree splits that would make the workflow more

58 reproducible

59 

60 

61 Output:

62 

63 - setup plan

64 

65 - data inventory

66 

67 - analysis plan

68 

69 - first commands or files to create

70relatedLinks:

71 - label: Agent skills

72 url: /codex/skills

73 - label: Worktrees in the Codex app

74 url: /codex/app/worktrees

75techStack:

76 - need: Analysis stack

77 goodDefault: "[pandas](https://pandas.pydata.org/) with

78 [matplotlib](https://matplotlib.org/) or

79 [seaborn](https://seaborn.pydata.org/)"

80 why: Good defaults for import, profiling, joins, cleaning, and the first round

81 of charts.

82 - need: Modeling

83 goodDefault: "[statsmodels](https://www.statsmodels.org/) or

84 [scikit-learn](https://scikit-learn.org/stable/)"

85 why: Start with interpretable baselines before moving to more complex predictive

86 models.

87 

88## Introduction

89 

90At its core, data analysis is about using data to inform decisions. The goal isn't analysis for its own sake. It's to produce an artifact that helps someone act: a chart for leadership, an experiment readout for a product team, a model evaluation for researchers, or a dashboard that guides daily operations.

91 

92A useful framework, popularized by _R for Data Science_, is a loop: import and tidy data, then iterate between transform, visualize, and model to build understanding before you communicate results. Programming surrounds that whole cycle.

93 

94Codex fits well into this workflow. It helps you move around the loop faster by cleaning data, exploring hypotheses, generating analyses, and producing reproducible artifacts. The target isn't a one-off notebook. The target is a workflow that other people can review, trust, and rerun.

95 

96## Define your use case

97 

98Choose one concrete question you want to answer with your data.

99 

100The more specific the question, the better. It will help Codex understand what you want to achieve and how to help you get there.

101 

102### Running example: Property values near the highway

103 

104As an example, we'll explore the following question:

105 

106> To what extent are houses near the highway lower in property valuation?

107 

108Suppose one dataset contains property values or sale prices, and another contains location, parcel, or highway-proximity information. The work isn't only to run a model. It's to make the inputs trustworthy, document the joins, pressure-test the result, and end with an artifact that somebody else can use.

109 

110## Set up the environment

111 

112When you start a new data analysis project, you need to set up the environment and define the rules of the project.

113 

114- **Environment:** Codex should know which Python environment, package manager, folders, and output conventions are canonical for the project.

115- **Skills:** Repeated workflows such as notebook cleanup, spreadsheet exports, or final report packaging should move into reusable skills instead of being re-explained in every prompt.

116- **Worktrees:** Separate explorations into separate worktrees so one hypothesis, merge strategy, or visualization branch doesn't bleed into another.

117 

118To learn more about how to install and use skills, see our [skills documentation](https://developers.openai.com/codex/skills).

119 

120### Guide Codex's behavior

121 

122Before touching the data, tell Codex how to behave in the repo. Put personal defaults in `~/.codex/AGENTS.md`, and put project rules in the repository `AGENTS.md`.

123 

124A small `AGENTS.md` is often enough:

125 

126```md

127## Data analysis defaults

128 

129- Use `uv run` or the project's existing Python environment.

130- Keep source data in `data/raw/` and write cleaned data to `data/processed/`.

131- Put exploratory notebooks in `analysis/` and final artifacts in `output/`.

132- Never overwrite raw files.

133- Prefer scripts or checked-in notebooks over unnamed scratch cells.

134- Before merging datasets, report candidate keys, null rates, and join coverage.

135```

136 

137If the repo doesn't already define a Python environment, ask Codex to create a reproducible setup and explain how to run it. For data analysis work, that step matters more than jumping straight into charts.

138 

139## Import the data

140 

141Often the fastest way to start is to paste the file path and ask Codex to inspect it. This is where Codex helps you answer basic but important questions:

142 

143- What file formats are here?

144- What does each dataset seem to represent?

145- Which columns might be targets, identifiers, dates, locations, or measures?

146- Where are the clear quality issues?

147 

148Don't ask for conclusions yet. Ask for inventory and explanation first.

149 

150## Tidy and merge the inputs

151 

152Most real work starts here. You have two or more datasets, the primary key isn't clear, and a naive merge could lose data or create duplicates.

153 

154Ask Codex to profile the merge before performing it:

155 

156- Check uniqueness for candidate keys.

157- Measure null rates and formatting differences.

158- Normalize clear formatting issues such as casing, whitespace, or address formatting.

159- Run trial joins and report match rates.

160- Recommend the safest merge strategy before it writes the final merged file.

161 

162If you need to derive the best key, such as a normalized address, a parcel identifier built from a few columns, or a location join, make Codex explain the tradeoffs and edge cases before you accept the merge.

163 

164## Explore with charts and separate worktrees

165 

166Exploratory data analysis is where Codex benefits from clean isolation. One worktree can test address cleanup or feature engineering while another focuses on charts or alternate model directions. That keeps each diff reviewable and prevents one long thread from mixing incompatible ideas.

167 

168The Codex app includes built-in worktree support. If you are working in a terminal, plain Git worktrees work well too:

169 

170```bash

171git worktree add ../analysis-highway-eda -b analysis/highway-eda

172git worktree add ../analysis-model-comparison -b analysis/highway-modeling

173```

174 

175In the running example, this step is where you would compare homes near the highway against homes farther away, examine outliers, inspect missing-value patterns, and decide whether the observed effect looks real or reflects neighborhood composition, home size, or other factors.

176 

177## Model the question

178 

179Not every analysis needs a complex model. Start with an interpretable baseline.

180 

181For the highway question, a sensible first pass is a regression or other transparent model that estimates the relationship between highway proximity and property value while controlling for relevant factors such as size, age, and location.

182 

183Ask Codex to be explicit about:

184 

185- The target variable and feature definitions.

186- Which controls to include and why.

187- Leakage risks and exclusions.

188- How it chose the split, evaluation, or uncertainty estimate.

189- What the result means in plain language.

190 

191If the first model is weak, that's still useful. It tells you whether the problem is the model, the features, the join quality, or the question itself.

192 

193## Communicate the result

194 

195The analysis is only useful when someone else can consume it. Ask Codex to produce the artifact the audience needs:

196 

197- A Markdown memo for technical collaborators.

198- A spreadsheet or CSV for downstream operations work.

199- A `.docx` brief using `$doc` when formatting and tables matter.

200- A rendered appendix or final deliverable using `$pdf`.

201- A lightweight dashboard or static report site deployed with `$vercel-deploy`.

202 

203This is also where you ask for caveats. If the join quality is imperfect, sampling bias is present, or the model assumptions are fragile, Codex should say that plainly in the deliverable.

204 

205## Skills to consider

206 

207The curated skills that fit this workflow especially well are:

208 

209- `$spreadsheet` for CSV, TSV, and Excel editing or exports.

210- `$jupyter-notebook` when the deliverable should stay notebook-native.

211- `$doc` and `$pdf` for stakeholder-facing outputs.

212- `$vercel-deploy` when you want to share the result as a URL.

213 

214Once the workflow stabilizes, create repo-local skills for the repeated parts, such as `refresh-data`, `merge-and-qa`, or `publish-weekly-report`. That's a better long-term pattern than pasting the same procedural prompt into every thread.

215 

216## Suggested prompts

217 

218**Set Up the Analysis Environment**

219 

220**Load the Dataset and Explain It**

221 

222**Profile the Merge Before You Join**

223 

224**Open a Fresh Exploration Worktree**

225 

226**Build an Interpretable First Model**

227 

228**Package the Results for Stakeholders**