API Reference

This part of the documentation covers all the interfaces of twinl.

Main interface

All of the twinls’ functionality can be accessed by the following functions and classes.

twixl.collections.twinl.search(query, start_time=None, end_time=None, max_results=None, api=None, callback=None)[source]

Sends a TwiXL search query.

Parameters:

query (Query) – A TwiXL query object that describes the search query.
start_time (Optional[datetime]) – The oldest UTC timestamp from which the Tweets will be provided.
end_time (Optional[datetime]) – The newest UTC timestamp from which the Tweets will be provided.
(Optional) (callback) – The maximum number of search results in query output. By default, all search results will be stored in the query output.
(Optional) – An initialized twixl Api object. If not provided, an object will be initialized.
(Optional) – Callback function taking a QueryStatus object.

Returns:

SearchReuslts object

Return type:

twinl.SearchResults

Usage:

>>> from twixl.collections import twinl
>>> query = (
>>>   twinl.Query().
>>>       and_(keywords=["example", "query"])
>>> )
>>> search_results = twinl.search(
>>>   query=query,
>>>   start_time=datetime(2022, 1, 1, 0, 0),
>>>   end_time=datetime(2022, 1, 1, 23, 59, 59),
>>>   max_results=100,
>>>   callback=twinl.print_callback
>>> )
Query status: RUNNING (0 Bytes scanned)
Query status: DOWNLOADING_RESULTS (1 GB scanned)
>>> SearchResults
SearchResults(...)

twixl.collections.twinl.word_frequency(date, min_length_words=1, max_results=None, frequency_limit=None, api=None, callback=None)[source]

Sends a word_frequency request to the TwiXL API for the specified date.

Parameters:

date (datetime) – The date for which the word-frequency should be returned.
min_length_words (int) – The minimum word length of the words in the word-frequency list. The default minimum word length is ‘1’.
(Optional) (api) – The maximum number of search results in query output. By default, all search results will be stored in the query output.
(Optional) – The minimum occurence rate of the words in the word-frequency list. The default limit is ‘1’.
(Optional) – An initialized twixl Api object. If not provided, an object will be initialized.

Returns:

WordFrequencyResults object

Return type:

twinl.WordFrequencyResults

Usage:

>>> from twixl.collections import twinl
>>> word_frequencies = twinl.word_frequency(
>>>   date=datetime(2022, 1, 1),
>>>   min_length_words=2,
>>>   callback=twinl.print_callback
>>> )
Query status: RUNNING (0 Bytes scanned)
Query status: DOWNLOADING_RESULTS (1.0 GB scanned)
>>> word_frequencies.to_pandas()
  word        frequency
0 example     100
1 words       50

twixl.collections.twinl.tweet_metrics(api=None)[source]

Sends a get metrics request to the TwiXL Api and returns the results.

Parameters:: (Optional) (api) – An initialized twixl Api object. If not provided, an object will be initialized.
Returns:: TweetMetrics object
Return type:: twinl.TweetMetrics

Usage:

>>> from twixl.collections import twinl
>>> metrics = twinl.tweet_metrics()
>>> merics.to_pandas()

class twixl.collections.twinl.Query[source]

A TwiXL query object to define a search query.

from_userids(userids, overwrite=False)[source]

Add a query statement that matches any tweet from the specific userid(s) to the TwiXL.Query object.

Parameters:: userids (List[str]) – A list of user’s numeric user ID’s
Return type:: Query
Returns:: Query object
Rtpe:: twinl:Query

Usage:

>>> from twixl.collections import Query
>>> Query().from_userids(userids=['twitterdev', 'twitterapi'])

from_usernames(usernames, overwrite=False)[source]

Add a query statement that matches any tweet from the specific username(s) to the TwiXL.Query object.

Parameters:: usernames (List[str]) – A list of usernames (excluding the @ character)
Return type:: Query
Returns:: Query object
Rtpe:: twinl:Query

Usage:

>>> from twixl.collections import Query
>>> Query().from_usernames(usernames=['twitterdev', 'twitterapi'])

keywords(keywords)[source]

Add a query statement that matches any tweet with the specified keyword(s).

Parameters:: regex – A list of words
Return type:: Query
Returns:: Query object
Rtpe:: twinl:Query

Usage:

>>> from twixl.collections import Query
>>> Query().keywords(regex=['twitter', 'tweet'])

print()[source]

Print query.

Return type:: None

regex(regex)[source]

Add a query statement that matches any tweet with the specified regular expression(s).

Parameters:: regex (List[str]) – A list of regular expressions
Return type:: Query
Returns:: Query object
Rtpe:: twinl:Query

Usage:

>>> from twixl.collections import Query
>>> Query().regex(regex=['twit\w+'])

to_dict()[source]

Returns the TwiXL query as a dict.

Returns:: Query object as dictionary.
Return type:: dict

url(url_regex)[source]

Add a query statement that matches any tweet that contains one of the specified URLs to the TwiXL.Query object.

Parameters:: url – List of url’s or regular expressions
Returns:: Query object
Return type:: twinl.Query

Usage:

>>> from twixl.collections import Query
>>> Query().url(url_regex: ["twitter.com/twitter*"])

twixl.collections.twinl.API(api_endpoint, api_key)[source]

Plotting functons

This section of the documentation covers all the plotting functions.

twixl.collections.twinl.plotting.plot_tweet_frequencies(search_results, num_xticks=5, title='Number of tweets per day')[source]

Plot the TwiXL Query result in a frequency plot.

Parameters:

search_results (SearchResults) – Twinl search results.
num_xticks (int) –
(Optional) (title) – The figure title.

Return type:

Tuple[Figure, Axes]

Returns:

Tweet frequency figure.

Usage:

>>> from twixl.collections import twinl
>>> twinl.plotting.plot_tweet_frequencies(
>>>   search_results,
>>>   title="Number of 'Elfstedentocht' tweets per day"
>>> )
(<Figure>, <AxesSubplot>)

twixl.collections.twinl.plotting.plot_word_cloud(word_frequency_results, width=800, height=400, max_words=200, stopwords=None, background_color='white', min_word_length=0)[source]

Plots the word-frequency list as a wordcloud.

Parameters:

word_frequency_results (WordFrequencyResults) – Word frequency results.
width (int) – Width of the canvas.
height (int) – Height of the canvas.
max_words (int) – The maximum number of words in the wordcloud.
stopwords (Optional[List[str]]) – A list of stopwords that should be filtered from the wordcloud.
background_color (str) – Background color for the word cloud image.
min_word_length (int) – Minimum number of letters a word must have to be included.

Return type:

Figure

Returns:

Word cloud plot

Usage:

>>> from twixl.collections import twinl
>>> twinl.plotting.plot_word_cloud(
>>>   word_frequencies,
>>>   stopwords=stopwords,
>>>   max_words=100,
>>>   min_word_length=4
>>> );
<matplotlib.image.AxesImage>

twixl.collections.twinl.plotting.plot_circular_bars(word_frequency_results, stopwords=None, group_size=5)[source]

Plots the word-frequency list as a circular bar plot.

Parameters:

stopwords (Optional[List[str]]) – A list of stopwords that should be filtered from the wordcloud.
group_size (int) – The number of bars per hour.

Return type:

Tuple[Figure, Axes]

Usage:

>>> from twixl.collections import twinl
>>> twinl.plotting.plot_circular_bars(
>>>   word_frequencies,
>>>   stopwords=stopwords,
>>>   group_size=3
>>> );
(<Figure>, <PolarAxesSubplot>)

Exceptions

This section of the documentation covers all the exceptions.

exception twixl.collections.twinl.exceptions.QueryFailed(message='query has failed')[source]: The query failed.

exception twixl.collections.twinl.exceptions.QueryCanceled(message='query was canceled')[source]: The query is canceled.

exception twixl.collections.twinl.exceptions.QueryTimeout(timeout)[source]: The query timed out.

Lower-Level Classes

class twixl.collections.twinl.SearchResults(tweets)[source]

SearchReults object.

tweets

List with TweetMetadata.

Type:: List

static from_file(path)[source]

Read the file from the given path and return a QueryResults data object.

Parameters:: path (Path) – source file path
Return type:: SearchResults

to_pandas()[source]

Return the word frequency data as a pandas dataframe.

Return type:: DataFrame

class twixl.collections.twinl.WordFrequencyResults(words)[source]

WordFrequencyResults object.

tweets

List with WordFrequencydataGroupedByHour.

Type:: List

static from_file(path)[source]

Read the file from the given path and return a WordFrequency data object.

Parameters:: path (Path) – source file path
Return type:: WordFrequencyResults

to_pandas(by_hour=False)[source]

Return the word frequency data as a pandas dataframe.

Parameters:: (default=false) (by_hour) – group the frequency list by hour
Return type:: DataFrame

class twixl.collections.twinl.TweetMetrics(metrics)[source]