Skip to content

Module reference

Generated by scripts/docs/generate_reference.py from the source itself, so it cannot drift from the code. Each entry lists the module’s purpose and its public classes and functions.

Private names (leading underscore) are omitted; they are implementation detail.

src/inmotion/__init__.py - 8 lines

inMotion — WiFi RSSI mobility classification.

Single importable package for the project’s data, model, training, evaluation and CLI surfaces. Legacy top-level modules (dl, ml_classification) are being folded in here; see docs/reports/ for the migration notes.

No public classes or functions; this module provides data or constants consumed elsewhere.

src/inmotion/cli/__init__.py - 77 lines

The inmotion command-line interface.

One package, one module per command group:

model inspect, verify, predict and adopt checkpoints datasets dataset versions, provenance and checksums data build and clean datasets (export, merge, clean, augment) bus scrape the Aveiro bus networks and build the OD matrices train train models (classification, dl, exotic, hpo-paper) evaluate evaluate and combine models (ensemble, checkpoints, shap, importance) analyze analyse results (seeds, interference) plots regenerate figures from saved results edge the edge-quantization campaign on the wavecom routers doctor report on the environment and the artifact store

Each command builds a typed RunConfig and calls the pipeline’s run(). The CLI holds no pipeline logic, and the pipelines hold no argument parsing, so either side can change without touching the other.

Public API:

  • func main - [bold]inMotion[/] — WiFi RSSI mobility classification.

src/inmotion/datasets.py - 362 lines

Dataset version registry.

The datasets are committed to git, so their history is the version history. What git cannot tell you is which version is safe to train on: earlier collections were assembled with different device pools, and the project owner reports that older versions carry incorrect class labels. That knowledge is recorded here, next to checksums that prove a file has not silently changed.

Two kinds of information are kept apart on purpose:

  • Measured — sha256, row count, class counts, device count, size, and the commit that first added the file. Regenerated by :func:build_manifest, so it cannot drift.
  • Curated — role, lineage, status and the label audit. Written by hand, because it is project knowledge rather than something derivable from the file.

:func:verify` re-checks the measured side, so a dataset that changed under git’s feet (a re-export written over the same path) is caught.

Public API:

  • class DatasetVersion - One recorded version of one dataset file.
  • func measure - Fill in the measured fields from the file on disk.
  • func build_manifest - Regenerate the whole manifest, measuring every curated version.
  • func write_manifest
  • func load_manifest - Read the manifest, or None when it has not been generated yet.
  • func verify - Check every recorded dataset against its checksum and row count.
  • func resolve - Find a dataset version by id or file name.
  • func canonical - The dataset new training runs should use.

src/inmotion/data/paths.py - 99 lines

Canonical locations for data files, and resolution of dataset references.

The project has three data tiers, matching how a dataset is actually produced:

raw/ Captures straight off the access point (Wavecom .txt dumps). Never edited; the input to inmotion data export. interim/ One CSV per collection session, as written by export. Input to inmotion data merge. processed/ Merged and augmented datasets that training and evaluation consume.

Before this module the tiers all lived in the repository root or in wavecom_files/, and code referred to datasets by bare filename (dataset.csv) from whatever the current directory happened to be.

:func:resolve keeps those bare references working by searching the tiers in order, so an old command line such as --data dataset.csv still finds the file, while new code uses explicit paths.

Public API:

  • func resolve - Resolve a dataset reference to a path.
  • func processed - Path to a processed dataset, by bare filename.
  • func raw - Path to a raw capture, by bare filename.
  • func interim - Path to an interim per-collection CSV, by bare filename.
  • func list_processed - Every file in the processed tier, sorted.
  • func list_raw - Every raw capture, sorted.

src/inmotion/data/preprocessing.py - 185 lines

Reproducible RSSI feature pipeline.

The training code standardised RSSI values with a StandardScaler and then engineered extra channels, but never persisted the scaler. Two different conventions were in use, which is why a saved model could not be re-run without also having the exact training CSV:

inmotion/dl/data_loader.py scaler.fit_transform(X_raw) on the whole file, before the split. inmotion/pipelines/mega_ensemble.py StandardScaler().fit(_raw_X[train_idx]) on the training fold only.

:class:FeaturePipeline records which convention produced a model, stores the fitted statistics next to the checkpoint, and replays them at inference. A pipeline whose statistics were rebuilt from a reference CSV rather than recovered from training is flagged reconstructed so results are never presented as more reproducible than they are.

Public API:

  • class FeaturePipeline - Standardisation + channel expansion for RSSI sequences.

src/inmotion/data/export.py - 130 lines

Public API:

  • func extract_rssi_and_mac_pairs
  • func export_to_csv

src/inmotion/data/merge.py - 133 lines

Merge multiple CSV files into a single dataset.

Public API:

  • func extract_concurrent_noise_path - Extract the concurrent noise path from filename and row label.
  • func merge_csv_files - Merge multiple CSV files into a single dataset.

src/inmotion/data/clean.py - 215 lines

Dataset cleaning audit — find and drop devices/samples that poison training.

Why: on the current data/processed/dataset.csv the absolute RSSI level carries ~3x more information about WHICH DEVICE recorded a sequence than about WHICH movement it is (MI with MAC 0.219 vs MI with label 0.071). Several devices sit at/below chance under cross-device evaluation, i.e. their sequences genuinely do not look like their labels. This script quantifies that per device, drops the poisoned parts, and writes a cleaned CSV plus a full report.

within_mcc : stratified CV inside the device (does it agree with itself?) low -> labels are inconsistent/noisy for this device -> DROP lodo_mcc : leave-one-device-out (train on all other devices, predict this one) low -> device distribution is shifted vs everyone else -> DROP (unless –keep-shifted: keep self-consistent-but-shifted devices)

OOF probabilities from a KNN on the surviving rows: samples the model rejects with high confidence (max prob > –ambiguity-thresh AND wrong class) are reported to _flagged.csv; dropped too with –drop-ambiguous.

MAMBA_SSM_AVAILABLE=0 uv run inmotion data clean -- --data data/processed/dataset.csv
# stricter: also drop ambiguous samples
MAMBA_SSM_AVAILABLE=0 uv run inmotion data clean -- --drop-ambiguous

Public API:

  • func run - Execute the pipeline.

src/inmotion/data/augment.py - 127 lines

Data Augmentation for RSSI sequences.

Two strategies:

  1. Class-Conditioned Noise Augmentation
    • noise=False (clean): inject heavier Gaussian noise to teach model how “clean” data looks when it gets dirty.
    • noise=True (noisy): apply only light jitter so the real signal is not overwhelmed.
  2. Intra-class Mixup λ ~ Beta(α, α), X_new = λ·X₁ + (1-λ)·X₂ (same label only)

All synthetic rows get synthetic=True; originals get synthetic=False.

Public API:

  • func noise_augment - Return a DataFrame of n_copies noisy versions of every row in df.
  • func mixup_augment - Intra-class Mixup: X_new = λ·X₁ + (1−λ)·X₂, same label only.
  • func augment

src/inmotion/data/splits.py - 43 lines

The train/validation/test split convention.

One definition, because every reported number depends on it. The convention is an 80/20 stratified train-test split, then 12.5% of the train portion held out for validation, both with a fixed seed.

This lived in pipelines/mega_ensemble.py and was imported from there by three other modules, which meant a 1,000-line pipeline had to be imported to obtain a fifteen-line function. It is a data concern, so it lives with the data.

Public API:

  • func stratified_indices - Return (train, validation, test) index arrays.

src/inmotion/bus/sources.py - 284 lines

Polite, cached, checksummed fetching of the operator sites, plus inventory.

Neither operator publishes GTFS, so the schedules only exist as web pages. This module is the one place that talks to the two sites:

  • it sleeps crawl_delay seconds between network requests, using the value each site’s robots.txt asks for (AveiroBus asks for 10s, BusWay for none);
  • it caches every response under data/bus/raw/<operator>/ and serves repeat runs from disk, so a re-parse never re-hits the site;
  • it records url, sha256 and size of every artifact in manifest.json, which makes the scrape replayable and detects a page that changed under our feet.

Nothing here parses timetables; that is inmotion.bus.busway and inmotion.bus.aveirobus.

Public API:

  • class Operator - One bus operator site.
  • class LinePage - One served timetable page: a line, in one direction.
  • class Fetcher - Fetch with a cache, a crawl delay, and a manifest of what was fetched.
  • func local_name - A readable, collision-free filename for a URL.
  • func parse_line_id - Split 16-ida into ("16", "ida"); L35 has no direction.
  • func busway_inventory - Every BusWay line page, from the operator’s own sitemap.
  • func aveirobus_inventory - Every AveiroBus timetable PDF linked from its index pages.
  • func load_manifest - The recorded URL -> checksum map.

src/inmotion/bus/busway.py - 245 lines

Parse BusWay line pages into trips and their stop-to-stop calls.

Every BusWay line page carries one <table class="tabela-horaria"> per service type (weekdays, Saturdays, Sundays and holidays). Inside such a table each column is one trip and each row is one stop, so a cell is a single departure time — or – when that trip does not call at that stop. The page therefore publishes the whole timetable, not just endpoint departures, which is what an OD matrix needs.

Cell attributes carry the service detail:

ÉPOCA A = Anual, PE = Período Escolar (term time only). fundoamarelo The cell is highlighted because it is the hand-over point of a connection; the matching footnote in the table’s observacao row says to which line. * A marker pointing at that same footnote.

The parser is deliberately ignorant of which lines exist; it turns one page into records and leaves the inventory to inmotion.bus.sources.

Public API:

  • class Cell - One table cell: its text, its CSS classes and its column span.
  • func parse_tables - Every table on the page, with its class attribute.
  • func page_identity - Read the line, direction and route caption a page carries.
  • func parse_line_page - Every trip on one BusWay line page, for the direction it carries.

src/inmotion/bus/aveirobus.py - 1014 lines

Parse AveiroBus timetable PDFs into trips and their stop-to-stop calls.

AveiroBus publishes one PDF per urban line, and the timetable inside it is a single embedded bitmap (about 3400x2200 px, some 430 dpi) rather than text: pdftotext returns nothing but the page number. Text extraction therefore means OCR, and OCR over a whole page is exactly where timetable digits get silently lost.

So the page is not read as prose:

  1. the bitmap is lifted out of the PDF at its native resolution, with no resampling anywhere;
  2. the grid is recovered from the pixels — the red header bands give the column groups and the service each column belongs to, the OCR word boxes give the rows and the column pitch;
  3. each cell is then read from two independent OCR passes (different page segmentation, scale and binarisation) and OCR’d from a tight crop of that cell alone when they disagree, or when the value would break the invariant that a trip’s times never run backwards.

Every cell that needed that third opinion is counted and reported, so the confidence of an extraction is visible rather than assumed.

Public API:

  • func unaccent - Lowercase, unaccented, hyphen-free text, for matching captions.
  • class Word - One OCR word box, in image pixels.
  • class Band - One red column-group header: the x-range it labels and its caption.
  • class Block - One timetable on the page: a stop list running against a set of trips.
  • func timetable_image - The largest embedded bitmap of the document: the timetable itself.
  • func ocr_words - OCR one image, returning word boxes in the original pixel frame.
  • func tesseract_languages - The language packs the installed tesseract can load, by name.
  • func read_cell - Read a single time out of one cell, with a digits-and-colon whitelist.
  • func read_caption - OCR one caption crop, returning the text and its word boxes.
  • func banner_text - OCR the vector route caption printed above the timetable bitmap.
  • func close_horizontal - Fill horizontal holes up to radius wide, to bridge glyph gaps.
  • func runs - Maximal runs of True at least minimum long.
  • func close_vertical - Fill vertical holes up to radius tall, to bridge glyph gaps.
  • func header_bands - The coloured column-group headers, whatever colour the line uses.
  • func keep_heading_bands - Drop colour bars that head no timetable.
  • func column_highlights - The background colour of each trip column, and which ones are tinted.
  • func cluster - Group values into (centre, size), splitting where the gap is too big.
  • func median
  • func column_pitch - The spacing between adjacent trip columns, from the closest pair in any row.
  • func build_block - Recover the stop list, the trip columns and every time of one block.
  • func cell_box - The pixel rectangle of one (row, column) cell, with a little padding.
  • func assign_matrix - Map an independent OCR pass onto the grid the first pass established.
  • func reconcile - Settle each cell between two OCR passes, asking a third when they differ.
  • func fill_missing - Read every cell the page-level OCR left empty, one crop at a time.
  • func enforce_monotonic - A trip’s times never run backwards; repair or flag any cell that does.
  • func format_minutes - Minutes past midnight as HH:MM, for diagnostics.
  • func roll_block - Put a block’s columns on a continuous scale across midnight.
  • func to_minutes - "07:45" to minutes past midnight; None when there is no time.
  • class Extraction - One parsed PDF, with how much work the OCR needed.
  • func label_bands - Split each coloured strip into one band per printed caption.
  • func text_words - Exact word boxes from a PDF text layer, in page points.
  • func text_bands - Service headers of a text-layer timetable, one band per header line.
  • func text_caption - The route description of a text-layer timetable.
  • func parse_text_pdf - Every trip of a line PDF whose timetable is a real text layer.
  • func parse_pdf - Every trip of one AveiroBus line PDF.

src/inmotion/bus/paths.py - 70 lines

Canonical locations for the bus-network artifacts and derived tables.

The three tiers mirror inmotion.data.paths, with the bus network kept apart from the WiFi captures so neither can be mistaken for the other:

raw/ Whatever the operator sites served, byte for byte: BusWay line pages and AveiroBus line PDFs, plus manifest.json. A cache, not a deliverable. interim/ One CSV per operator, straight out of its parser, before the two networks are reconciled. processed/ The merged stop/trip/stop-time tables and the OD matrices derived from them, plus the stop coordinates resolved from OpenStreetMap. scenarios/ One directory per synthetic passenger-flow scenario, named after its configuration. Regenerable output, not a deliverable.

Public API:

  • func raw_dir - Raw artifact directory of one operator, created on demand.
  • func osm_cache - Where the cached OpenStreetMap responses live, created on demand.
  • func scenario - Directory of one generated scenario, created on demand.
  • func interim - Path to an interim table, by bare filename.
  • func processed - Path to a processed table, by bare filename.

src/inmotion/bus/records.py - 80 lines

The record shapes both operator parsers produce.

Keeping one definition for both networks is what lets inmotion.bus.od build the OD matrices without caring which site a trip came from.

Public API:

  • class Call - One trip calling at one stop.
  • class Trip - One scheduled trip, with every stop it calls at in order.
  • func roll_past_midnight - Put a trip’s times on one continuous scale across midnight.
  • func timed - Calls with a time, in stop order.

src/inmotion/bus/od/bands.py - 44 lines

Departure bands and service labels, as the two operators write them.

Every classification the OD tables depend on lives here, because a band applied at the wrong point silently rewrites the matrix: a (line, direction, service) group can span the whole service day, so banding such a group by its earliest departure files every one of its trips under that first band.

Public API:

  • func band - The departure band a trip’s first stop belongs to.
  • func format_minutes - Minutes past midnight back to HH:MM, keeping hours past 24.
  • func service_group - Collapse the operators’ own service labels to weekday or weekend.

src/inmotion/bus/od/stops.py - 39 lines

Stop identity: one canonical key per stop per operator, and the stop dictionary.

Public API:

  • func canonical - A stable stop key: lowercase, unaccented, alphanumerics only.
  • func stop_id - The canonical id of one stop of one operator.
  • func stops_frame - The stop dictionary: one row per operator-specific stop.

src/inmotion/bus/od/tables.py - 121 lines

The tidy tables: one row per trip, and one row per trip and stop.

These are the input every other module in this package reads, so they are kept free of aggregation: a value here is what a single trip did, never a sum over trips.

minutes is a nullable integer rather than the float a missing value used to force: a dash in the timetable is the absence of a clock, not a fractional one.

Public API:

  • func stop_times_frame - The full tidy timetable: one row per trip and stop.
  • func trips_frame - One row per trip, with its endpoints and its span.

src/inmotion/bus/od/pairs.py - 231 lines

The OD relation: every ordered stop pair a rider can ride directly.

One implementation, shared by the supply matrices and the synthetic demand. It used to exist twice — once in pandas here, once in polars in :mod:inmotion.bus.demand — held together by a parity test. A second answer is not a safety net once both can drift, so there is now one.

The relation derives from the timetable alone, which is why it lives here rather than with the demand model: the supply decides which pairs exist, the demand decides how many people are on them.

Pairs are enumerated per trip, so a row is a direct ride rather than a connection, and the band is stamped on each trip before the group is aggregated. Banding afterwards, from the group’s earliest departure, would file a whole day of service under one morning band.

per_trip_pairs is that enumeration; od_pairs is one projection of it, and :mod:inmotion.bus.od.timeline is the other. Both stamp their own time key on the same rows, which is why they agree cell by cell.

Public API:

  • func dedupe_calls - Drop a call that repeats the previous stop at the same minute.
  • func per_trip_pairs - Every ordered stop pair one trip serves, one row per trip and pair.
  • func stop_dictionary - One name per stop id: the dictionary’s, plus a fallback for its gaps.
  • func name_stops - Replace the pair relation’s stop names with the dictionary’s own.
  • func with_time_keys - Stamp each pair with the service group and band of its own departure.
  • func od_pairs - Every reachable ordered stop pair, aggregated over the trips serving it.

src/inmotion/bus/od/matrix.py - 61 lines

The matrices themselves: aggregated over lines, long or wide.

wide_matrix pivots with stop_id order, which is alphabetical and says nothing about the network. A route-ordered pivot belongs to the caller: it needs a stop order derived from the trips, not from the ids.

Public API:

  • func od_matrix - The OD matrix: direct trips per stop pair, by operator, service and band.
  • func wide_matrix - Pivot a long OD matrix into origins by destinations, absent cells as zero.

src/inmotion/bus/od/timeline.py - 224 lines

OD matrices by time interval: the same relation, sliced by departure.

A static matrix aggregates a whole service day into one number per stop pair. A dynamic OD matrix keeps the same rows and columns and adds when the movement happened: M_ij(t), the direct trips from i to j that left i inside interval t.

The interval is stamped on the departure from the row’s own origin, which is the instant the departure bands are keyed on. Two consequences worth naming: a trip is never split between slices — a 23:50 departure that arrives after midnight belongs to 23:00-24:00 in full — and a rider who boards mid-trip is counted in the slice they left in, not the one the vehicle started in.

Portuguese timetables keep printing past 24:00 for the last trips of the day, so the grid keeps counting past it: 24:00-25:00 is a real interval, not an error.

window is how long a slice lasts and step how far apart the slices start. The defaults partition the service day into hours, which is what makes the slices add up to the static matrix; a step shorter than the window overlaps them, so a trip is counted by every slice containing its departure and the slices must not be summed, while a longer one samples the day and leaves the gaps between slices unread.

Public API:

  • func window_starts - The start of every slice that contains minutes, latest first.
  • func interval_label - A slice as 07:00-08:00, keeping hours past 24.
  • func od_timeline - The dynamic OD matrix: direct trips per stop pair, per time interval.
  • func interval_matrices - Every interval of one operator and service group as a dense grid.
  • func read_stop_times - The tidy timetable the slices are cut from.
  • func write_timeline - Write the long timeline, and with wide a grid per interval.

src/inmotion/bus/od/validate.py - 75 lines

Invariants the tables have to hold before an OD matrix is worth anything.

Only checks that a wrong answer cannot hide behind: a time outside the service day, or a journey that arrives before it departs.

Public API:

  • func validate - Invariants the tables have to satisfy to be worth an OD matrix.
  • func validate_timeline - The slices of a day have to hold the flows of the day they were cut from.

src/inmotion/bus/build.py - 198 lines

Build the bus tables and the OD matrices from the two operator sites.

One pass, three stages: fetch (cached, so it only hits the network once), parse each operator with its own parser, then merge into the tidy tables and the OD matrices. The two parsers are independent, so a failure on one network still leaves the other’s tables written and reports what went wrong.

Public API:

  • class Report - What a build produced, and what it had to work around.
  • func parse_busway - Every BusWay trip, one line page at a time.
  • func parse_aveirobus - Every AveiroBus trip, one PDF at a time.
  • func collect - Fetch both operators and parse everything into trips.
  • func write_tables - Write the tidy tables, the OD matrices and the timeline, and return them.
  • func write_summary - Record the build’s counts and warnings next to the tables.
  • func run - Collect, write and summarise. Returns a process exit code.

src/inmotion/bus/viz.py - 467 lines

Figures that let the extracted routes be checked by eye.

Two routes are drawn per operator, and each figure carries three views of the same two routes:

  • an OD grid per route — the matrix restricted to that route, origins down the side and destinations across the top, coloured by how many direct trips connect the pair. A route read correctly is upper-triangular: nothing runs backwards and a stop is never its own destination.
  • a route ladder — the two routes’ stops in travel order, one ladder each, positioned at the elapsed time from their own first stop. Every stop the two routes share is joined by a connector. Where the extraction is wrong, the ladder is jagged and the connectors cross at random; where it is right, the two of a line’s directions mirror each other and the connectors are parallel.

Which two routes get drawn is not a choice: :func:similar_pairs ranks every pair of routes of an operator by how much of their stop list they share, and the top pair is plotted. The figure therefore shows the most comparable pair the data contains, and the console reports the pair and its agreement so the comparison can be judged rather than trusted.

Nothing is typed in by hand; every number comes from data/bus/processed.

Public API:

  • class Route - One route: a line, one direction, one service.
  • class SimilarPair - Two routes and how much they have in common.
  • func load_processed - The stop times and the per-line OD relation.
  • func route_profile - One route’s stops in travel order, with their elapsed time.
  • func similar_pairs - Every pair of one operator’s routes, ranked by shared stops.
  • func od_grid - One route’s OD matrix, as origins by destinations in travel order.
  • func plot_route_pair - Render one comparison figure and return its path.
  • func run - Draw the most similar pair of routes of each operator. Returns an exit code.

src/inmotion/bus/viz_config.py - 32 lines

Typed options for the bus-network figures.

Kept beside the pipeline like every other *_config.py in this repository, so the CLI holds no figure logic and the pipeline holds no argument parsing.

Public API:

  • class PlotConfig - Command-line options for the OD-matrix figures.

src/inmotion/bus/demand/config.py - 380 lines

One scenario’s parameters, and the space a batch samples from.

Every value that changes a number in the output lives here, which makes a run reproducible from its own scenario.json rather than from the command line that produced it. :class:ScenarioSpace turns ranges and choices into N scenarios with distinct seeds.

Public API:

  • func resolve_basemap - Turn :data:AUTO_BASEMAP into the best basemap this machine can draw.
  • class BusSize - One size of vehicle in the fleet, and how many of them there are.
  • class ScenarioConfig - Everything one generated scenario depends on.
  • func with_peak_share - Rescale a band profile so the two peaks hold share of the day.
  • class ScenarioSpace - The ranges a batch of scenarios is sampled from.
  • func sweep_configs - Every combination of the values a sweep file lists.

src/inmotion/bus/demand/allocate.py - 149 lines

Integer apportionment: splitting a whole number of people without losing one.

The demand across stop pairs, the assignment across the trips serving a pair, and the queue across the destinations wanting the last seats all use largest remainder, with ties broken by a seeded jitter so no rounding detail becomes a systematic bias. sampled is the fourth: drawing riders individually is what makes a day sparse with a long tail, where rounding the expected value of every cell would empty most of the matrix.

Public API:

  • func jitter - n reproducible uniform draws below 1, for breaking rounding ties.
  • func largest_remainder - Split total between weights, to integers that add back up to it.
  • func sampled - Draw total riders across alternatives, in proportion to weights.
  • func apportion - Add name: total split per keys group in proportion to weights.

src/inmotion/bus/demand/inputs.py - 206 lines

The supply tables a scenario is generated from, and the user’s stop attributes.

Only stop_times.csv and stops.csv are read: the first already carries every fact the model keys on, so trips.csv would be a second copy that could disagree with it. The optional attributes file is a trust boundary, checked before anything uses it.

Public API:

  • class Network - The supply side of a generated day: where the buses go, and when.
  • func read_network - Read the processed tables inmotion bus build writes.
  • func read_stop_attributes - The optional per-stop table, or an empty one with the full schema.
  • func check - What is worth reporting about the inputs, before a scenario is generated.

src/inmotion/bus/demand/model.py - 212 lines

Where the riders want to go: a gravity model over the pairs the network runs.

A_i = w_i * (1 + lines_i)^alpha — what a stop draws. D_ij = exp(-beta * t_ij) — how sharply a longer ride is avoided. T_ij ∝ A_i * A_j * D_ij, normalised to the day’s target and drawn per rider: rounding the expected value of every cell would empty most of the matrix, while drawing makes it sparse with a long tail, as real OD data is.

The dials are conventional, not calibrated: every number reproduces from scenario.json, and none of it is a forecast of Aveiro’s real ridership.

Public API:

  • class Demand - The generated demand for one day, and anything worth saying about it.
  • func attraction - How much each stop draws, from its own service level and any override.
  • func service_targets - The boardings each operator and service day has to add up to.
  • func pair_demand - The day’s demand per stop pair, on the pairs the network actually runs.
  • func generate - The demand of one scenario: the pairs, scaled to the day’s target.

src/inmotion/bus/demand/assignment.py - 232 lines

Which bus carries whom: demand spread over the trips serving each pair.

Each serving trip is weighted by its departure band, so demand follows the commutes; each trip then gets one of the fleet’s sizes, by the scenario’s fleet policy, and that size is what later limits how many of those riders fit.

The result is an intent — this many riders want this trip, from this stop, to that one. Whether they get on is the queue’s decision, in simulate.

Public API:

  • func ordered_fleet - The fleet smallest first, with ties settled by name so a run is stable.
  • class Assignment - The demand, per trip, and the fleet that has to carry it.
  • func band_preference - How strongly each departure attracts riders, from its own band.
  • func fleet_sizes - One bus size per trip, by the scenario’s fleet policy.
  • func trip_table - One row per scheduled trip: which line it runs, and when it starts.
  • func assign - Spread each pair’s demand over the trips serving it, then size the fleet.

src/inmotion/bus/demand/simulate.py - 382 lines

The queue at each stop, and the bus that either takes the riders or leaves them.

arrivals riders turn up for a departure; boarded (entry) is how many fit; alighted (exit) is who got off here; waiting (stay in the stop) is who is still standing there, and a later bus for their destination can still take them. What is left when the day’s last bus has gone is stranded, reported not dropped.

Two orderings are load-bearing: events follow the order buses arrive at each stop, not the order they left their first one, and each service group is a separate day, so a weekday queue never boards a weekend bus.

Public API:

  • class Flows - What one generated day moved: per trip and stop, per stop and hour.
  • func simulate - Run every generated service day’s buses over that day’s riders.

src/inmotion/bus/demand/instants.py - 95 lines

The flows on the 10-second grid the WiFi captures already use.

AA stayed inside the bus, BB stayed at the stop, BA boarded, AB alighted. Rows exist around a stop visit — window seconds either side — because that is all a capture at that stop can see.

Public API:

  • func clock - HH:MM:SS on a continuous scale, keeping hours past 24.
  • func instants - One row per stop visit and instant, in the label vocabulary of the data.

src/inmotion/bus/demand/matrices.py - 161 lines

The passenger OD matrices: the supply tables’ keys, one measure apart.

od_matrix.csv counts the departures a rider could take; these count the riders who took them. The static matrix and its hourly slices are built together, and validate holds the second to adding back up to the first.

Public API:

  • func passenger_matrix - Boardings per stop pair, by operator, service day and departure band.
  • func passenger_timeline - The same boardings per stop pair, sliced by when the ride left.
  • func wide - Pivot a long matrix into origins by destinations, absent cells as zero.

src/inmotion/bus/demand/validate.py - 299 lines

The invariants a generated day has to hold, and the supply it must trace to.

A synthetic day can be wrong in ways that look plausible — a bus over capacity, a queue boarding riders who were never there, a matrix that does not add up. Each is checked here, including that every trip, call and clock came from the scrape, and a failure is reported rather than written.

Public API:

  • func check_flows - Every identity a trip and a stop have to satisfy, on the flow tables.
  • func check_conservation - The day’s totals: what was generated, what boarded, what was left.
  • func check_demand - The demand matrix itself: whole riders, on pairs that exist, non-negative.
  • func check_timeline - The slices of a day have to hold the boardings of the day they came from.
  • func check - Every invariant, in one call, for a run to attach to its report.
  • func check_provenance - Every vehicle movement must trace back to the scraped timetable.

src/inmotion/bus/demand/coords.py - 672 lines

Stop coordinates, resolved from OpenStreetMap and never invented.

One cached Overpass request covers every bus stop of the region; matching then happens locally, cheapest tier first. Each stop records the tier that placed it — manual, exact, expanded, tokens, fuzzy, sibling, nominatim — or none, with the coordinates left blank and the stop listed in stops_unresolved.csv. A guessed position would put a phantom stop on the map and a plausible one in an analysis, so a gap is reported, not filled.

Public API:

  • class Resolution - What the matcher did, per stop, and how the day’s coordinates look.
  • func expand - The canonical form of a name, with its abbreviations spelled out.
  • func strip_parenthetical - A name without its qualifier: Esmoriz (Avenida da Praia 3).
  • func side_base - A name without a trailing direction qualifier, for sibling matching.
  • func index_frame - The Overpass response as a table: one row per named stop.
  • func fetch_index - Every named bus stop of the region, from the cache when it is there.
  • func nominatim - The best web match for one stop name, or nothing.
  • class Index - The OpenStreetMap stops, bucketed by every way a name can be compared.
  • func build_index - Bucket the OSM stops once, so each tier is a lookup rather than a scan.
  • func match - Place every stop of the network, or leave it blank and say so.
  • func coords_schema - The coordinate table’s columns and types.
  • func cluster - Group stops that are the same place, whichever operator runs them.
  • func write - Write the coordinate table, the clusters and the unresolved list.
  • func geocode - Place every stop of the network, writing the tables bus demand reads.

src/inmotion/bus/demand/map.py - 658 lines

The generated day as GIS layers, and as the payloads the pages draw.

Coordinates come from coords, so only placed stops appear. Two GeoJSON files serve a GIS; the rest feeds the three viewers in pages.

Public API:

  • func stop_features - One point per placed stop, carrying what the flows say about it.
  • func flow_features - The busiest OD relations as straight lines between their two stops.
  • func network_legs - Every leg between two consecutive stops of a trip, once, with coordinates.
  • func hour_window - The hours the day touches, and their labels, past midnight included.
  • func basemap_payload - Every basemap the viewer may switch to, and whether this machine can draw it.
  • func placed_count - How many stops have a position, which is what the map needs to exist.
  • func require_key - Refuse a keyed basemap whose key this machine does not have.
  • func cube_payload - The OD relation as a space-time cube: origin, destination, and the clock.
  • func replay_payload - One bus route’s day, as an animation the page can drive.
  • func write_replay - Write the route-replay page, when there is a route worth replaying.
  • func write_geojson - A FeatureCollection, written the way any GIS expects to read it.
  • func write - Write the two GeoJSON files and the page, when coordinates allow it.
  • func write_cube - Write the space-time cube page, when coordinates allow one.

src/inmotion/bus/demand/pages.py - 1746 lines

The three pages the generator writes: the map, the cube, the replay.

Each is one self-contained file that works when double-clicked. Every colour and space comes from the tokens in one place, every bulk toggle carries its inverse, and no layout scrolls sideways.

Public API:

  • func render_cube - The space-time cube page: the OD relation as a tensor you can turn.
  • func render_map - The map page: the day’s flows on the ground, with filters and a clock.
  • func render_replay - The replay page: a route’s day, its buses moving, its people waiting.

src/inmotion/bus/demand/build.py - 473 lines

Generate one scenario end to end, or a batch of them, and write them out.

Read the supply, lay the demand over the pairs the network runs, spread it across the trips, run the buses over the queues, cut the result into the matrices, check every invariant — including that the supply is the scraped one — then write. Each scenario lands in its own directory with the configuration that produced it, and a batch adds index.csv for comparing them.

Public API:

  • class Report - What a generated scenario produced, and what it had to work around.
  • func digest - The sha256 of each input file, so a scenario names the tables it read.
  • func stop_coordinates - Coordinates per stop: the geocoded table, with attributes as overrides.
  • func run - Generate one scenario and write its tables. Returns what it produced.
  • func pair_relation_grid_axis - Every stop of one operator, as the axis a dense grid is laid out on.
  • func run_space - Generate a batch of scenarios, sharing the supply tables between them.
  • func index_schema - The types of index.csv, so an empty batch still writes a header.

src/inmotion/quant/spec.py - 151 lines

Quantization schemes.

Weight-only quantization: the weights are stored at low precision, activations stay in fp32. That is the right trade here because weights dominate this workload by 9x-2424x over activations (a full inference window is 10 timesteps x 4 channels = 160 bytes), so the entire memory problem is the weights. Keeping activations in fp32 also removes the need for calibration data, which keeps Q4 and Q8 exact and reproducible rather than data-dependent.

Rounding is specified explicitly. NumPy’s np.round rounds half to even, while Rust’s f32::round rounds half away from zero; leaving that implicit would make the Python reference and the Rust kernels disagree on roughly one element in a thousand, which is exactly the kind of drift the golden-vector tests exist to catch.

Public API:

  • class Granularity - How many weights share one scale/zero-point pair.
  • class Rounding - Rounding mode applied before the integer cast.
  • class QuantSpec - A weight-quantization scheme.
  • func resolve - Look up a preset by name, or parse q<N> shorthand.

src/inmotion/quant/reference.py - 203 lines

Normative quantization math, in numpy.

This module is the specification. The Rust kernels in rust/inmotion-core must reproduce it exactly, and tests/test_quant_reference.py pins the properties that make “exactly” checkable:

  1. dequantize is exactly (q - zero_point) * scale in float32;
  2. re-quantizing a dequantized tensor is idempotent (no compounding drift);
  3. rounding ties follow the declared mode, because numpy rounds half to even while Rust rounds half away from zero;
  4. granularity is honoured, so per-group is never silently coarser than asked;
  5. the byte accounting uses the packed size, not one int8 per value.

scale and zero_point are stored in the reduced shape that broadcasts against the codes, so no reader has to re-derive it:

=============== ========================================== ================== granularity reduced shape dequant broadcast =============== ========================================== ================== per_tensor () scalar per_channel (1, .., D, .., 1) with D=shape[axis] direct per_group (*shape[:-1], ceil(D/g)) scale[..., None] =============== ========================================== ==================

Public API:

  • func n_groups_for - Number of groups the last axis is divided into, rounding up.
  • class QuantizedTensor - Integer codes plus the metadata needed to reconstruct the float values.
  • func quantize - Quantize a float tensor into integer codes and per-group metadata.
  • func dequantize - Reconstruct float32 values from codes and metadata.

src/inmotion/quant/packing.py - 145 lines

Bit-packing of integer codes.

Storing a 4-bit code in an int8 wastes half the memory, and this workload is memory-bound, so the packing is not an optimization — it is the point. Q4 must cost half of Q8 and Q2 a quarter of it, or the exercise is pointless.

Codes are biased to unsigned so the byte stream holds no negatives, and written LSB-first: element i occupies bits [i*bits, (i+1)*bits) of the byte stream, so for 4-bit codes element 0 is the low nibble of byte 0 and element 1 the high nibble.

The bias is 2**(bits-1) for a symmetric scheme, whose codes are signed and run [-2**(bits-1), 2**(bits-1)-1]. An asymmetric scheme emits codes that are already unsigned ([0, 2**bits-1]), so its bias is zero; applying the signed bias there would push the top code out of range, which is why q1 could not be exported until this parameter existed.

Biasing means the on-device dequantization stays a single formula with no extra per-weight work: because q = u - bias,

(q - zero_point) * scale == (u - (zero_point + 2**(bits-1))) * scale

so the bias is folded into the zero point once, at export, by :func:fold_bias_into_zero_point.

Public API:

  • func n_bytes_for - Number of bytes needed to pack count codes of bits each.
  • func fold_bias_into_zero_point - Return the zero point that pairs with biased unsigned codes.
  • func code_bias - Offset added to a code to make it unsigned.
  • func pack - Pack int8 codes into a uint8 byte stream, LSB-first.
  • func unpack - Inverse of :func:pack. Returns int8 codes.

src/inmotion/quant/model.py - 272 lines

Weight-only quantization of a model, and honest size accounting.

Only the weights of Linear and Conv1d/Conv2d layers — the tensors with two or more dimensions. Everything else stays fp32:

  • biases, LayerNorm/BatchNorm weights and running statistics are 1-D and a tiny share of the parameters; quantizing them costs accuracy and saves nothing;
  • learned tokens and position embeddings (mask_token, query_tokens, pos_embed) are initialization state, not weights to be approximated.

Activations stay fp32. That is deliberate: activations peak at ~10 KB against 0.57-2.35 MB of weights, so keeping them fp32 costs nothing measurable and removes the need for calibration data.

:func:apply replaces each weight with dequantize(quantize(w)). Running the model afterwards measures exactly what a device does, because the device also reconstructs fp32 weights from codes before the matmul. No forward pass needs to be rewritten, so the measurement cannot drift from the model.

Public API:

  • class TensorRecord - One quantized weight tensor.
  • class QuantReport - Size and error summary for one (model, spec) pair.
  • func quantize_tensor - Quantize one weight tensor.
  • func apply - Return a model whose quantizable weights have been quantized and rebuilt.
  • func apply_cast - Round every parameter and buffer to a narrower float format.

src/inmotion/quant/evaluate.py - 360 lines

Accuracy under quantization, measured on data/processed/dataset.csv.

Every number this module produces is on dataset.csv. It is not on dataset.icaisf.csv, so it is not comparable with the MCC values published for the icaisf variant (lejepa 0.8850, t_jepa 0.8694, ts_jepa 0.8785, cf_jepa 0.8661, sigreg 0.8858). The two splits differ in size and in score, so the numbers are not interchangeable.

Otherwise the harness reuses the same splits and the same feature pipeline the models were trained with:

  • features from DLDataLoader with the model’s own rich flag, because the scaler is fitted inside it and using a different fit would change the inputs;
  • the 80/20 stratified split from inmotion.data.splits, the convention every reported number uses.

The first thing the sweep does is evaluate the unquantized model. If that does not reproduce the recorded MCC, the harness is wrong and every later number is meaningless, so :func:check_baseline fails loudly instead of publishing a table nobody can trace.

Public API:

  • class EvalRow - One (model, precision) measurement.
  • func load_split - Features, labels and test indices, using the training convention.
  • func load_preprocess - The fitted StandardScaler the training loader uses for raw RSSI.
  • func measure_producer - (quantized model, bits, total bytes, quantized bytes, max weight error).
  • func evaluate - Measure one (model, precision) pair on the test split.
  • func check_baseline - Confirm fp32 reproduces the recorded MCC on the baseline dataset.
  • func sweep - Evaluate every (model, precision) pair and optionally write a CSV.
  • func write_csv - Write the sweep as one row per measurement.
  • func write_json

src/inmotion/quant/export.py - 846 lines

Export a model to a portable artifact a non-Python runtime can execute.

The artifact is a directory:

model.safetensors tensors, quantized ones packed
meta.json architecture, quantization spec, tensor index

ONNX Runtime is a poor fit for an MCU and heavy even for an x86 router, and the graphs here are small and fixed-shape. A flat tensor bag plus a small JSON description is easier to audit and is what embedded runtimes actually do.

Two source conventions are resolved here rather than in every Rust reader:

in_proj_weight is split into separate Q, K and V tensors. PyTorch packs them into one (3*d_model, d_model) matrix; splitting means the Rust side does not have to know that packing convention.

weight_norm is folded into an ordinary weight. It is what broke FX tracing and ONNX export for tcn/deep_stack, and folding removes the problem instead of working around it.

dtype="fp32" writes plain float weights. Use it to verify that the port is correct before introducing quantization, so a mismatch can only be one of the two things.

quant=QuantSpec writes packed integer codes plus scales and zero points. The Rust reader dequantizes exactly as :mod:inmotion.quant.reference does, so parity holds by construction and is asserted by the golden-vector tests.

Public API:

  • class ExportReport - What was written and how big it is.
  • func write_onnx - Export the checkpoint as a generic ONNX graph for inmotion-onnx.
  • func codebook_values - Dequantize a v2 codebook tensor: codebook[code] * absmax[i // block].
  • func dequantize_artifact - The float weights an artifact stands for: (code - zero_point) * scale.
  • func rebuild_state_dict - The model’s OWN state dict, from artifact-shaped tensors.
  • func artifact_space - The tensors an artifact would contain, before quantization.
  • func model_with_producer - The model carrying a producer’s quantization in its weights.
  • func resolve_producer - The per-weight quantizer and the quant metadata block for a producer.
  • func export - Write model_name as a portable artifact directory.
  • func write_golden - Write input/output pairs for a non-Python runtime to reproduce.

src/inmotion/models/registry.py - 377 lines

Model registry — the single source of truth for loadable models.

A :class:ModelSpec records everything needed to rebuild a saved model:

factory which architecture constructor to call (see factories.py) arch the keyword arguments for it prefix state-dict wrapping, if the checkpoint was saved from a wrapper params expected parameter count, used as a checksum

Loading is deliberately strict. The previous code called load_state_dict(..., strict=False), which turns an architecture mismatch into a silently random subset of weights — the model still runs and still returns numbers, so the error is invisible. :func:load refuses by default.

Adding a model is data entry, not code. Use adopt (see inmotion model adopt) to infer a spec from a checkpoint’s tensor shapes.

Public API:

  • class ModelSpec - A rebuildable saved model.
  • func spec_names - Names of every registered model.
  • func by_name - Look up a spec by name, optionally overriding its checkpoint path.
  • func all_specs - Every registered spec, including adopted ones.
  • func load - Build spec and load its checkpoint.
  • func param_count - Parameter count of the architecture as built from spec.arch.

src/inmotion/models/factories.py - 751 lines

Architecture factories.

Each factory takes only keyword arguments and is registered in FACTORIES under a stable name. A checkpoint’s architecture is therefore data (an arch dict in the registry or a checkpoint sidecar), not code that has to be reverse-engineered from tensor shapes.

The configurations here were originally recovered by matching saved weight shapes; they are pinned by tests/test_checkpoint_contract.py, which asserts every documented checkpoint still loads with strict=True and matches the parameter count published for it.

Public API:

  • func lejepa - LeJEPA classifier (paper after-HPO winner: d_model=128, ff=256, layers=4).
  • func t_jepa - T-JEPA classifier (paper after-HPO winner: d_model=128, ff=256).
  • func ts_jepa - TS-JEPA classifier (paper: embed_dim=256, layers=4, ff=512).
  • func cf_jepa - CF-JEPA classifier (paper after-HPO: embed 256, layers 3, ff 256).
  • func sigreg - SIGReg classifier wrapped so it returns logits only.
  • func mamba3_cnn - Mamba-3 CNN hybrid.
  • func mamba3_tcn - Mamba-3 TCN hybrid.
  • func mamba3_transformer - Mamba-3 transformer hybrid.
  • func mamba3_multiview - Mamba-3 multi-view hybrid (checkpoint uses d_model=256).
  • func deep_stack - Deep stack ensemble, 10 heterogeneous bases.
  • func build - Instantiate factory with arch keyword arguments.
  • func rnn - Plain RNN classifier.
  • func gru - GRU classifier, optionally with attention pooling.
  • func lstm - LSTM classifier, optionally with attention pooling.
  • func bilstm - Bidirectional LSTM classifier.
  • func tcn - Temporal convolutional network classifier.
  • func mamba - Mamba (selective SSM) classifier.
  • func transformer - Transformer encoder classifier.
  • func cnn - Multi-branch residual CNN classifier.
  • func cnn2d_rnn - 2-D CNN front-end feeding an RNN.
  • func meta_fusion - RNN plus metadata (noise flag, concurrent path) fusion classifier.
  • func voting_ensemble - Averaging ensemble over nested member specs.
  • func stacking_ensemble - Stacking ensemble: base members feed a learned meta-learner.
  • func lejepa_pretrain - Base LeJEPA world model (no classification head).
  • func t_jepa_pretrain - Base T-JEPA world model.
  • func ts_jepa_pretrain - Base TS-JEPA world model.
  • func cf_jepa_pretrain - Base CF-JEPA world model.

src/inmotion/models/checkpoint.py - 166 lines

Checkpoint I/O with a JSON sidecar.

A .pt file alone is not a usable artifact: it does not say which architecture it belongs to, how the inputs were scaled, or what the output classes mean. :class:Sidecar carries that information next to the weights, and :func:save / :func:load keep the two in sync.

Layout written by :func:save::

<dir>/model.pt weights
<dir>/model.json Sidecar
<dir>/preprocessing.json FeaturePipeline metadata
<dir>/preprocessing.npz FeaturePipeline statistics

Loading verifies the sidecar against the weights: the architecture must build, the state dict must load with strict=True, and the parameter count must match. Anything else raises rather than returning a partly-random model.

Public API:

  • class Sidecar - Everything needed to rebuild and interpret a saved model.
  • func save - Write weights, sidecar and (optionally) preprocessing state.
  • func read_sidecar
  • func load - Rebuild the model, its sidecar and (if present) its preprocessing state.
  • func sidecar_for_spec - Build a sidecar from a registry :class:ModelSpec.

src/inmotion/models/adopt.py - 775 lines

Infer a :class:~inmotion.models.checkpoint.Sidecar from an untagged checkpoint.

Existing checkpoints predate the sidecar convention, so their architecture has to be recovered. Two strategies are tried in order:

  1. Signature match. Every registered spec’s module is built and its state-dict key set and shapes are compared with the checkpoint’s. An exact match identifies the architecture with no guessing.
  2. Shape-driven search. For a checkpoint nothing in the registry matches, a bounded per-family grid is searched until a configuration loads with strict=True. Dimensions are read out of the tensor shapes rather than hardcoded.

If neither succeeds, the error lists what was tried and how each candidate differed, so a factory can be added deliberately instead of the model being loaded with strict=False and left partly random.

Checkpoints may or may not carry a wrapper prefix ("c." for the JEPA classifier, "m." for :class:~inmotion.models.wrappers.TupleWrap). Detection works on plain keys; the prefix a factory needs is applied only when checking a candidate, so a raw SIGReg checkpoint and a re-saved wrapped one are both recognised.

Public API:

  • func read_state - Load a state dict, accepting a raw dict or a module checkpoint.
  • func plain_state - Strip any wrapper prefix so detection sees canonical child names.
  • func match_all - Every registered architecture that reproduces plain exactly.
  • func match_registry - First registered architecture that reproduces plain exactly.
  • func search_family - Search the per-family grids for a strictly-loadable configuration.
  • func resolve_plain - Resolve a plain (prefix-stripped) state dict to (factory, arch, prefix).
  • func looks_like_pretrain - True when state is a pre-training bundle rather than a state dict.
  • func describe_pretrain - A one-line description of a pre-training bundle.
  • func spec_for_checkpoint - A :class:ModelSpec for any checkpoint, architecture inferred.
  • func resolve_model - A registered name, or a path to any checkpoint.
  • func infer - Recover a :class:Sidecar for an untagged checkpoint.
  • func infer_many - Adopt every checkpoint in paths, recording failures instead of raising.

src/inmotion/models/wrappers.py - 55 lines

Thin nn.Module adapters and state-dict key helpers.

Some checkpoints were saved from a wrapper module, so their keys carry a prefix that the bare module does not have (or vice versa). These helpers normalise that without the callers needing to know which case they are in.

Public API:

  • class TupleWrap - Expose logits of a model that returns (logits, latents).
  • func strip_prefix - Remove prefix from every key that starts with it.
  • func add_prefix - Prepend prefix to every key.
  • func normalise_state - Return state shaped the way the target module expects.

src/inmotion/cli/__init__.py - 77 lines

The inmotion command-line interface.

One package, one module per command group:

model inspect, verify, predict and adopt checkpoints datasets dataset versions, provenance and checksums data build and clean datasets (export, merge, clean, augment) bus scrape the Aveiro bus networks and build the OD matrices train train models (classification, dl, exotic, hpo-paper) evaluate evaluate and combine models (ensemble, checkpoints, shap, importance) analyze analyse results (seeds, interference) plots regenerate figures from saved results edge the edge-quantization campaign on the wavecom routers doctor report on the environment and the artifact store

Each command builds a typed RunConfig and calls the pipeline’s run(). The CLI holds no pipeline logic, and the pipelines hold no argument parsing, so either side can change without touching the other.

Public API:

  • func main - [bold]inMotion[/] — WiFi RSSI mobility classification.

src/inmotion/cli/model.py - 292 lines

inmotion model - inspect, verify, predict and adopt checkpoints.

Public API:

  • func model_list - List every registered model.
  • func model_info - Show the architecture and provenance of one model.
  • func model_verify - Strict-load every model and check it against its recorded parameter count.
  • func model_predict - Run a trained model over a CSV of RSSI windows.
  • func model_adopt - Recover a checkpoint’s architecture and write a sidecar.
  • func model_inventory - Adopt every checkpoint under a directory and report what is recoverable.

src/inmotion/cli/datasets.py - 131 lines

inmotion datasets - dataset versions, provenance and checksums.

Public API:

  • func datasets_list - List recorded dataset versions, newest lineage last.
  • func datasets_show - Show lineage and label provenance for one dataset version.
  • func datasets_verify - Re-check every dataset against its recorded checksum and row count.
  • func datasets_manifest - Regenerate the manifest’s measured fields, or print it.
  • func datasets_resolve - Print the path of a dataset version, warning when it is not trustworthy.

src/inmotion/cli/data.py - 99 lines

inmotion data — build and clean datasets.

Public API:

  • func export - Pivot 10-second captures into one row per route.
  • func merge - Concatenate the interim CSVs and label concurrent-noise rows.
  • func clean - Quantify which devices or samples carry inconsistent labels.
  • func augment - Add class-conditioned noise and mixup rows, flagged synthetic.

src/inmotion/cli/bus.py - 392 lines

inmotion bus — scrape the Aveiro operators and build the OD matrices.

Public API:

  • func fetch - Populate data/bus/raw and the checksum manifest.
  • func timeline - Read the processed stop times and write one matrix per time interval.
  • func plot - Render one figure per operator: both routes’ OD grids and route ladders.
  • func build - Fetch if needed, parse, then write data/bus/{interim,processed}.
  • func geocode - Resolve stop coordinates once, so a scenario run stays offline.
  • func demand - Generate flows for the processed network and write them under data/bus/scenarios.

src/inmotion/cli/train.py - 277 lines

inmotion train — train models.

Public API:

  • func dl - Train the supervised deep-learning models and their ensembles.
  • func exotic - Pretrain and fine-tune a world model, or train SIGReg / a Mamba-3 hybrid.
  • func classification - Run the classical machine-learning comparison.
  • func hpo_paper - Rebuild the HPO-best models, since the Optuna databases were deleted.

src/inmotion/cli/evaluate.py - 159 lines

inmotion evaluate — evaluate and combine models.

Public API:

  • func ensemble - Combine saved checkpoints with Caruana forward selection.
  • func mega_ensemble - Combine DL, JEPA, classical ML and TabPFN members into one model.
  • func checkpoints - Evaluate every checkpoint in a directory with extended metrics.
  • func shap - Attribute predictions to the 18 feature channels.
  • func feature_importance - Shuffle each feature channel and measure the MCC drop.

src/inmotion/cli/analyze.py - 47 lines

inmotion analyze — analyse results across seeds and routes.

Public API:

  • func seeds - Compute cross-seed statistics and ranking stability.
  • func interference - Quantify how a concurrent device’s route degrades classification.

src/inmotion/cli/plots.py - 72 lines

inmotion plots — regenerate figures from saved results.

Public API:

  • func classical - Rebuild the figures without retraining.
  • func dl - Rebuild the DL figures without retraining.

src/inmotion/cli/quantize.py - 452 lines

inmotion quantize — quantize models and measure what it costs.

Public API:

  • func formats - Show each scheme, its bit width and its storage granularity.
  • func show - Report the size, compression and weight error for one scheme.
  • func producers_cmd - Which quantizer made a number matters, so they are named, not implied.
  • func export_cmd - Export an artifact plus the golden vectors a Rust runtime must reproduce.
  • func evaluate - Sweep models x formats and write one row per measurement.
  • func run_cmd - Load the artifact through the quantized runtime and classify windows.

src/inmotion/cli/doctor.py - 41 lines

inmotion doctor - report on the environment and the artifact store.

Public API:

  • func doctor - Report on the environment and the artifact store.

src/inmotion/pipelines/classification.py - 254 lines

Main script for WiFi Fingerprinting Classification Analysis.

This script runs a comprehensive analysis of various ML classifiers for predicting location classes based on WiFi RSSI fingerprints.

Public API:

  • func save_detailed_classifier_reports - Save detailed per-classifier reports to a CSV file.
  • func run - Execute the pipeline.

src/inmotion/pipelines/dl/__init__.py - 42 lines

DL pipeline: supervised baselines, HPO/NAS, MoE and DeepStack.

Split from a single 1,700-line module into:

config model lists and the typed :class:RunConfig devices GPU pool selection and seeding builders model construction, including from saved HPO parameters workers spawn-safe worker functions used by ProcessPoolExecutor pipeline :func:run, the orchestration

No public classes or functions; this module provides data or constants consumed elsewhere.

src/inmotion/pipelines/dl/config.py - 82 lines

DL pipeline configuration: model lists and run options.

Public API:

  • class RunConfig - Typed options for the DL pipeline.

src/inmotion/pipelines/dl/devices.py - 28 lines

Device pool selection and seeding.

Public API:

  • func set_seed

src/inmotion/pipelines/dl/builders.py - 297 lines

Model construction for the DL pipeline.

No public classes or functions; this module provides data or constants consumed elsewhere.

src/inmotion/pipelines/dl/workers.py - 723 lines

Spawn-safe worker functions for parallel training and HPO.

No public classes or functions; this module provides data or constants consumed elsewhere.

src/inmotion/pipelines/dl/pipeline.py - 626 lines

DL pipeline orchestration.

Public API:

  • func run - Execute the DL pipeline.

src/inmotion/pipelines/exotic/__init__.py - 37 lines

World-model (self-supervised) pipeline.

Split from a single 1,950-line module into modules with one job each:

config the typed :class:RunConfig (54 options) devices device selection and seeding data pretraining and supervised data loading builders the model family and its dispatch table training stage-1 pretraining, linear probing, stage-2 fine-tuning hpo shared Optuna helpers and per-trial logging hpo_jepa the JEPA search (also holds the Pareto machinery) hpo_sigreg the SIGReg search hpo_mamba3 the Mamba-3 search pipeline :func:run, the orchestration

No public classes or functions; this module provides data or constants consumed elsewhere.

src/inmotion/pipelines/exotic/config.py - 78 lines

Options for the world-model pipeline.

Public API:

  • class RunConfig - Typed options for the exotic pipeline.

src/inmotion/pipelines/exotic/devices.py - 26 lines

Device selection and seeding.

Public API:

  • func set_seed
  • func resolve_device

src/inmotion/pipelines/exotic/data.py - 109 lines

Data loading for pretraining and supervised training.

Public API:

  • func load_pretrain_data - Load data for SSL pretraining.
  • func load_supervised_data - Load data for supervised training.

src/inmotion/pipelines/exotic/builders.py - 164 lines

Model construction for the world-model family.

No public classes or functions; this module provides data or constants consumed elsewhere.

src/inmotion/pipelines/exotic/training.py - 456 lines

Stage-1 pretraining, probing and stage-2 fine-tuning.

Public API:

  • func pretrain_jepa - Pretrain a JEPA model (T-JEPA or TS-JEPA).
  • func finetune_jepa - Fine-tune a pretrained JEPA encoder for classification.

src/inmotion/pipelines/exotic/hpo.py - 161 lines

Shared Optuna helpers and per-trial logging.

Public API:

  • class SIGRegWrapper - Wraps SIGRegClassifier so Trainer can use it with compute_loss.

src/inmotion/pipelines/exotic/hpo_jepa.py - 428 lines

Hyperparameter search for the JEPA models.

No public classes or functions; this module provides data or constants consumed elsewhere.

src/inmotion/pipelines/exotic/hpo_sigreg.py - 121 lines

Hyperparameter search for SIGReg.

No public classes or functions; this module provides data or constants consumed elsewhere.

src/inmotion/pipelines/exotic/hpo_mamba3.py - 109 lines

Hyperparameter search for the Mamba-3 hybrids.

No public classes or functions; this module provides data or constants consumed elsewhere.

src/inmotion/pipelines/exotic/pipeline.py - 284 lines

World-model pipeline orchestration.

Public API:

  • func run - Execute the exotic (world-model) pipeline.

src/inmotion/pipelines/ensemble.py - 272 lines

Greedy ensemble selection over existing checkpoints.

Research-backed combiner: Caruana’s forward selection with replacement (“ensemble selection from libraries of models”), which the 2026 TFM-ensembling study recommends as the practical default over plain weighted averaging and stacking. It adds the base whose inclusion maximizes validation accuracy at each step, with replacement, so diverse-but-redundant models can each earn weight without a meta-learner.

Add a model in one line by appending a dict to MODELS: { “name”: “foo”, “rich”: False, # True if it needs 18-channel rich features “build”: lambda: build_foo(), # returns an nn.Module, logits already loaded }

Run: uv run inmotion ensemble –data data/processed/dataset_augmented3.csv –seed 42

Public API:

  • func run - Execute the pipeline.

src/inmotion/pipelines/mega_ensemble.py - 1057 lines

Mega-ensemble across every model family.

Combines DL checkpoints, the JEPA family, classical ML (KNN/CatBoost/GP/LR) and TabPFN via OOF stacking, with temperature calibration and CE-based bagged Caruana selection.

Research-backed combiner pipeline. The combiner choices and their rationale: A. Collect OOF + test probabilities for every member under the same 70/10/20 split B. Per-member temperature calibration on the validation fold C. CE-based bagged Caruana (ensemble selection with replacement) D. Regularized-LR stacker over the calibrated OOF matrix E. Compare: greedy-weighted, logit-avg, rank-avg, entropy-weighted, LR stack

Usage: MAMBA_SSM_AVAILABLE=0 inmotion mega-ensemble –data data/processed/dataset_augmented3.csv –seed 42

Note: set MAMBA_SSM_AVAILABLE=0 to skip the (hang-prone) mamba_ssm CUDA extension import and use the pure-PyTorch fallback for Mamba-based models.

Public API:

  • func rocket_features - MiniRocket-style random convolutional features + PPV pooling.
  • func catch22_features - Hand-crafted time-series statistics per channel (catch22-inspired subset).
  • func fit_temperature - Fit a single temperature scalar to minimize NLL on the calibration set.
  • func run - Execute the pipeline.

src/inmotion/pipelines/hpo_paper.py - 312 lines

Train the paper’s HPO-best models using configs from docs/icaisf/hpo_supplementary.md.

The original Optuna DL DBs (optuna_dl_*.db) were deleted, so the DL pipeline can no longer skip HPO. This script rebuilds each HPO-best model from the paper’s documented config and trains it with the Trainer, saving checkpoints that the mega-ensemble can load directly.

Configs sourced from docs/icaisf/hpo_supplementary.md (best val MCC in parens): HPO GRU 0.9030 HPO TCN 0.8526 HPO Mamba 0.8506 HPO CNN 0.8488 HPO LSTM 0.8388 HPO BiLSTM 0.8410 HPO RNN 0.6402

Usage: MAMBA_SSM_AVAILABLE=0 inmotion hpo-paper –data data/processed/dataset.csv –seed 42 # –models only gru tcn (subset)

Public API:

  • func run - Execute the pipeline.

src/inmotion/evaluation/checkpoints.py - 827 lines

Retroactive DL checkpoint evaluation — produce extended results CSV with per-class metrics.

Usage: uv run inmotion evaluate-checkpoints –seed 42 –data data/processed/dataset.csv

Public API:

  • func set_seed
  • func evaluate_single_checkpoint - Load a checkpoint, build model, evaluate. Returns metrics dict or None.
  • func run - Execute the pipeline.

src/inmotion/evaluation/shap.py - 218 lines

Game-Theoretic SHAP Feature Channel Attribution for WiFi ISAC Models.

Evaluates Shapley Additive exPlanations (SHAP) across the 18-channel feature hierarchy (or the 4-channel base hierarchy) for the time-series world models: TS-JEPA, LeJEPA, CF-JEPA, T-JEPA and SIGReg.

Usage: inmotion shap –data data/processed/dataset.csv –checkpoint backup/ts_jepa_ft_seed42.pt –samples 50 –nsamples 150

Public API:

  • func explain_channels_shap - Compute channel-level Shapley values across test sequences.
  • func run - Execute the pipeline.

src/inmotion/evaluation/feature_importance.py - 612 lines

Permutation feature importance for DL movement classification models.

Computes MCC-drop when each of the 4 engineered channels × 10 timesteps (= 40 features) is independently shuffled, for CNN, TCN, GRU, and Mamba.

DeepStackEnsemble is skipped unless all 8 DS base-variant checkpoints already exist under models/dl/ (it requires 9 pre-trained sub-models).

Output plots (publication-quality PDF, 600 DPI, husl palette): docs/icaisf/paper/images/feature_importance_dl.pdf heatmap docs/icaisf/paper/images/feature_importance_channels_dl.pdf bar chart

Public API:

  • func set_seed
  • func get_device
  • func setup_plot_style - Apply DLVisualizer-compatible plot style.
  • func build_model - Construct a model matching _build_model_by_name in the DL pipeline.
  • func train_or_load - Train model from scratch or load saved checkpoint.
  • func permutation_importance - Return (importance[N_CHANNELS, N_TIMESTEPS], baseline_mcc).
  • func plot_heatmap - Publication-quality heatmap: 4 channels × 10 timesteps, avg across models.
  • func plot_per_model_heatmaps - Multi-panel figure: one 4x10 heatmap per model.
  • func plot_channel_bars - Channel-level bar chart: mean importance +/- std across timesteps & models.
  • func run - Execute the pipeline.

src/inmotion/analysis/seeds.py - 440 lines

Analyze and combine results from multi-seed experiments.

This script reads results from experiments with different seeds, computes statistics, and generates comparison plots.

Public API:

  • func setup_plot_style - Setup publication-ready plot style.
  • func load_seed_results - Load classification results for each seed.
  • func compute_statistics - Compute mean and std statistics across seeds.
  • func plot_metric_comparison_across_seeds - Plot metric comparison for each seed.
  • func plot_metric_variability - Plot metric variability across seeds with error bars.
  • func plot_seed_boxplot - Create boxplot showing metric distribution across seeds.
  • func plot_multi_metric_heatmap - Plot heatmap of mean metrics across seeds.
  • func plot_seed_stability_ranking - Plot how classifier rankings change across seeds.
  • func generate_summary_report - Generate a comprehensive summary report.
  • func run - Execute the pipeline.

src/inmotion/analysis/interference.py - 44 lines

Analyze cross-route interference using the concurrent_noise_path column.

Usage: inmotion analyze-interference –data data/processed/dataset.csv –output-dir plots/interference

Public API:

  • func run - Execute the pipeline.

src/inmotion/viz/regenerate.py - 142 lines

Regenerate plots from saved CSV results.

This script loads classification results from CSV files and regenerates all visualization plots without needing to retrain models.

Usage: uv run inmotion regenerate-plots –results-dir results_3 inmotion regenerate-plots –csv results_3/classification_results.csv –plots-dir plots_regenerated inmotion regenerate-plots –results-dir results_3 –eda –data data/processed/dataset.csv

Public API:

  • func run - Execute the pipeline.

src/inmotion/viz/regenerate_dl.py - 80 lines

Regenerate DL-specific paper plots from extended results CSV.

Usage: inmotion regenerate-dl-plots –results-csv results/dl/dl_detailed_seed42.csv –output-dir plots/dl/42 inmotion regenerate-dl-plots –results-csv results/dl/dl_detailed_seed42.csv –eda –data data/processed/dataset.csv

Public API:

  • func run - Execute the pipeline.

src/inmotion/dl/config.py - 101 lines

DL pipeline configuration.

Public API:

  • class DLConfig

src/inmotion/dl/data_loader.py - 343 lines

Data loading, preprocessing, and PyTorch Dataset/DataLoader utilities.

Public API:

  • class RSSIDataset - PyTorch Dataset for RSSI time-series sequences.
  • class MetaRSSIDataset - Dataset that returns (X, meta, y) triples for metadata-fusion models.
  • class DLDataLoader - Load, preprocess, and split the WiFi fingerprinting dataset.

src/inmotion/dl/training.py - 317 lines

Generic Trainer with WandB logging, early stopping, and L1 regularization.

Public API:

  • class Loggable
  • class TrainResult
  • class Trainer

src/inmotion/dl/optimization.py - 669 lines

Optuna HPO studies — per-model and NAS meta-model.

Public API:

  • func init_optuna_db - Pre-create SQLite schema + studies in the main process to avoid spawn race.
  • func run_hpo_study - Run HPO for a named model type. Returns the finished study.
  • func run_nas_study - NAS: Optuna searches over architectures AND hyperparams.
  • func run_binary_moe_hpo_study - HPO for a single binary MoE expert arch type.
  • func save_optuna_plots
  • func run_moe_multiobjective_study - Multi-objective Optuna HPO for SoftMixtureOfExperts using NSGA-II.

src/inmotion/dl/evaluation.py - 291 lines

Metrics, cross-validation evaluation, and plot generation.

Public API:

  • func compute_metrics
  • func plot_confusion_matrix
  • func plot_training_curves
  • func cross_validate
  • func evaluate_model_on_test
  • func save_results_csv
  • func evaluate_checkpoint_from_disk - Load a checkpoint from disk, reconstruct the model, and evaluate.
  • func metrics_to_extended_row - Convert metrics dict to a flat row dict suitable for CSV storage.

src/inmotion/dl/results.py - 77 lines

Extended results I/O for DL pipeline — detailed per-class metrics + confusion matrices.

Public API:

  • func save_extended_results_csv - Save extended results rows to CSV with all per-class and CM columns.
  • func load_extended_results - Load extended DL results CSV.

src/inmotion/dl/interference.py - 357 lines

Cross-route interference analysis — how concurrent paths affect RSSI signatures.

Analyses the concurrent_noise_path column to measure how strongly each interfering route distorts the RSSI readings of the primary route. Generates publication-quality PDF plots at 600 DPI with large fonts.

Public API:

  • class InterferenceAnalyzer - Analyze how concurrent noise from different routes affects RSSI readings.

src/inmotion/dl/models/__init__.py - 48 lines

DL model exports.

No public classes or functions; this module provides data or constants consumed elsewhere.

Classical machine learning library (inmotion.classification)

Section titled “Classical machine learning library (inmotion.classification)”

src/inmotion/classification/config.py - 117 lines

Configuration module for ML classification pipeline.

Public API:

  • func check_gpu_availability - Check if CUDA GPU is available for ML libraries.
  • class Config - Configuration settings for the ML classification pipeline.

src/inmotion/classification/classifiers.py - 362 lines

Classifier factory with all ML classification algorithms.

Public API:

  • class ClassifierFactory - Factory class to create and manage all classifiers.

src/inmotion/classification/training.py - 407 lines

Training pipeline for ML classification.

Public API:

  • func suppress_stderr - Context manager to suppress stderr output (for C++ library warnings).
  • class ClassifierResult - Results from training a classifier.
  • class TrainingPipeline - Complete training pipeline for all classifiers.

src/inmotion/classification/optimization.py - 325 lines

Optuna hyperparameter optimization module.

Public API:

  • class OptunaOptimizer - Hyperparameter optimization using Optuna.

src/inmotion/classification/visualization.py - 637 lines

Visualization module for ML classification results.

Public API:

  • func load_results_from_csv - Load classification results from CSV files for plot regeneration.
  • class Visualizer - Visualization utilities for ML classification results.

src/inmotion/classification/eda.py - 452 lines

Exploratory Data Analysis module for comprehensive dataset analysis.

Public API:

  • class ExploratoryDataAnalysis - Comprehensive exploratory data analysis for WiFi fingerprinting dataset.

src/inmotion/classification/data_loader.py - 110 lines

Data loading and preprocessing module.

Public API:

  • class DataLoader - Load and preprocess the WiFi fingerprinting dataset.