Destination ranks¶
This dataset evaluates whether HCT ranks a worker's observed next employer above plausible alternatives. It reads the exported int8 embedding archives directly: it does not reload the model, rebuild embeddings, or require firm-MQ or hiring- frequency files. Each conditional scenario is an oracle diagnostic, because its industry or pre-move size band is defined from the realised destination firm. The archive metadata records—and the scorer cross-checks—the common checkpoint provenance of the company and mover exports, but the checkpoint file itself is not opened or required at scoring time.
flowchart TB
movers[(Mover worker embeddings)]
companies[(Company embeddings<br/>and static attributes)]
activity[(Company-year observed counts)]
pools[Build t−1 active-firm pools]
score[Draw 999 unique alternatives<br/>and rank the destination]
output[(Destination ranks)]
movers --> score
companies --> pools
companies --> score
activity --> pools
pools --> score
score --> output
classDef source fill:#e8eef7,stroke:#52739e
classDef process fill:#fff0cc,stroke:#a66b00
classDef data fill:#eee5f5,stroke:#76528c
class movers,companies,activity source
class pools,score process
class output data
Inputs
| Dataset | Location |
|---|---|
| Company embedding table | For training: /data/<coverage>/analyses/profile_worker/training/embeddings/ or /data/<coverage>/analyses/profile_time/training/embeddings/; for full_training: /data/<coverage>/analyses/full_training/embeddings/ |
| Mover embedding table | worker_embeddings_movers/ under the selected profile/mode embeddings directory |
| Embedding metadata | _metadata.yaml in the selected embeddings directory — validates the checkpoint and MQ weights |
| Company-year observed counts | data.company_year_observed_counts_path — provides the prior-year active-firm universe and size |
Build
| Component | Location |
|---|---|
| Builder | model/scoring/score_destination_ranks.py |
| Runtime | hct-tower-model-cuda-… (GPU task) |
| Entry point | python -m scoring.score_destination_ranks / score-destination-ranks |
Output
| Dataset | File / location | Grain | Key variables |
|---|---|---|---|
| Destination ranks | Source-named Parquet shards in /data/<coverage>/analyses/profile_worker/training/destination_ranks/ or /data/<coverage>/analyses/profile_time/training/destination_ranks/; full-training output is under /data/<coverage>/analyses/full_training/destination_ranks/. Selected shard sets are nested under shards/user_00_01/. |
One scenario × sampled move |
IDs and dates; scenario, sample_status, selection_stratum; incumbent/destination industry and industry_transition; destination state/size band; candidate-pool size; MQ scores/gain; rank; size_rank |
For a move in calendar year t, eligible candidates are firms with
observed_active_users > 0 in year t − 1. The observed destination must also
be active in t − 1; the incumbent is removed whenever it belongs to the same
candidate pool. The scorer then draws 999 unique alternatives uniformly without
replacement and appends the destination, so every retained row has exactly 1,000
candidates. HCT's weighted cosine rank and the firm-size rank use that exact
same pool. The size rank uses the expected rank under random tie breaking, which
is important because observed firm size is discrete. A random ordering has
Recall@1 of 0.1% and Recall@10 of 1% by construction.
The sampling contract is configured at
scoring.<mode>.datasets.destination_ranks.sampling. Its default targets are
50,000 global moves, 50,000 moves in each global-size band, 10,000 moves in
each broad-industry stratum, and 5,000 moves in each industry × size-band
stratum. A stratum with fewer eligible moves than its configured target is
excluded entirely rather than retained at a smaller sample size. This gives
each retained conditional market equal weight and avoids noisy sparse cells.
For training, choose --profile worker or --profile time to select the
checkpoint, embedding archives, split labels, and destination-rank output
root. Each retained stratum's fixed target is split proportionally between
combined train/validation (in-sample) and test (out-of-sample) events under
that profile. For profile-independent full_training, omit --profile; the
full target is in-sample. The metadata records the configured contract,
available counts, excluded undersized strata, per-status quotas, and realised
counts.
The standard scenarios (global, global_size_band, industry2, and
industry2_size_band) remain unconditional with respect to whether a worker
changes industry. Every row nevertheless records incumbent_industry2 and
industry_transition: same_industry, industry_switch, or
industry_unknown when either firm lacks broad-industry information.
Three additional balanced transition scenarios require known incumbent and
destination industries. global_industry_transition draws 50,000 moves from
each transition type using global candidates. global_size_band_industry_transition
draws 50,000 from each transition × destination-size-band cell using candidates
in that size band. industry2_size_band_industry_transition uses destination
industry × size candidates and draws 5,000 from each transition cell. Its
industry-size market is retained only when both transition cells meet that
target; otherwise both are excluded. This paired rule gives same-industry and
switching movers identical destination-market composition.
Global scenarios require neither industry nor HQ-state information, so they
retain destinations with missing values in those fields and remain comparable to
the original global test. The two industry scenarios exclude only destinations
with missing industry2; no current scenario conditions on HQ state.
For every size-controlled scenario, the destination and all alternatives are
in the same fixed lagged-size band: under_5 (observed_active_users < 5) or
5_plus (observed_active_users >= 5). The thresholds are constant across
candidate-pool years; the metadata records the resulting candidate-year firm
counts. These remain global-year and industry × global-size-band comparisons,
not industry × state × size cells, so candidate pools retain enough firms for a
1,000-firm ranking exercise.
Eligibility counting and deterministic within-stratum selection use DuckDB to scan only required scalar Parquet columns and perform joins, grouping, and window ranking columnarly. Embedding vectors are not read until the later GPU scoring phase. The two-pass design remains necessary because stratum eligibility and proportional status quotas depend on complete eligibility counts.
--shards 00,01 restricts only the mover embedding source files used for
event eligibility, sampling, and GPU scoring. It retains the full company
embedding table and full prior-year active-firm pools, so every selected mover
is still ranked against the same economy-wide or destination-industry candidate
universe as in the all-shard run. Selected outputs and their metadata are
isolated under destination_ranks/shards/user_00_01/; a shard run never
overwrites the canonical all-shard dataset. Existing undersized-stratum rules
continue to apply without modification.
Only destination starts on or after 2009-01-01 are eligible. Output uses the
original external company_id and destination_company_id, not internal model
indices. Dataset version 10 intentionally replaces the former v9 schema; the R
table builder must be updated separately before consuming v10.
Command reference
| Option | Required / default | Source-defined effect |
|---|---|---|
--config PATH |
Required | Model YAML config, including paths and scoring defaults. |
--mode training\|full_training |
Required | Selects embedding archives and output mode. |
--profile worker\|time |
Required with --mode training; omit for full_training |
Selects the training checkpoint, split labels, embedding archive, and output root. |
| Sampling contract | scoring.<mode>.datasets.destination_ranks.sampling |
Per-stratum targets, undersized-cell treatment, and training status allocation. It is intentionally configured in YAML, not overridden by a single global CLI count. |
--num-negatives N |
Config num_negatives (999) |
Unique uniformly drawn alternatives per retained move; output candidate count is N + 1. |
--seed N |
Config seed (42) |
Deterministic event-selection and candidate-draw seed. |
--batch-size N |
Config employee_batch_size |
Embedding rows scored per GPU batch. |
--shards IDS |
All mover shards | Comma- or whitespace-separated user shard IDs from 00 through 19. Restricts mover events only and writes under shards/user_<IDs>/. |
--resume / --overwrite |
Off | Resume compatible source-shard progress or recreate output; mutually exclusive. |
| Option | Required / default | Source-defined effect |
|---|---|---|
--task score-destination-ranks |
Required | Selects slurm/model/score_destination_ranks.slurm. |
--config CONFIG.yaml |
Required | Resolves model configuration passed to the scorer. |
--mode training\|full_training |
Required | Passed to the scorer. |
--profile worker\|time |
Required with --mode training; omit for full_training |
Selects the profile-specific checkpoint, embedding archive, and output root. |
--shards IDS |
All mover shards | Passes the shared user-shard selection to the scorer and its matching output scope. |
--destination-rank-args 'ARGS' |
Empty | Extra direct-scorer options, such as --num-negatives, --seed, or --batch-size. |
--resume / --overwrite |
Off | Passed to the scorer; cannot be combined. |
--partition, --time, --mem, --cpus, --gpus, --constraint, --exclude, --job-name, --dependency, --dry-run |
Wrapper defaults | Standard Slurm overrides; default request is one GPU, 8 CPUs, 256 GB, and 24 hours. The full candidate-selection scan and candidate-pool construction are memory-intensive. |
--repo-root, --data-root, --artifact-root, --container-root, --sif |
Wrapper defaults | Override host paths or the Apptainer image. |
cd /hct-tower/model
python -m scoring.score_destination_ranks \
--config config/config_full.yaml --profile worker --mode training
python -m scoring.score_destination_ranks \
--config config/config_full.yaml --profile time --mode training
python -m scoring.score_destination_ranks \
--config config/config_full.yaml --mode full_training
python -m scoring.score_destination_ranks \
--config config/config_full.yaml --profile worker --mode training --shards 00,01
cd /hct-tower
slurm/submit.sh --task score-destination-ranks \
--profile worker --mode training --config config_full.yaml
slurm/submit.sh --task score-destination-ranks \
--profile time --mode training --config config_full.yaml
slurm/submit.sh --task score-destination-ranks \
--mode full_training --config config_full.yaml
slurm/submit.sh --task score-destination-ranks \
--profile worker --mode training --config config_full.yaml --shards 00,01
The job checkpoints after every mover-embedding source shard. --resume
verifies embedding metadata, company-year counts, and ranking controls before
continuing; do not combine it with --overwrite.