No project description provided
Project description
TWON: Ranker - Modularized & Weighted Timeline Ranking
todo
Usage
# installing via pip
pip install twon-ranker
# running as python module
python -m twon_ranker.api
Development Setup
todo
# install Python requirements
make install
# start api with hot-reload for development
make dev
# start api for production
make serve
# run unit tests
make test
Modules
The current TWON ranking/recommendation algorithm is divided into three encapsulated modules that composed denote the ranking function. These modules provide the functionalities to measure engagement given a predefined data format, represent the course of time, and partly randomize the final ranking.
Noise
We draw random floating point numbers from the normal distribution provided lower and upper boundaries to generate a multiplicative noise (the neutral value defined as LOW = HIGH = 1.
will result in no noise).
from src.modules import Noise
LOW: float
HIGH: float
N: int
eps = Noise(low=LOW, high=HIGH)
rnd_number: float = eps()
rnd_samples: List[float] = eps.draw_samples(N)
Decay
We compute a decay factor based on the time elapsed between two references. In the context of this project, the decay factor decreases the relevance of posts over time. That results in older posts without recent interaction being less often recommended. We instantiate a decay object by defining a minimum value that serves as a lower boundary for the decay and a reference time interval. When called, the decay object calculates a time difference between the reference time interval and the observed time interval. The maximum computed value is defined as 1, for observation == reference
.
from src.modules import Decay
MINIMUM: float
REFERENCE_TIMEDELTA: timedelta
decay = Decay(minimum=MINIMUM, reference_timedelta=REFERENCE_TIMEDELTA)
decay_factor: float = decay(observation_datetime=datetime, reference_datetime=datetime)
Engagement
The engagement module computes a score based on a plain count of observations count_based
or the sum of decayed values for the individual data points decay_based
. For the decayed-based version, an instantiated decay module is necessary. Optionally, the output can be normalized with the natural logarithm log_normalize
.
from src.modules import Engagement
FUNC: Literal['count_based', 'decay_based']
LOG_NORMALIZE: bool
E = Engagement(func=FUNC, log_normalize=LOG_NORMALIZE)
score_count: int = E(items=List[datetime])
score_decay: float = E(items=List[datetime], reference_datetime=datetime, decay=decay)
Usage
todo
Post
We model a social media post for the TWON simulation with the following class. The object contains the following attributes:
- id: A unique identifier (ID) of the post as a string.
- timestamp: The timestamp containing the post creation date and time. The class expect a string formatted defined by ISO 8601.
- likes/dislikes: A list of observations denoted as timestamps (see above).
- comments: A list of
Post
objects representing comments. This approach allows arbitrary nest posts into complex tree structures for future TWON modifications. The current implementation ignores those sublevel structures and only counts direct comments of the main posts into the observations.
from src.post import Post
ID: str
TIMESTAMP: datetime
OBERSERVATIONS: List[datetime]
COMMENTS: List[Post] # post objects w/o comments
post = Post(
id=ID,
timestamp=TIMESTAMP,
likes=OBERSERVATIONS,
dislikes=OBERSERVATIONS,
comments=COMMENTS,
)
Request
The Request
object denotes the attributes needed for interaction with the ranker. It collates all modules previously defined and combines them with weights for each observation type. The object contains the following attributes:
- items: A list of Post objects
- reference_datetime: The reference timestamp (defaults to now while receiving the request).
- decay: Attributes needed to instantiate the
Decay
module - noise: Attributes needed to instantiate the
Noise
module - engagement: Attributes needed to instantiate the
Engagement
module - weights: Weights to tweak the different engagement factors (defaults
1.0
for all)
from src.request import Request, Weights
MODE: Literal["ranked", "chronological", "random"] = "ranked"
ITEMS: List[Post] # see Usage:Post
REFERENCE_DATETIME: datetime
DECAY: modules.Decay # see Modules:Decay
NOISE: modules.Noise # see Modules:Noise
ENGAGEMENT: modules.Engagement # see Modules:Engagement
WEIGHTS: Weights(
likes=1.
dislikes=1.
comments=1.
comments_likes=1.
comments_dislikes=1.
)
req = Request(
items=ITEMS,
reference_datetime=REFERENCE_DATETIME,
decay=DECAY,
noise=NOISE,
engagement=ENGAGEMENT
weights=WEIGHTS
)
Ranker
todo
# todo
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for twon_ranker-0.0.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ed16345c6f0f86d80e4556e8cdc5e5f216544322a54b801a64e5fea766d6b90f |
|
MD5 | b7e1e5ca36e7414a3b23264e0fa9abdc |
|
BLAKE2b-256 | 0a4a263f5d2dba48e1ca27ac4a252051975878763b8013ff715ef7285569f3b4 |