Python package

Example 01

Validate a ready-made Core stimulus

Check an existing stimulus Turtle file with the complete Python validation pipeline.

1. Install the package and download the repository’s validated starter file.
2. Run sstim validate against the frozen Core profile. A successful check is schema conformance, not clinical evidence.

python3 -m pip install "sstim>=0.2,<0.3"
curl -fsSL https://raw.githubusercontent.com/w3c-cg/sstim/main/examples/01-stimulus-core.ttl -o stimulus.ttl
sstim validate stimulus.ttl --profile core --version 0.19.0

Example 02

See profile dependencies before modeling

Understand whether you need kernel, core, core-plus or full.

1. List the available profiles and the manifest-owned module closure; use this to avoid an accidental dependency on Full.

sstim profiles
sstim modules --profile full

Example 03

Validate many files without resolving the ontology repeatedly

Apply the exact same frozen release and profile closure across a study dataset.

1. Resolve the pinned profile once, then validate each record.
2. Review failures; do not treat a valid graph as evidence that the stimulation was effective.

from pathlib import Path
import sstim

closure = sstim.resolve_profile('core', version='0.19.0')
for path in sorted(Path('records').glob('*.ttl')):
    report = sstim.validate(str(path), closure=closure)
    print(path.name, 'PASS' if report else str(report))

Example 04

Record a real session from PsychoPy or LSL

Turn stimulus events and measurements into versioned RDF records with a proper clock provenance.

1. Use the Session builder in the same process that presents the stimulus, or when converting a stored LSL event stream.
2. Pass actual instrument clock readings and playback-start/stop events; do not fabricate timestamps.
3. Write the session file after the run; the builder validates before writing.

import sstim
# In a real PsychoPy run, core is psychopy.core and the stimulus
# is actually presented by your existing experiment code.
start = core.getTime()
s = sstim.Session('https://example.org/lab/run-001/',
    label='10 Hz flicker block', duration=60,
    master_volume=0.0, timing='monotonic-substitute', clock=start)
flicker = s.signal(hz=10, shape='square')
s.channel('Screen disc', modality='visual', medium='visual-light',
    placement='eyes', signal=flicker, parameter='luminance',
    mechanism='direct-presentation')
# Run the actual stimulus here; record its true event timestamp.
s.event('playback-start', at=core.getTime())
# After actual playback: s.close(at=core.getTime(), completed=True)
# Then: s.write('run-001.ttl')

This excerpt illustrates API integration points, not a standalone runnable experiment; PsychoPy and real presentation code must supply core and the actual timing events.

Example 05

Run offline after caching a frozen release

Validate study records in a disconnected lab once a release closure has already been fetched.

1. Fetch the pinned release at least once online.
2. On subsequent runs, --offline refuses uncached dependencies rather than silently updating a release.

sstim validate stimulus.ttl --profile core --version 0.19.0 --offline
sstim cache