===============================================
REQUIREMENTS - Please ensure before running:
===============================================
1. PYTHON: Install Python 3.x from https://www.python.org/downloads/
   - Check "Add Python to PATH" during installation

2. PACKAGES: Run in terminal:
   pip install numpy pandas scipy pyarrow wrds python-dotenv

3. DATA: The strategy needs three parquet files:
   ctff_chars.parquet, ctff_features.parquet, ctff_daily_ret.parquet (optional)
   - Either use files that have already been downloaded, OR
   - Build them yourself from WRDS (requires a WRDS account) using
     02-DownloadJKPdata.py - see its header for full instructions.

4. WRDS CREDENTIALS: You will need a subscription to CRSP/Compustat via WRDS, which is available to students at Queen's University Belfast. Register for an account at: https://wrds-www.wharton.upenn.edu/. Add your WRDS username and password to env-template.txt, which is provided with the course materials. The setup step below will turn it into your root .env file for you.
===============================================

SETUP STEP (do this before anything else)
Ask the user for the folder containing their data files, and check that
ctff_chars.parquet and ctff_features.parquet exist there.
If they DO exist, skip straight to the tasks below.
If they do NOT exist, offer to build the data with 02-DownloadJKPdata.py:
  - Check whether a .env file exists in the root folder. If it does not,
    create one by copying env-template.txt to a file named .env in the root
    folder. Then ask the user for their WRDS username and password, and
    replace your_username_here / your_password_here in .env with the values
    they provide. (The user needs their own WRDS account.)
  - Then run:  python 02-DownloadJKPdata.py --out-dir <folder>
Do not start the tasks below until ctff_chars.parquet and
ctff_features.parquet are in place.

TASK
Run a quantitative equity trading strategy - walk-forward factor selection
with meta-selection - and assemble it as a JKP CTF submission. Do NOT modify
or extend the strategy: run the provided baseline as-is and submit that. The
strategy selects stock characteristics ("factors") - and even its own
methodology - using only information available at each point in time, so its
out-of-sample track record is honest: no look-ahead, no configuration
selection bias.

BACKGROUND FILES
Analyse these files before running anything:
- 02-DownloadJKPdata.py - a runnable script that obtains the underlying data
  (the official JKP CTF tables via WRDS) and writes it in the ctff format.
  Read its header for the data background, target schema, and caveats. Only
  needed if the user does not already have the parquet files.
- 03-StrategySpecification.txt - the complete, self-contained specification
  of the strategy: data schema, the four stages, hard constraints, required
  deliverables, and the verification checklist (V1-V5). This is the
  authoritative description.
- 04-StrategyTemplate.py - the working baseline implementation. This IS the
  model you will run and submit; use it as-is. (It contains EXTENSION POINT
  blocks for optional self-study, but this task does not use them.)

TASK 1 - RUN THE BASELINE
Run 04-StrategyTemplate.py against the user's data folder:
   python 04-StrategyTemplate.py --data <folder>
Report the annualized Sharpe ratios by period and the average monthly
turnover, and explain to the user in plain language what each of the four
stages did.

TASK 2 - PREPARE THE SUBMISSION (JKP CTF)
Assemble the files required to submit to the JKP Characteristics Trading
Factor challenge - rules: https://jkpfactors.com/ctf/rules . Produce, in a
`submission/` folder:
  1. The model script (.py) - a self-contained copy of 04-StrategyTemplate.py
     exposing main(chars, features, daily_ret) with the exact output schema
     (columns id, eom, w; no missing values). Keep it under 1 MB, UTF-8. It
     must run start-to-finish with no manual steps.
  2. requirements.txt - every dependency pinned to the exact version used
     (e.g. pandas==2.2.3), so the run is reproducible.
  3. weights.csv - the portfolio weights produced by main() on the full
     dataset: columns id, eom (YYYY-MM-DD), w, no NaNs, under 50 MB. (The
     graders score only rows where ctff_test is True, but export all rows.)
  4. methodology.pdf - a short methodology document, exported to PDF,
     describing the baseline strategy: the four stages and how each one
     avoids look-ahead (the methodology document is highly encouraged by the
     rules).
Before declaring the submission ready, re-confirm V2 (truncation test) and
V5 (determinism): the challenge auto-detects look-ahead by running your
script on truncated data and requiring identical predictions. Provide a clear explanation of how to submit to the JKP competition at: https://jkpfactors.com/ctf/submit

THE RULE THAT MATTERS MOST
Temporal integrity. Every decision made at the end of month t (which
factors, which weights, which configuration) may only use information
realized by the end of month t. The single most common error - in student
code and AI-generated code alike - is using ret_exc_lead1m (the FORWARD
return, realized over month t+1) as if it were known at month t. Explain
every line of the strategy that touches ret_exc_lead1m; if a use cannot be
justified, treat it as a bug.

REPORT
Once completed, summarise for the user:
- The baseline Sharpe ratio table by sub-period and the average turnover
- Which verification checks were run and their outcomes
- A plain-language explanation of how each stage avoids look-ahead
- The location and contents of the submission/ folder, with a one-line
  description of each file and confirmation it is ready to upload to
  https://jkpfactors.com/ctf/rules