marivo.analysis#

Marivo’s typed analysis runtime.

At qualifying catalog-bound runtime parameters, analysis accepts an exact current marivo.semantic.CatalogEntry or its exact marivo.semantic.Ref. The boundary validates ownership, kind, and current membership, then normalizes immediately to the ref. Bare semantic strings, stale or cross-catalog entries, arbitrary entry subclasses, and duck-typed .ref objects are rejected. Runtime metric constructors and nested Event handles retain their existing exact input contracts.

Typed regression is not part of the current analysis operator surface. Work that requires it remains explicit terminal custom analysis through frame.to_pandas() or md.raw_sql(...); neither terminal result can re-enter typed Marivo analysis.

Help and agent surface#

At analysis entry, use the project interpreter to run python -m marivo help once and verify the environment fingerprint. After entry, use the public object already in hand: show() reports current state, while contract() describes mechanically valid next actions. Open focused marivo.help("analysis.<target>") only when that object contract is insufficient or before first use of an unfamiliar capability. After a failure, follow the structured repair. Focused help is not required before every API call.

Live help owns callable signatures, accepted input families, constraints, and recovery guidance.

Frames#

Public artifacts expose ref, kind, shape, row_count, columns, show(), contract(), quality_summary, evidence_status, evidence_digest, lineage, state, and to_pandas(). row_count == shape[0]. contract().issues contains typed issues; role-preserving affordances describe mechanical compatibility only. A multi-metric contract exposes one exact full-id frame.metric(...) projection repair per carried metric when a consumer requires arity 1; it never selects one.

Every public value returned by .contract() has bounded repr, render(), and show() while retaining its structured fields. This is structural conformance, not a shared public contract base class.

`BaseFrame`	Call marivo.help(BaseFrame) for its public consumption contract.
`BaseFrameMeta`	Shared ownership and provenance fields for every frame family.
`MetricFrame`	Metric artifact; call marivo.help(MetricFrame) for its public contract.
`EventFrame`	Canonical materialized Event analysis artifact.
`LifecycleFrame`	Canonical materialized replay history or pure Lifecycle reduction.
`SubjectSet`	Persisted exact subject identities for typed cohort composition.
`ComponentFrame`	Call marivo.help(ComponentFrame) for its public consumption contract.
`DeltaFrame`	Call marivo.help(DeltaFrame) for its public consumption contract.
`CoverageFrame`	Call marivo.help(CoverageFrame) for its public consumption contract.
`AttributionFrame`	Call marivo.help(AttributionFrame) for its public consumption contract.
`ForecastFrame`	Call marivo.help(ForecastFrame) for its public consumption contract.
`ArtifactAffordance`	Mechanical compatibility entry, not a recommendation.
`ArtifactInputRequirement`	One public input role preserved from the capability registry.
`ArtifactColumn`	Column-level schema fact for an analysis artifact.
`ArtifactContract`	Mechanical consumption contract for an artifact.
`ArtifactPrecondition`	Mechanical precondition attached to an affordance.
`ArtifactSchema`	Bounded deterministic schema descriptor embedded in an artifact contract.
`ArtifactState`	Baseline runtime facts for a materialized artifact.

Analysis results and selections#

`AssociationResult`	Call marivo.help(AssociationResult) for its public consumption contract.
`HypothesisTestResult`	Call marivo.help(HypothesisTestResult) for its public consumption contract.
`QualityReport`	Call marivo.help(QualityReport) for its public consumption contract.
`CandidateSet`	Call marivo.help(CandidateSet) for its public consumption contract.
`PointAnomalySelection`
`PeriodShiftSelection`
`DriverAxisSelection`
`SliceSelection`
`WindowSelection`
`CrossSectionalOutlierSelection`
`OntologyMetricCandidate`	One selected, unscored ontology candidate ready for explicit observation.
`CandidateOrigin`	Non-evidentiary lineage from one explicitly observed ontology candidate.

Evidence#

Finding is the typed audit record. ArtifactDigest is the bounded operator-local read model; it never performs cross-artifact judgment.

`Finding`
`ArtifactDigest`
`EvidenceDerivationTrace`
`AnalysisScope`	Metric-shaped scope for one artifact and its evidence projection.
`ObservationFact`
`ChangeFact`
`ContributionFact`
`AssociationFact`
`TestDecision`
`ForecastOutput`
`AnomalyCandidate`
`QualityCheckResult`
`DataQualityIssue`
`ComparabilityIssue`
`EvidenceAvailabilityIssue`
`CandidateResolutionIssue`	Repairable analysis-artifact issue for one excluded ontology path.

Bounded pages#

Pages expose immutable items, limit, has_more, and opaque next_cursor. They use ordinary newest-first keyset semantics, not snapshot isolation.

`FrameSummaryPage`	Bounded newest-first page of persisted frame summaries.
`FrameSummaryEntry`
`ArtifactDigestPage`	Bounded newest-first page of persisted artifact digests.
`FindingPage`	Bounded newest-first page of canonical typed findings.

Scopes and windows#

`TimeScope`	One immutable public selection window shared by semantic and analysis.
`AbsoluteWindow`	Call marivo.help(AbsoluteWindow) for its public consumption contract.
`Grain`	One closed aggregation grain, created through public helpers only.

marivo.analysis.grain(unit, *, count=1)[source]#

Construct one builtin aggregation grain.

Parameters:

unit (Literal['second', 'minute', 'hour', 'day', 'week', 'month', 'quarter', 'year']) – One builtin unit from second through year.
count (int) – Positive sub-day width; calendar-variable units require one.

Returns:

The immutable public Grain value.

Return type:

Grain

Example

>>> import marivo.analysis as mv
>>> mv.grain("month")

Constraints:: Semantic calendar levels are constructed by ms.calendar_grain(...).

Event Journey, Lifecycle replay, and typed cohorts#

session.events.match(...) consumes typed participant roles and a closed EventPattern. The first step uses the half-open TimeScope cohort window; completion_through is an inclusive follow-up bound. session.events.funnel(...) and session.events.time_to_event(...) reduce the persisted journey assignment without rematching Events. session.select_subjects(...) materializes the closed dropped_before(...) selection as a persisted SubjectSet. A ready SubjectSet may scope observe(..., cohort=...) and events.match(..., cohort=...).

session.lifecycle.replay(...) consumes one exact current StateModel entry/ref, an explicit timezone-aware half-open window, and the explicit from_inception() seed. It returns LifecycleFrame[history]. Lifecycle reducers consume that persisted history without querying Event sources or replaying the StateModel again. in_state(...) is the closed Lifecycle selection used by session.select_subjects(...); a resulting ready SubjectSet may scope later metric, Event, or Lifecycle materialization. Use focused marivo.help("analysis.lifecycle.replay") and the returned artifact contract() for the current mechanical contract and continuations. Before selecting a window, session.events.occurrence_bounds(...) returns the observed earliest/latest occurrences of one exact Event or StateModel as EventOccurrenceBounds; it does not establish completeness.

`PatternStep`	One typed Event role in an ordered journey pattern.
`EventPattern`	Closed ordered sequence of typed PatternSteps.
`FirstPerSubject`
`EveryStart`
`CompletenessDeclaration`	Explicit caller assertion for exact Event inputs.
`EventOccurrenceBounds`	Observed occurrence-time bounds for one exact Event or StateModel.
`DroppedBefore`	Select subjects that resolved as lost before one exact Event step.
`FromInception`	Required Phase 3 replay seed using the first qualifying inception.
`InState`	Select subjects whose replayed state is established at one instant.
`FunnelLossRate`	Target one PatternStep's loss from its immediately preceding step.
`funnel_loss_rate`	Target the loss into one exact funnel PatternStep for attribution.
`EventWatermarkRequest`	Exact request passed to a backend completeness provider.
`EventWatermarkReceipt`	Provider-owned authoritative Event completeness receipt.
`step`	Build one typed Event Journey step.
`sequence`	Build one ordered EventPattern.
`first_per_subject`	Choose one journey at the earliest first-step occurrence per subject.
`every_start`	Choose one journey attempt per first-step occurrence.
`declared_complete_through`	Declare exact Event inputs complete through one governed bound.
`dropped_before`	Build a typed selection for resolved loss before an Event step.
`from_inception`	Return the only Phase 3 Lifecycle replay seed.
`in_state`	Build an exact typed Lifecycle state selection.

Policies#

`AlignmentPolicy`	Closed public alignment protocol; construct values with one helper.
`AlignmentKind`
`SamplingPolicy`	Call marivo.help(SamplingPolicy) for its public consumption contract.

Refs and lineage#

`ArtifactRef`	Session-local analysis artifact ref.
`Lineage`
`LineageStep`

Session and jobs#

`Session`	Call marivo.help(Session) for its public consumption contract.
`SessionSummary`	Lightweight session metadata returned by page_sessions / session_summary.
`JobSummary`

Alignment and window helpers#

`window_bucket`	Construct a request-window bucket alignment policy.
`day_of_week`	Construct same-weekday-occurrence alignment inside one target period.
`period_progress`	Construct same-progress alignment inside one certified target period.
`period_correspondence`	Construct alignment through one certified named period correspondence.
`occurrence_progress`	Construct relative-local-day alignment inside two exact occurrences.
`working_day_progress`	Construct same-working-day ordinal alignment under one exact schedule.

Slices#

`SlicePredicate`
`SlicePredicateOp`

Submodules#

`marivo.analysis.errors`	Typed analysis errors and local repair contracts.
`marivo.analysis.evidence`	Typed findings, bounded digests, issues, pages, and derivation traces.
`marivo.analysis.frames`	Frame classes and metadata companions.
`marivo.analysis.session`	Session lifecycle helpers (`get_or_create`, `current`, `list`, `delete`).

Type aliases#

`SliceScalar`	Represent a PEP 604 union type
`SliceValue`	Represent a PEP 604 union type
`TimeScopeInput`	Represent a PEP 604 union type