Skip to content

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.