Quickstart¶
Get from installation to a validated grouped workflow without having to learn the entire API first.
1. Install¶
python -m pip install gp3mlpy
python -m pip install "gp3mlpy[xgboost]"
python -m pip install "gp3mlpy[conformal]"
python -m pip install "gp3mlpy[artifact]"
git clone https://github.com/stefanosbalaskas/gp3mlpy.git
cd gp3mlpy
python -m pip install -e ".[dev,docs]"
Verify the active package:
import gp3mlpy as gp
print(gp.__version__)
print(gp.r_reference_version)
Expected release values are 0.1.0 and 0.3.0.
2. Start from the scientific target¶
The first question is not which model should I fit? It is what claim must the assessment data support?
New people
New participants¶
Use participant-disjoint splitting when the claim concerns performance on people not used for fitting.
New material
New stimuli¶
Use stimulus-disjoint splitting when assessment stimuli must be unseen during fitting.
Both unseen
Participants + stimuli¶
Require both forms of independence when the scientific claim needs both.
3. Run a minimal governed workflow¶
This synthetic example uses an explicitly observed experimental assignment and requires new-participant generalization.
import gp3mlpy as gp
predictors = [
"tracking_ratio",
"blink_rate",
"fixation_duration",
"gaze_dispersion",
"pupil_change",
]
data = gp.simulate_gazepoint_governed_data(
n_participants=18,
n_stimuli=4,
trials_per_cell=1,
seed=17,
)
task = gp.create_gazepoint_synthetic_task(
data,
workflow="assigned_condition",
generalization_target="new_participants",
)
manifest = gp.create_gazepoint_synthetic_manifest(task.outcome, predictors)
folds = gp.create_gazepoint_group_folds(
data=data,
outcome=task.outcome,
predictors=predictors,
feature_manifest=manifest,
generalization_target=task.generalization_target,
participant_id=task.participant_id,
trial_id=task.unit_id,
stimulus_id=task.stimulus_id,
v=3,
repeats=1,
seed=17,
)
evaluation = gp.evaluate_gazepoint_group_folds(
folds,
task,
predictors,
engine="glm",
seed=17,
)
validation = gp.validate_gazepoint_resample_evaluation(evaluation)
assert validation.status == "pass"
4. Add only the layers your question needs¶
Need hyperparameter selection?
Nested grouped resampling
Need explicit classification decisions?
Decision governance
Need prediction sets or intervals?
Group-aware conformal prediction
Need a second dataset?
External validation reporting
Need shift diagnostics?
Dataset shift and robustness
Need a release-ready evidence bundle?
Reproducibility hardening
5. Keep the boundary explicit¶
Permitted-use boundary
gp3mlpy is for explicitly observed, non-sensitive outcomes. It must not be used for person identification, biometric authentication, protected-attribute inference, health/diagnosis inference, or direct/indirect inference of emotion, stress, personality, deception, cognition, comprehension, intent, or other mental states.
Read Key concepts before adapting the workflow to a new study, then use the workflow API map when you are ready to move from examples to individual functions.