Local Regression Studio v1.0.11

User guide and privacy policy

Release: 1.0.11
Operation: Browser-only regression modelling
Original CSV storage: Not included in exported projects or models

1. What the application does

Local Regression Studio loads tabular CSV data, prepares input features, fits regression models, evaluates independent training, validation and test datasets, displays diagnostic plots and applies fitted models to compatible prediction CSV files.

Supported models:

• Linear regression
• Ridge regression
• Elastic-net regression
• Huber robust regression
• Decision-tree regression
• Random-forest regression
• Gradient-boosted regression trees
• k-nearest-neighbour regression
• Linear quantile regression
• Gaussian-process regression
• Artificial neural-network regression

All calculations run inside the browser. The application does not contain an account system, analytics service, cloud-training endpoint, database or CSV-upload endpoint.

2. Starting the application

Offline mode

Extract the package and run the launcher for your operating system:

• Windows: start-windows.bat
• macOS: start-macos.command
• Linux: start-linux.sh

The launcher opens a loopback address, normally similar to:

http://127.0.0.1:8080/?localOnly=1

127.0.0.1 is the user’s own computer. The launcher does not expose the application to other devices on the network.

Offline mode loads all required program files from the extracted package and does not attempt to contact a CDN.

Hybrid mode

Opening index.html, publishing the package on a static host, or running:

python3 start.py --hybrid

allows the application to try pinned CDN copies of Papa Parse and Plotly. If either request fails or times out, the bundled local replacement is used automatically.

Hybrid mode does not send CSV data to the CDN. It does send an ordinary request for the JavaScript library, which may expose normal network metadata such as IP address and browser headers to the CDN provider.

3. Language selection

Use the language selector in the page header.

Options:

• Automatic browser detection
• English
• Simplified Chinese
• Spanish
• French
• German

Language switching changes interface text and number formatting. It does not translate CSV column names, category values, filenames or user data.

Language files are bundled with the package and work in offline mode.

4. Step 1 — Start and load data

Choose a training CSV. The application displays:

• Row and column counts
• Numeric and categorical column counts
• A local preview of the first rows
• Recommended workload warnings

Recommended ordinary workload:

• Up to about 50,000 rows and 50 original columns for the core models
• Smaller datasets for Gaussian processes
• ANN workload determined by both row count and trainable-parameter count

The preview and profiling remain in browser memory.

You may also open:

• A .mlproject project file
• A fitted .mlmodel.json or compatible JSON model file

Project and model files do not contain the original CSV.

5. Step 2 — Select features and transform the target

Select one numeric target column and one or more input features.

The automatic feature detector excludes the target and likely identifier columns. Review its choices before training.

Target transformations:

• None
• Natural logarithm
• Log base 10
• Square root
• Box–Cox
• Yeo–Johnson

Transformation parameters are fitted from training targets only. Predictions and uncertainty bounds are converted back to the original target scale.

Requirements:

• Log and log10 require positive targets.
• Square root requires non-negative targets.
• Box–Cox requires positive targets.
• Yeo–Johnson supports negative, zero and positive targets.

For ANN and linear quantile regression, target values are additionally centred and scaled internally during network optimisation. This internal scaling is reversed before the selected target inverse transformation is applied.

6. Step 3 — Configure preprocessing

Numeric missing values

Choose one of:

• Training mean
• Training median
• Zero
• Drop affected rows

Numeric scaling fitted on training data

Choose:

• Standardisation
• Min–max scaling
• No scaling

Scaling statistics are calculated from the training data only. The fitted values are applied unchanged to validation, test and prediction CSV data.

Scaling is strongly recommended for Gaussian processes and artificial neural networks.

Categorical missing values

Choose:

• A dedicated Missing category
• The most frequent training category
• Drop affected rows

Categorical encoding

Choose:

• One-hot encoding
• Ordinal integer encoding
• Exclude categorical columns

For linear, ridge, elastic-net, Huber robust, and linear quantile regression, removing one reference category from each one-hot feature avoids a redundant indicator column. Tree, GP and ANN models can use either setting, although one-hot encoding may create many processed features.

Unseen categories in validation, test or prediction CSV data follow the fitted training-category policy and produce a warning.

7. Step 4 — Select a model and tune hyperparameters

Manual configuration

The selected settings are fitted directly. Validation data is still used for ANN early stopping and for diagnostic evaluation, but not to choose model hyperparameters.

Grid search

Specify minimum, maximum, number of grid points and linear or logarithmic spacing for each tunable numeric parameter. The app previews the candidate count and caps excessively large grids.

Ordinary random search

Each parameter is sampled independently from its configured range.

Latin hypercube sampling

Each continuous parameter range is divided into intervals and sampled once per interval. LHS generally covers multi-dimensional ranges more evenly than ordinary random search with the same number of trials.

All automatic tuning compares candidates using validation RMSE. Test data remains isolated.

7A. Models added in v1.0.11

The expanded modelling release adds elastic net, Huber robust regression, gradient-boosted trees, k-nearest neighbours, and linear quantile regression. All participate in tuning, cross-validation, comparison, validation, approval, and prediction-only workflows.

Key cautions:

• Standardise inputs for elastic net, robust regression, kNN, and quantile regression.
• kNN does not extrapolate and may create large model packages because it stores processed training rows.
• Gradient boosting can overfit as stages/depth increase; inspect validation history.
• Quantile bounds are fitted conditional quantiles, not guaranteed calibrated coverage.
• New-model uncertainty methods must be checked on the independent test set.

See docs/EXPANDED_MODELLING_GUIDE.md for parameter-level guidance.

8. Core model settings

Linear regression

No model hyperparameters. Provides analytical confidence and prediction calculations under ordinary linear-model assumptions.

Ridge regression

Main setting:

• Ridge strength, lambda

Uncertainty uses residual bootstrap models and is labelled approximate.

Elastic net

Settings include total penalty, L1 mixing ratio, coordinate-descent iterations and convergence tolerance.

Huber robust regression

Settings include Huber threshold, IRLS iterations, convergence tolerance and a numerical ridge stabiliser.

Gradient-boosted trees

Settings include stages, learning rate, tree depth, minimum leaf size, row subsampling and threshold-search detail.

k-nearest neighbours

Settings include neighbour count, weighting, distance metric and maximum stored rows.

Linear quantile regression

Settings include central quantile, iterations, learning rate and L2 regularisation. Lower/upper quantiles are derived from requested interval coverage during final fitting.

Decision tree

Settings include:

• Maximum depth
• Minimum rows per leaf
• Candidate thresholds per feature
• Number of features considered per split

The training-history panel shows training and validation mean-squared loss across candidate maximum depths.

Random forest

Settings include:

• Number of trees
• Maximum depth
• Minimum rows per leaf
• Row sampling fraction
• Candidate thresholds
• Features considered per split

The history panel shows cumulative training and validation loss as trees are added.

9. Gaussian-process regression

Exact GP

Exact GP uses every processed training row. Training creates and factorises a dense covariance matrix.

The app uses a default hard limit of 2,000 representative rows. Exact GP may become slow well before that limit on a phone, tablet or lower-powered laptop.

Representative-subset GP

A smaller representative subset is used to construct the GP state.

Selection methods:

• Farthest-point sampling
• K-means++-style representative sampling
• Random sampling

This is a subset-of-data approximation. It is not a sparse variational GP and does not optimise free inducing-point locations.

Automatic subset-size optimisation

Select Automatically optimise subset size and configure:

• Minimum subset size
• Maximum subset size
• Number of sizes to evaluate
• Validation tolerance

The app evaluates candidate sizes using validation RMSE and selects the smallest subset within the requested tolerance of the best validation result.

Example: with a 1% tolerance, a 250-row subset may be selected over a 1,000-row subset when its validation RMSE is no more than 1% worse.

Kernels

Available kernels:

• RBF or squared exponential
• Matérn 3/2
• Matérn 5/2
• Rational quadratic
• Linear

Settings include:

• Length scale
• Signal variance
• Observation-noise standard deviation
• Numerical jitter
• Rational-quadratic alpha
• Kernel optimisation iterations

The implementation uses a shared length scale across processed features in v1.0.11. Therefore, the GP feature-relevance chart is only a shared-scale proxy rather than an ARD ranking.

GP uncertainty

The GP produces a predictive mean and variance. Prediction intervals include the configured observation-noise term. Step 6 reports empirical interval coverage, width, coverage error and interval score on each split.

The optimisation-history plot displays negative log marginal likelihood by iteration.

10. Artificial neural-network regression

The ANN is a local CPU-based dense feed-forward network implemented in JavaScript. It does not use cloud training.

Architecture

Configure one to three hidden layers with up to 512 neurons per layer.

Activations:

• ReLU
• Leaky ReLU
• Tanh
• Sigmoid

The output layer is linear for regression.

Training settings

• Adam or stochastic gradient descent
• Learning rate
• Batch size
• Maximum epochs
• Dropout rate
• L2 regularisation
• Early-stopping patience
• Minimum validation improvement

Training data updates the network weights. Validation data determines early stopping. The best validation epoch is restored.

The learning-curve plot shows training and validation mean-squared loss on the internally standardised transformed-target scale.

Model-size recommendations

The app calculates trainable parameters before fitting.

• Below 50,000: small browser model
• 50,000–250,000: ordinary desktop range
• 250,000–500,000: large model
• 500,000–1,000,000: very large browser workload
• Above 1,000,000: blocked by default

On mobile or memory-constrained devices, remain below approximately 100,000 parameters.

A small dataset combined with a very large network can overfit even when the browser has enough memory. Prefer smaller networks, dropout, L2 regularisation and early stopping.

ANN hyperparameter tuning

Grid, random and LHS searches can vary:

• First hidden-layer size
• Second hidden-layer size
• Learning rate
• Dropout
• L2 regularisation

Other settings remain manually configurable. Search candidates use a single network; an optional ensemble is trained only after the final hyperparameters are selected.

Monte Carlo dropout uncertainty

Repeated stochastic forward passes keep dropout active during prediction. The distribution is combined with training residual variation.

This interval is approximate and does not guarantee nominal coverage.

Small deep ensemble uncertainty

Two to seven independently initialised networks are trained. Their prediction distribution is combined with residual variation.

Ensembles multiply training time, memory use and exported model size.

11. Step 5 — Split and train

The application maintains three independent datasets:

• Training: fits preprocessing and model parameters
• Validation: selects hyperparameters, GP subset size and ANN stopping epoch
• Test: final independent evaluation only

Split strategies:

Naive random split

Seeded row-level random allocation.

Metadata/source-grouped split

Choose a source column and assign validation and test source values. Every remaining source goes to training. A source cannot appear in multiple splits.

Regime-aware split

Choose either:

• Proportional splitting inside each regime
• Complete held-out regimes for validation or test

Held-out regimes measure extrapolation to unseen conditions.

Time-based split

Choose a time or sequence column. The app sorts rows and allocates contiguous training, validation and test periods without shuffling.

Cross-validation

Optional k-fold cross-validation is performed on training data only. Every fold independently refits preprocessing, target transformation and model.

For GP and ANN, cross-validation can be computationally expensive. Use smaller subsets, fewer folds or reduced ANN epochs.

12. Step 6 — Review, validate and approve

Step 6 is ordered to match the review workflow:

1. Confirm the active experiment and compare saved experiments.
2. Review performance metrics.
3. Choose diagnostic plot settings.
4. Inspect diagnostic plots.
5. Evaluate validation and acceptance criteria.
6. Generate validation and governance reports.
7. Download general model, metrics, experiment and project exports.
8. Record the approval decision and, when appropriate, export an approved prediction package.

Point metrics:

• R²
• RMSE
• MAE

Uncertainty metrics when intervals are available:

• Prediction Interval Coverage Probability
• Mean Prediction Interval Width
• Normalised interval width
• Coverage error
• Interval or Winkler-style score

Plots include:

• Actual versus predicted
• Residual versus predicted
• Residual distribution
• Residual Q–Q plot
• Residual versus selected input feature
• Residual by source
• Interval width versus prediction
• Training, growth or optimisation history
• Feature importance or relevance proxy

The Show uncertainty intervals in plots checkbox affects only visual display. It does not retrain the model or remove uncertainty metrics.

Test metrics should be treated as the final independent assessment. Do not repeatedly adjust model choices after inspecting the test set without creating a new untouched test dataset.

13. Step 7 — Predict unknown data

Upload a compatible CSV containing all required input columns.

The target column is not required. When a measured target is present, select it under Optional measured-target comparison and enable the checkbox to display measured and predicted values together.

Measured values are used only for plotting. They do not update, fit or tune the model.

The prediction download contains:

• Source row number
• Prediction
• Lower and upper interval bounds when available
• Interval level
• Uncertainty method

GP predictions use the saved representative processed training state. ANN predictions use saved network weights. The same fitted preprocessing and target transformation are applied.

14. Saving and reopening work

Model file

Contains the fitted model and preprocessing required for prediction. It omits diagnostic data and the original CSV.

Project file

Contains configuration, model, metrics, split predictions and diagnostic data. It omits the original CSV.

When reopening a project, upload the original or a compatible CSV to retrain or restore raw-data-dependent controls.

Sensitive derived information

Model files can still be sensitive:

• GP files include representative processed training inputs, covariance factors and coefficients.
• ANN files include learned weights that may encode patterns from the training data.
• Predictions and metrics may reveal sensitive outcomes.

Secure exported files appropriately.

15. Privacy policy

Data processed locally

The following operations occur inside the user’s browser:

• CSV parsing
• Column profiling
• Missing-value handling
• Scaling and categorical encoding
• Data splitting
• Hyperparameter search
• Model training
• Cross-validation
• Uncertainty estimation
• Diagnostics and plotting
• Unknown-data prediction
• Export generation

Data not automatically stored

The application does not automatically store CSV data in browser local storage, IndexedDB, cookies or a remote service.

The application retains data in memory while the page remains open. Closing or reloading the page clears that in-memory state unless the user first downloads a project or model.

Network requests

Offline mode makes no CDN attempt. A hosted page or local loopback server still serves application files to the browser.

Hybrid mode may request JavaScript libraries from configured CDNs. Requests do not contain CSV rows, model inputs, predictions or metrics.

No analytics or remote logging

The packaged application contains no:

• Analytics SDK
• Advertising SDK
• Remote error-reporting service
• fetch-based data upload
• XMLHttpRequest data upload
• WebSocket data channel
• Cloud model API

Hosting logs

When the package is hosted on GitHub Pages, GoDaddy or another web server, the hosting provider may log ordinary request metadata such as IP address, browser type, time and requested file path. This is separate from application-level CSV processing.

User-controlled downloads

Files leave browser memory only when the user explicitly downloads or saves them. The user is responsible for selecting a safe directory and controlling access to exported models, projects, predictions, plots and metrics.

16. Current limitations

• GP uses a shared length scale rather than per-feature ARD.
• Representative-subset GP is not a variational sparse GP.
• GP matrix calculations are CPU-based JavaScript and may be slow near the hard limit.
• ANN training is CPU-based and may be slower than native or GPU frameworks.
• ANN uncertainty is approximate.
• A single decision-tree interval is leaf-based and approximate.
• Random-forest intervals use variation between trees and are approximate.
• Browser memory reporting is optional and may be unavailable or imprecise.
• Some specialised plot hover text may remain in English after switching languages.

17. Troubleshooting

The app does not start

Use a launcher rather than opening index.html directly. Confirm the folder structure still contains js, css and vendor directories.

GP covariance factorisation fails

Increase observation noise or numerical jitter, standardise features, remove duplicate rows, or use a smaller representative subset.

GP training is too slow

Reduce subset size, kernel optimisation iterations, tuning trials or cross-validation folds.

ANN loss does not improve

Standardise numeric inputs, use Adam, reduce the learning rate, use ReLU or tanh, reduce network size or increase maximum epochs.

ANN loss becomes non-finite

Reduce the learning rate, standardise inputs, reduce layer sizes and inspect the target for invalid or extreme values.

ANN overfits

Reduce layer sizes, increase dropout or L2, use early stopping, obtain more training data, or simplify the feature set.

Prediction CSV is rejected

Ensure every required feature column is present with the exact original spelling. The target column is optional.

Save As is unavailable

The browser will use its configured download directory. Direct file-system access is not supported consistently across every browser.

Step 4 interface behaviour

The package includes a detailed model-options reference at:

docs/STEP_4_MODEL_OPTIONS_GUIDE.md

Step 4 now hides settings that do not affect the selected Gaussian-process configuration:

• Rational-quadratic alpha appears only for the rational-quadratic kernel.
• Length scale is hidden for the linear kernel.
• Exact GP hides every subset control.
• Representative-subset GP shows fixed subset size and subset selection.
• Automatic subset optimisation shows the automatic size-range controls and subset selection.

ANN grid, ordinary-random and Latin-hypercube tuning include all three hidden-layer sizes. A third hidden layer is allowed only when the second hidden layer is present. Search summaries distinguish requested samples from unique valid configurations and show when a grid is capped.

Experiment provenance and schema migration in v1.0.11

Dataset fingerprint

After a training CSV is loaded, the app calculates a SHA-256 fingerprint locally. Before hashing, a UTF-8 byte-order mark is removed and Windows or classic-Mac line endings are normalised to line-feed characters. This makes fingerprints stable when the CSV content is the same but line-ending conventions differ.

The fingerprint is an identifier, not encryption and not a replacement for keeping the original data. The original CSV is not placed in model, project or experiment files.

Experiment record

Every successful training run creates an experiment record containing:

• Experiment ID and application version
• Dataset filename metadata, row and column counts, and fingerprint
• Target, features, preprocessing and target transformation
• Split method, random seed, split sizes and CSV row membership
• Model type, capabilities and hyperparameters
• Tuning settings and candidate history
• Uncertainty settings
• Training, validation and test metrics
• Training-job start, finish, progress status and result summary
• Warnings and migration notes

Use Download experiment record in Step 6 to save this information as a .mlexperiment.json file.

Project and model schema version 10

v1.0.11 writes model and project schema version 10, experiment schema version 6, and approved prediction-package schema version 2. Files from earlier releases are migrated in memory when loaded. The migration does not modify the original file on disk. Saving the migrated artifact creates a new v1.0.11 file.

A migrated artifact from an earlier release may not contain a dataset fingerprint or exact split membership because those values were not recorded by the earlier release. The app marks the generated experiment record as migrated and includes a warning.

Experiment collections

A v1.0.11 project contains multiple fitted experiments, an active experiment ID, an optional preferred experiment ID, validation records and approval records. Step 6 provides the multi-model comparison workspace while diagnostics operate on the active experiment.

Managed jobs and cancellation

Training now has an internal job record. The record tracks progress, status, start and finish times, cancellation requests and errors. The existing Cancel button requests cancellation through this job system while retaining the existing model-level cancellation checks.

Web Worker foundation

The package includes a local Web Worker protocol. v1.0.11 uses it for dataset fingerprinting when the browser permits workers. If the application is opened in a browser context that blocks workers, fingerprinting safely falls back to the main browser thread.

Model training remains on the main application thread in v1.0.11. Moving complete training and tuning workflows into workers is planned for a later release and requires careful transfer, progress and cancellation handling.

Model comparison workspace

Training a comparison set

In Step 5, select the model families to include and choose Train selected baseline models. The app fits them sequentially using the same split, preprocessing, target transformation and uncertainty level. Linear, ridge, tree and forest are selected initially. GP and ANN are optional because they can be slower.

The comparison batch uses documented baseline hyperparameters. For a tuned candidate, configure the model in Step 4 and use Train and evaluate; the resulting experiment is added to the same workspace.

Reading the leaderboard

The Step 6 comparison workspace shows validation RMSE, independent test metrics, uncertainty metrics and training time. Use validation performance to compare or select candidates. Use test metrics for the final independent assessment rather than repeatedly tuning against the test set.

A Different setup badge means that the experiment differs from the active model in one or more of: dataset fingerprint, target, features, preprocessing, target transformation, exact split membership or requested interval level. Such experiments remain available but are hidden when Comparable only is selected.

Active and preferred models

• Open makes an experiment active and refreshes diagnostics and Step 7 prediction.
• Prefer records the user’s preferred candidate and moves it to the top of the leaderboard. It is not a formal approval mechanism.
• Remove deletes an experiment from the current in-memory project.

Saving comparison projects

A v1.0.11 project stores every fitted artifact, the active experiment, the preferred experiment, experiment records and diagnostic outputs. The original CSV remains excluded. Multi-model projects can be larger than earlier project files.

Validation workflow

Data-quality assistant

The assistant updates when the target or feature selection changes. It checks common risks including exact duplicate rows, missing target or feature values, constant and near-constant columns, selected identifier-like columns, high-cardinality categories and very strong numeric relationships that may indicate target leakage.

Findings are classified as critical, warning or information. These automated checks do not determine whether data are scientifically representative or whether a relationship is causal.

Acceptance criteria

Step 6 allows optional limits for test RMSE, test R², interval coverage and worst-group test RMSE. It can also require no critical data-quality finding. Blank numeric limits are not evaluated.

The result is Passed, Failed or Not evaluated. A passed result means only that the configured measurable criteria passed. It is not regulatory approval or certification.

Group validation

Choose a source, regime or other available column to calculate count, RMSE, MAE, R², bias and interval coverage for each test-set group. Very small groups can produce unstable metrics.

Prediction applicability

For uploaded prediction data, the app checks numeric values against fitted training ranges, identifies values near range boundaries, reports missing values handled by preprocessing and detects categorical levels not present during training. Row-level status and explanations are included in the prediction CSV.

These checks do not detect every type of distribution shift and do not guarantee that a prediction is reliable.

v0.4.0 approval and operational workflow

Approval workspace

After validation, Step 6 provides an approval workspace for the active experiment. Record the model name, owner, reviewer, intended use, prohibited uses, known limitations, conditions, decision date and next review date. Approval history is stored with the fitted artifact, experiment record and project.

Statuses are Draft, Approved, Approved with conditions, Rejected and Retired. Full approval requires the configured acceptance criteria to pass. Conditional approval requires written conditions. Approval is a human decision recorded by the app; it is not automatic certification.

Operational input schema

The app builds an input schema from the fitted training preprocessor. Numeric training ranges and categorical levels are retained. Optional units and descriptions can be added for operators. These values are documentation and applicability evidence; they do not prove that uploaded values use the stated unit or are fully in-distribution.

Validation and approval report

Choose Download validation report (HTML) to create a local report containing model identity, dataset fingerprint, intended/prohibited uses, test metrics, acceptance outcomes, input schema, limitations and decision history. Open the report in a browser and print or save it as PDF when required.

Approved prediction package

An approved .mlpredict.json package contains the fitted model and preprocessing, approval record, evaluation summary, input schema, embedded test vectors and SHA-256 integrity metadata. The original CSV is excluded. The package is available only when the approval record is operational and the review date has not passed.

Prediction-only mode

Prediction-only mode hides model-development controls. It requires an approved package and verifies:

• Package type and schema
• SHA-256 integrity
• Approval status
• Review-date validity
• Embedded self-test predictions
• Required input columns and numeric types

After verification, upload a compatible CSV in Step 7. Prediction downloads include package ID, approval status, review date, integrity status and applicability findings.

Security and governance limitations

SHA-256 detects changes but is not a digital signature. It does not authenticate the reviewer or enforce organizational access control. Store approved packages and reports in controlled systems when auditability or regulated authorization is required.

v1.0 deployment and governance

v1.0 preserves the documented modelling behaviour and adds separate deployment editions, versioned governance lifecycle records, monitoring and revalidation, model-change assessments, local recovery, stricter import/export validation, and optional verification of organizational signatures against deployment-pinned public keys. See the package-root DEPLOYMENT_GUIDE.md, GOVERNANCE_GUIDE.md, MONITORING_GUIDE.md, SECURITY.md, and MIGRATION_GUIDE.md.

v1.0.11 comparison and approval usability notes

The Train a comparison set panel now states explicitly that a quick baseline comparison uses one frozen target, feature selection, preprocessing setup, target transformation, exact train/validation/test membership, random seed and interval level. A preset table and ? help buttons explain the baseline settings used for each model.

The Model comparison workspace now includes a chart-scope selector. Comparable-only charts remain the recommended final-selection view. All-experiment charts are available for overview and mark different-setup models with a warning symbol. Use the Why different? button to display the descriptor fields that differ from the active experiment.

The Approval and operational release section now provides separate approval record JSON and approval history CSV downloads. The full approval bundle remains planned for a later release.