README
¶
cohorts 
import "github.com/marcsantiago/go-cohort"
Overview
A simple data-science package, which allows deterministic hashes to segment data by cohort 
Index
Package files
bucket.go cohorts.go doc.go split_type.go
Constants
const (
BucketA = "A"
BucketB = "B"
BucketC = "C"
)
const (
SplitCohortAB = iota + 2
SplitCohortABC
)
const SplitTypeUnknown = SplitType(-1)
returns -1 because when using the value in mod math the split will always be 0 and therefore fall into group A without a B group this in turn means the split is not running, but also nothing is panicking or breaking.
type Bucket
type Bucket string
Bucket provides a string representation of the Bucket the cohort landed in
func AssignCohort
func AssignCohort(identifier string, splitType SplitType) Bucket
AssignCohorts returns a Bucket which is a string representation of A,B,or C contingent on the split type
func AssignCohortAB
func AssignCohortAB(identifier string) Bucket
AssignCohortAB calls AssignCohort and fixes the split type to A/B
func AssignCohortABC
func AssignCohortABC(identifier string) Bucket
AssignCohortAB calls AssignCohort and fixes the split type to A/B/C
func AssignMultipleCohorts
func AssignMultipleCohorts(identifier string, splitBy []SplitType) Bucket
AssignMultipleCohorts generates a bucket that merges the cohort on multiple split types e.g two different tests running on the same user where each test has a different split type assigned users see that a blue banner running an A/B test and users that see cats, dogs, or clowns as an A/B/C where the users are the same and the tests are running at the same time but the spit is different, test 1 the user is assigned bucket A and in test 2 the user is a assigned bucket C, so we return AC as the bucket type. Buckets are always sorted so A will represent that status on A/B testing and C on A/B/C testing
type SplitType
type SplitType int8
type SplitTypes
type SplitTypes []SplitType
Buckets is an alias for []Bucket with the sort interface implemented
func (SplitTypes) Len
func (s SplitTypes) Len() int
func (SplitTypes) Less
func (s SplitTypes) Less(i, j int) bool
func (SplitTypes) Swap
func (s SplitTypes) Swap(i, j int)
Generated by godoc2md
Documentation
¶
Overview ¶
Package cohorts is a simple data-science package that allows deterministic hashes to segment data by cohort
Index ¶
Constants ¶
const ( BucketA = "A" BucketB = "B" BucketC = "C" )
const ( SplitCohortAB = iota + 2 SplitCohortABC )
const NoBucket = Bucket("")
const SplitTypeUnknown = SplitType(-1)
SplitTypeUnknown returns -1 because when using the value in mod math the split will always be 0 and therefore fall into group A without a B group this in turn means the split is not running, but also nothing is panicking or breaking.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bucket ¶
type Bucket string
Bucket provides a string representation of the Bucket the cohort landed in
func AssignCohort ¶
AssignCohort AssignCohorts returns a Bucket which is a string representation of A,B,or C contingent on the split type
func AssignCohortAB ¶
AssignCohortAB calls AssignCohort and fixes the split type to A/B
func AssignCohortABC ¶
AssignCohortABC AssignCohortAB calls AssignCohort and fixes the split type to A/B/C
func AssignMultipleCohorts ¶
AssignMultipleCohorts generates a bucket that merges the cohort on multiple split types e.g. two different tests running on the same user where each test has a different split type assigned users see that a blue banner running an A/B test and users that see cats, dogs, or clowns as an A/B/C where the users are the same and the tests are running at the same time but the spit is different, test 1 the user is assigned bucket A and in test 2 the user is an assigned bucket C, so we return AC as the bucket type. Buckets are always sorted so A will represent that status on A/B testing and C on A/B/C testing
type CohortMapper ¶ added in v1.2.0
CohortMapper defines a mapping between one cohort bucket and another. This can be used to remap users from one experimental cohort to another (for example, to align training or testing buckets).
func (CohortMapper) Remap ¶ added in v1.2.0
func (cm CohortMapper) Remap(bucket Bucket) Bucket
Remap returns the remapped bucket if one exists in the mapper. If the mapper is nil or the bucket is not found, the original bucket is returned unchanged.
type Option ¶ added in v1.3.1
type Option func(*TrainingSplit)
Option applies optional configuration to a TrainingSplit.
func WithCustomRng ¶ added in v1.3.1
WithCustomRng overrides the default random number generator used by TrainingSplit when deciding whether to assign an entity to the training cohort.
The provided rng function must return a float64 in the range [0.0, 1.0). This is useful for testing (e.g., deterministic behavior) or for injecting a custom source of randomness.
type SplitTypes ¶
type SplitTypes []SplitType
SplitTypes Buckets is an alias for []Bucket with the sort interface implemented
func (SplitTypes) Len ¶
func (s SplitTypes) Len() int
func (SplitTypes) Less ¶
func (s SplitTypes) Less(i, j int) bool
func (SplitTypes) Swap ¶
func (s SplitTypes) Swap(i, j int)
type TrainingAction ¶ added in v1.2.0
type TrainingAction func() float64
TrainingAction defines the signature for training callbacks. It should perform an action and return a float64 representing a measurement, such as a metric value, cost, or performance score. Actions are intentionally parameterless so callers typically provide per-call parameters by using closures that capture the needed values.
type TrainingSplit ¶ added in v1.2.0
type TrainingSplit struct {
// contains filtered or unexported fields
}
TrainingSplit controls the logic for assigning users or entities into "training" or "normal" flows based on a probabilistic split percentage. The struct holds configuration used by the assignment logic; concrete actions are provided per-call to RunWithTraining (so the same TrainingSplit can be reused concurrently with different action closures).
func NewTrainingSplit ¶ added in v1.2.0
func NewTrainingSplit(splitPercent float64, splitType SplitType, remapper CohortMapper, options ...Option, ) *TrainingSplit
NewTrainingSplit creates a new TrainingSplit instance with the provided configuration.
The splitPercent must be between 0.0 and 1.0 inclusive, where:
- 0.0: No entities are assigned to training.
- 1.0: All entities are assigned to training.
- 0.0 < p < 1.0: A random fraction (p) of entities are assigned to training.
The returned TrainingSplit does not contain any per-call actions. Callers must provide the split and normal actions when invoking RunWithTraining. The RNG defaults to math/rand/v2.Float64 which returns uniformly distributed floats in [0.0, 1.0).
func (*TrainingSplit) RunWithTraining ¶ added in v1.2.0
func (t *TrainingSplit) RunWithTraining(targetableID string, normalAction TrainingAction, splitAction TrainingAction) (Bucket, float64)
RunWithTraining executes the appropriate training or normal action based on the configured split percentage. The caller provides the actions to run for the normal (non-training) path and the split (training) path.
Parameters:
- targetableID: used to assign a cohort via AssignCohort when a split occurs.
- normalAction: action to execute when the entity is not assigned to training. May be nil; if so, no action is run for the normal path.
- splitAction: action to execute when the entity is assigned to training. May be nil; if so, no action is run for the split path.
Returns:
- the assigned Bucket (the remapped value when split occurs), or NoBucket if not split.
- the float64 result returned by the executed action (0 if no action ran).
Behavior summary:
- If splitPercent <= 0: always run normalAction, never split.
- If splitPercent >= 1: always run splitAction, always split.
- Otherwise: randomly decide to split based on the splitPercent threshold.
Note: callers typically pass closures for normalAction and splitAction that capture per-call parameters (e.g., request-scoped values) so the TrainingSplit instance itself can remain reusable and concurrency-safe.
Source Files
