Package tomotopy

tomotopy 패키지는 Python에서 사용가능한 다양한 토픽 모델링 타입과 함수를 제공합니다. 내부 모듈은 c++로 작성되었기 때문에 빠른 속도를 자랑합니다.

tomotopy 란?

tomotopy는 토픽 모델링 툴인 tomoto의 Python 확장 버전입니다. tomoto는 c++로 작성된 깁스 샘플링 기반의 토픽 모델링 라이브러리로, 최신 CPU의 벡터화 기술을 활용하여 처리 속도를 최대로 끌어올렸습니다. 현재 버전의 tomoto에서는 다음과 같은 주요 토픽 모델들을 지원하고 있습니다.

tomotopy의 가장 최신버전은 0.10.0 입니다.

Star Issue

시작하기

다음과 같이 pip를 이용하면 tomotopy를 쉽게 설치할 수 있습니다. (https://pypi.org/project/tomotopy/) ::

$ pip install --upgrade pip
$ pip install tomotopy

지원하는 운영체제 및 Python 버전은 다음과 같습니다:

  • Python 3.5 이상이 설치된 Linux (x86-64)
  • Python 3.5 이상이 설치된 macOS 10.13나 그 이후 버전
  • Python 3.5 이상이 설치된 Windows 7이나 그 이후 버전 (x86, x86-64)
  • Python 3.5 이상이 설치된 다른 운영체제: 이 경우는 c++11 호환 컴파일러를 통한 소스코드 컴파일이 필요합니다.

설치가 끝난 뒤에는 다음과 같이 Python3에서 바로 import하여 tomotopy를 사용할 수 있습니다. ::

import tomotopy as tp
print(tp.isa) # 'avx2'나 'avx', 'sse2', 'none'를 출력합니다.

현재 tomotopy는 가속을 위해 AVX2, AVX or SSE2 SIMD 명령어 세트를 활용할 수 있습니다. 패키지가 import될 때 현재 환경에서 활용할 수 있는 최선의 명령어 세트를 확인하여 최상의 모듈을 자동으로 가져옵니다. 만약 tp.isa가 none이라면 현재 환경에서 활용 가능한 SIMD 명령어 세트가 없는 것이므로 훈련에 오랜 시간이 걸릴 수 있습니다. 그러나 최근 대부분의 Intel 및 AMD CPU에서는 SIMD 명령어 세트를 지원하므로 SIMD 가속이 성능을 크게 향상시킬 수 있을 것입니다.

간단한 예제로 'sample.txt' 파일로 LDA 모델을 학습하는 코드는 다음과 같습니다. ::

import tomotopy as tp
mdl = tp.LDAModel(k=20)
for line in open('sample.txt'):
    mdl.add_doc(line.strip().split())

for i in range(0, 100, 10):
    mdl.train(10)
    print('Iteration: {}\tLog-likelihood: {}'.format(i, mdl.ll_per_word))

for k in range(mdl.k):
    print('Top 10 words of topic #{}'.format(k))
    print(mdl.get_topic_words(k, top_n=10))

mdl.summary()

Tomotopy의 성능

tomotopy는 주제 분포와 단어 분포를 추론하기 위해 Collapsed Gibbs-Sampling(CGS) 기법을 사용합니다. 일반적으로 CGS는 gensim의 LdaModel가 이용하는 Variational Bayes(VB) 보다 느리게 수렴하지만 각각의 반복은 빠르게 계산 가능합니다. 게다가 tomotopy는 멀티스레드를 지원하므로 SIMD 명령어 세트뿐만 아니라 다중 코어 CPU의 장점까지 활용할 수 있습니다. 이 덕분에 각각의 반복이 훨씬 빠르게 계산 가능합니다.

다음의 차트는 tomotopy와 gensim의 LDA 모형 실행 시간을 비교하여 보여줍니다. 입력 문헌은 영어 위키백과에서 가져온 1000개의 임의 문서이며 전체 문헌 집합은 총 1,506,966개의 단어로 구성되어 있습니다. (약 10.1 MB). tomotopy는 200회를, gensim 10회를 반복 학습하였습니다.

↑ Intel i5-6600, x86-64 (4 cores)에서의 성능

↑ Intel Xeon E5-2620 v4, x86-64 (8 cores, 16 threads)에서의 성능

↑ AMD Ryzen7 3700X, x86-64 (8 cores, 16 threads)에서의 성능

tomotopy가 20배 더 많이 반복하였지만 전체 실행시간은 gensim보다 5~10배 더 빨랐습니다. 또한 tomotopy는 전반적으로 안정적인 결과를 보여주고 있습니다.

CGS와 VB는 서로 접근방법이 아예 다른 기법이기 때문에 둘을 직접적으로 비교하기는 어렵습니다만, 실용적인 관점에서 두 기법의 속도와 결과물을 비교해볼 수 있습니다. 다음의 차트에는 두 기법이 학습 후 보여준 단어당 로그 가능도 값이 표현되어 있습니다.

tomotopy가 생성한 주제들의 상위 단어
#1use, acid, cell, form, also, effect
#2use, number, one, set, comput, function
#3state, use, may, court, law, person
#4state, american, nation, parti, new, elect
#5film, music, play, song, anim, album
#6art, work, design, de, build, artist
#7american, player, english, politician, footbal, author
#8appl, use, comput, system, softwar, compani
#9day, unit, de, state, german, dutch
#10team, game, first, club, leagu, play
#11church, roman, god, greek, centuri, bc
#12atom, use, star, electron, metal, element
#13alexand, king, ii, emperor, son, iii
#14languag, arab, use, word, english, form
#15speci, island, plant, famili, order, use
#16work, univers, world, book, human, theori
#17citi, area, region, popul, south, world
#18forc, war, armi, militari, jew, countri
#19year, first, would, later, time, death
#20apollo, use, aircraft, flight, mission, first
gensim이 생성한 주제들의 상위 단어
#1use, acid, may, also, azerbaijan, cell
#2use, system, comput, one, also, time
#3state, citi, day, nation, year, area
#4state, lincoln, american, war, union, bell
#5anim, game, anal, atari, area, sex
#6art, use, work, also, includ, first
#7american, player, english, politician, footbal, author
#8new, american, team, season, leagu, year
#9appl, ii, martin, aston, magnitud, star
#10bc, assyrian, use, speer, also, abort
#11use, arsen, also, audi, one, first
#12algebra, use, set, ture, number, tank
#13appl, state, use, also, includ, product
#14use, languag, word, arab, also, english
#15god, work, one, also, greek, name
#16first, one, also, time, work, film
#17church, alexand, arab, also, anglican, use
#18british, american, new, war, armi, alfr
#19airlin, vote, candid, approv, footbal, air
#20apollo, mission, lunar, first, crew, land

어떤 SIMD 명령어 세트를 사용하는지는 성능에 큰 영향을 미칩니다. 다음 차트는 SIMD 명령어 세트에 따른 성능 차이를 보여줍니다.

다행히도 최신 x86-64 CPU들은 대부분 AVX2 명령어 세트를 지원하기 때문에 대부분의 경우 AVX2의 높은 성능을 활용할 수 있을 것입니다.

Cf와 Df를 이용한 어휘 통제

CF(collection frequency, 장서 빈도)와 DF(document frequency, 문헌 빈도)는 정보검색에서 다루는 개념들로, 각각 전체 코퍼스 내에서 특정 단어가 등장하는 총 빈도와 전체 코퍼스 내에서 특정 단어가 등장하는 문헌들의 빈도를 가리킵니다. tomotopy는 코퍼스 구축시 저빈도 어휘를 잘라낼 수 있도록 이 두가지 척도를 각각 min_cf와 min_df라는 파라미터로 사용합니다.

구체적으로, 다음처럼 구성된 문헌 #0 ~ #4를 가지고 예를 들어 보자면 ::

#0 : a, b, c, d, e, c
#1 : a, b, e, f
#2 : c, d, c
#3 : a, e, f, g
#4 : a, b, g

a와 c는 각각 전체 코퍼스에서 4번 등장했으므로 CF는 둘 다 4입니다. 반면 a는 #0, #1, #3, #4 문헌에서 등장했으므로 DF가 4지만, c는 #0과 #2에서만 등장했으므로 DF가 2입니다. 따라서 min_cf=3을 기준으로 저빈도 어휘를 잘라낸다면 결과는 다음과 같이 됩니다. ::

(d, f, g 가 삭제됨)
#0 : a, b, c, e, c
#1 : a, b, e
#2 : c, c
#3 : a, e
#4 : a, b

그러나 min_df=3를 기준으로 잘라내면 다음과 같습니다. ::

(c, d, f, g가 삭제됨)
#0 : a, b, e
#1 : a, b, e
#2 : (빈 문헌)
#3 : a, e
#4 : a, b

위 예시에서 확인할 수 있듯 min_df가 min_cf보다 더 강력한 조건입니다. 토픽 모델링을 수행함에 있어 한 문헌에서만 여러 번 등장하는 단어는 전체 토픽-단어 분포를 추정하는데 영향을 미치지 못합니다. 따라서 df가 작은 어휘들을 제거하면 최종 결과에 거의 영향을 미치지 않으며 모델 크기는 크게 줄일 수 있습니다. 그러므로 어휘 크기를 통제할 때는 min_cf보다는 min_df를 사용하는 걸 추천합니다.

모델의 저장과 불러오기

tomotopy는 각각의 토픽 모델 클래스에 대해 save와 load 메소드를 제공합니다. 따라서 학습이 끝난 모델을 언제든지 파일에 저장하거나, 파일로부터 다시 읽어와서 다양한 작업을 수행할 수 있습니다. ::

import tomotopy as tp

mdl = tp.HDPModel()
for line in open('sample.txt'):
    mdl.add_doc(line.strip().split())

for i in range(0, 100, 10):
    mdl.train(10)
    print('Iteration: {}\tLog-likelihood: {}'.format(i, mdl.ll_per_word))

# 파일에 저장
mdl.save('sample_hdp_model.bin')

# 파일로부터 불러오기
mdl = tp.HDPModel.load('sample_hdp_model.bin')
for k in range(mdl.k):
    if not mdl.is_live_topic(k): continue
    print('Top 10 words of topic #{}'.format(k))
    print(mdl.get_topic_words(k, top_n=10))

# 저장된 모델이 HDP 모델이었기 때문에, 
# LDA 모델에서 이 파일을 읽어오려고 하면 예외가 발생합니다.
mdl = tp.LDAModel.load('sample_hdp_model.bin')

파일로부터 모델을 불러올 때는 반드시 저장된 모델의 타입과 읽어올 모델의 타입이 일치해야합니다.

이에 대해서는 LDAModel.save()와 LDAModel.load()에서 더 자세한 내용을 확인할 수 있습니다.

모델 안의 문헌과 모델 밖의 문헌

토픽 모델은 크게 2가지 목적으로 사용할 수 있습니다. 기본적으로는 문헌 집합으로부터 모델을 학습하여 문헌 내의 주제들을 발견하기 위해 토픽 모델을 사용할 수 있으며, 더 나아가 학습된 모델을 활용하여 학습할 때는 주어지지 않았던 새로운 문헌에 대해 주제 분포를 추론하는 것도 가능합니다. 전자의 과정에서 사용되는 문헌(학습 과정에서 사용되는 문헌)을 모델 안의 문헌, 후자의 과정에서 주어지는 새로운 문헌(학습 과정에 포함되지 않았던 문헌)을 모델 밖의 문헌이라고 가리키도록 하겠습니다.

tomotopy에서 이 두 종류의 문헌을 생성하는 방법은 다릅니다. 모델 안의 문헌은 LDAModel.add_doc()을 이용하여 생성합니다. add_doc은 LDAModel.train()을 시작하기 전까지만 사용할 수 있습니다. 즉 train을 시작한 이후로는 학습 문헌 집합이 고정되기 때문에 add_doc을 이용하여 새로운 문헌을 모델 내에 추가할 수 없습니다.

또한 생성된 문헌의 인스턴스를 얻기 위해서는 다음과 같이 LDAModel.docs를 사용해야 합니다.

::

mdl = tp.LDAModel(k=20)
idx = mdl.add_doc(words)
if idx < 0: raise RuntimeError("Failed to add doc")
doc_inst = mdl.docs[idx]
# doc_inst is an instance of the added document

모델 밖의 문헌은 LDAModel.make_doc()을 이용해 생성합니다. make_doc은 add_doc과 반대로 train을 시작한 이후에 사용할 수 있습니다. 만약 train을 시작하기 전에 make_doc을 사용할 경우 올바르지 않은 결과를 얻게 되니 이 점 유의하시길 바랍니다. make_doc은 바로 인스턴스를 반환하므로 반환값을 받아 바로 사용할 수 있습니다.

::

mdl = tp.LDAModel(k=20)
# add_doc ...
mdl.train(100)
doc_inst = mdl.make_doc(unseen_words) # doc_inst is an instance of the unseen document

새로운 문헌에 대해 추론하기

LDAModel.make_doc()을 이용해 새로운 문헌을 생성했다면 이를 모델에 입력해 주제 분포를 추론하도록 할 수 있습니다. 새로운 문헌에 대한 추론은 LDAModel.infer()를 사용합니다.

::

mdl = tp.LDAModel(k=20)
# add_doc ...
mdl.train(100)
doc_inst = mdl.make_doc(unseen_words)
topic_dist, ll = mdl.infer(doc_inst)
print("Topic Distribution for Unseen Docs: ", topic_dist)
print("Log-likelihood of inference: ", ll)

infer 메소드는 Document 인스턴스 하나를 추론하거나 Document 인스턴스의 list를 추론하는데 사용할 수 있습니다. 자세한 것은 LDAModel.infer()을 참조하길 바랍니다.

병렬 샘플링 알고리즘

tomotopy는 0.5.0버전부터 병렬 알고리즘을 고를 수 있는 선택지를 제공합니다. 0.4.2 이전버전까지 제공되던 알고리즘은 COPY_MERGE로 이 기법은 모든 토픽 모델에 사용 가능합니다. 새로운 알고리즘인 PARTITION은 0.5.0이후부터 사용가능하며, 이를 사용하면 더 빠르고 메모리 효율적으로 학습을 수행할 수 있습니다. 단 이 기법은 일부 토픽 모델에 대해서만 사용 가능합니다.

다음 차트는 토픽 개수와 코어 개수에 따라 두 기법의 속도 차이를 보여줍니다.

버전별 속도 차이

아래 그래프는 버전별 속도 차이를 표시한 것입니다. LDA모델로 1000회 iteration을 수행시 걸리는 시간을 초 단위로 표시하였습니다. (Docs: 11314, Vocab: 60382, Words: 2364724, Intel Xeon Gold 5120 @2.2GHz)

어휘 사전분포를 이용하여 주제 고정하기

0.6.0 버전부터 LDAModel.set_word_prior()라는 메소드가 추가되었습니다. 이 메소드로 특정 단어의 사전분포를 조절할 수 있습니다. 예를 들어 다음 코드처럼 단어 'church'의 가중치를 Topic 0에 대해서는 1.0, 나머지 Topic에 대해서는 0.1로 설정할 수 있습니다. 이는 단어 'church'가 Topic 0에 할당될 확률이 다른 Topic에 할당될 확률보다 10배 높다는 것을 의미하며, 따라서 대부분의 'church'는 Topic 0에 할당되게 됩니다. 그리고 학습을 거치며 'church'와 관련된 단어들 역시 Topic 0에 모이게 되므로, 최종적으로 Topic 0은 'church'와 관련된 주제가 될 것입니다. 이를 통해 특정 내용의 주제를 원하는 Topic 번호에 고정시킬 수 있습니다.

::

import tomotopy as tp
mdl = tp.LDAModel(k=20)

# add documents into <code>mdl</code>

# setting word prior
mdl.set_word_prior('church', [1.0 if k == 0 else 0.1 for k in range(20)])

자세한 내용은 example.py의 word_prior_example 함수를 참조하십시오.

예제 코드

tomotopy의 Python3 예제 코드는 https://github.com/bab2min/tomotopy/blob/master/examples/ 를 확인하시길 바랍니다.

예제 코드에서 사용했던 데이터 파일은 https://drive.google.com/file/d/18OpNijd4iwPyYZ2O7pQoPyeTAKEXa71J/view 에서 다운받을 수 있습니다.

라이센스

tomotopy는 MIT License 하에 배포됩니다.

역사

  • 0.10.0 (2020-12-19)

    • Corpus와 LDAModel.docs 간의 인터페이스가 통일되었습니다. 이제 동일한 방법으로 코퍼스 내의 문헌들에 접근할 수 있습니다.
    • Corpus의 __getitem__이 개선되었습니다. int 타입 인덱싱뿐만 아니라 Iterable[int]나 slicing를 이용한 다중 인덱싱, uid를 이용한 인덱싱 등이 제공됩니다.
    • Corpus.extract_ngrams()와 Corpus.concat_ngrams()이 추가되었습니다. PMI를 이용해 코퍼스 내에서 자동으로 n-gram collocation을 발견해 한 단어로 합치는 기능을 수행합니다.
    • LDAModel.add_corpus()가 추가되었고, LDAModel.infer()가 Raw 코퍼스를 입력으로 받을 수 있게 되었습니다.
    • tomotopy.coherence 모듈이 추가되었습니다. 생성된 토픽 모델의 coherence를 계산하는 기능을 담당합니다.
    • FoRelevance에 window_size 파라미터가 추가되었습니다.
    • HDPModel 학습 시 종종 NaN이 발생하는 문제를 해결했습니다.
    • 이제 Python3.9를 지원합니다.
    • py-cpuinfo에 대한 의존성이 제거되고, 모듈 로딩속도가 개선되었습니다.

  • 0.9.1 (2020-08-08)

    • 0.9.0 버전의 메모리 누수 문제가 해결되었습니다.
    • LDAModel.summary()가 잘못된 결과를 출력하는 문제가 해결되었습니다.

  • 0.9.0 (2020-08-04)

  • 0.8.2 (2020-07-14)

    • DTModel.num_timepoints와 DTModel.num_docs_by_timepoint 프로퍼티가 추가되었습니다.
    • seed가 동일해도 플랫폼이 다르면 다른 결과를 내던 문제가 일부 해결되었습니다. 이로 인해 32bit 버전의 모델 학습 결과가 이전 버전과는 달라졌습니다.

  • 0.8.1 (2020-06-08)

  • 0.8.0 (2020-06-06)

    • NumPy가 tomotopy에 도입됨에 따라 많은 메소드와 프로퍼티들이 list가 아니라 numpy.ndarray를 반환하도록 변경되었습니다.
    • Tomotopy에 새 의존관계 NumPy >= 1.10.0가 추가되었습니다..
    • LDAModel.infer()가 잘못된 추론을 하던 문제가 수정되었습니다.
    • HDP 모델을 LDA 모델로 변환하는 메소드가 추가되었습니다.
    • LDAModel.used_vocabs, LDAModel.used_vocab_freq, LDAModel.used_vocab_df 등의 새로운 프로퍼티가 모델에 추가되었습니다.
    • 새로운 토픽 모델인 g-DMR(GDMRModel)가 추가되었습니다.
    • macOS에서 FoRelevance를 생성할 때 발생하던 문제가 해결되었습니다.
    • Corpus.add_doc()로 raw가 없는 문헌을 생성한 뒤 토픽 모델에 입력할 시 발생하는 오류를 수정했습니다.

  • 0.7.1 (2020-05-08)

    • HLDAModel용으로 Document.path가 새로 추가되었습니다.
    • PMIExtractor 사용시에 발생하던 메모리 문제가 해결되었습니다.
    • gcc 7에서 발생하던 컴파일 오류가 해결되었습니다.

  • 0.7.0 (2020-04-18)

    • DTModel이 추가되었습니다.
    • Corpus.save()가 제대로 작동하지 않는 버그가 수정되었습니다.
    • Document.get_count_vector()가 추가되었습니다.
    • 리눅스용 바이너리가 manylinux2010 버전으로 변경되었고 이에 따른 최적화가 진행되었습니다.

  • 0.6.2 (2020-03-28)

    • save와 load에 관련된 치명적인 버그가 수정되었습니다. 해당 버그로 0.6.0 및 0.6.1 버전은 릴리즈에서 삭제되었습니다.

  • 0.6.1 (2020-03-22) (삭제됨)

    • 모듈 로딩과 관련된 버그가 수정되었습니다.

  • 0.6.0 (2020-03-22) (삭제됨)

    • 대량의 문헌을 관리하기 위한 Corpus가 추가되었습니다.
    • 어휘-주제 분포의 사전 확률을 조절할 수 있는 LDAModel.set_word_prior() 메소드가 추가되었습니다.
    • 문헌 빈도를 기반으로 어휘를 필터링할 수 있도록 토픽 모델의 생성자에 min_df가 추가되었습니다.
    • 토픽 라벨링 관련 서브모듈인 tomotopy.label이 추가되었습니다. 현재는 FoRelevance만 제공됩니다.

  • 0.5.2 (2020-03-01)

    • LLDAModel.add_doc() 실행시 segmentation fault가 발생하는 문제를 해결했습니다.
    • HDPModel에서 infer 실행시 종종 프로그램이 종료되는 문제를 해결했습니다.
    • LDAModel.infer()에서 ps=tomotopy.ParallelScheme.PARTITION, together=True로 실행시 발생하는 오류를 해결했습니다.

  • 0.5.1 (2020-01-11)

    • SLDAModel.make_doc()에서 결측값을 지원하지 않던 문제를 해결했습니다.
    • SLDAModel이 이제 결측값을 지원합니다. 결측값을 가진 문헌은 토픽 모델링에는 참여하지만, 응답 변수 회귀에서는 제외됩니다.

  • 0.5.0 (2019-12-30)

    • PAModel.infer()가 topic distribution과 sub-topic distribution을 동시에 반환합니다.
    • Document에 get_sub_topics, get_sub_topic_dist 메소드가 추가되었습니다. (PAModel 전용)
    • LDAModel.train() 및 LDAModel.infer() 메소드에 parallel 옵션이 추가되었습니다. 이를 통해 학습 및 추론시 사용할 병렬화 알고리즘을 선택할 수 있습니다.
    • ParallelScheme.PARTITION 알고리즘이 추가되었습니다. 이 알고리즘은 작업자 수가 많거나 토픽의 개수나 어휘 크기가 클 때도 효율적으로 작동합니다.
    • 모델 생성시 min_cf < 2일때 rm_top 옵션이 적용되지 않는 문제를 수정하였습니다.

  • 0.4.2 (2019-11-30)

    • LLDAModel와 PLDAModel 모델에서 토픽 할당이 잘못 일어나던 문제를 해결했습니다.
    • Document 및 tomotopy.Dictionary 클래스에 가독성이 좋은 __repr__가 추가되었습니다.

  • 0.4.1 (2019-11-27)

    • PLDAModel 생성자의 버그를 수정했습니다.

  • 0.4.0 (2019-11-18)

  • 0.3.1 (2019-11-05)

    • min_cf 혹은 rm_top가 설정되었을 때 get_topic_dist()의 반환값이 부정확한 문제를 수정하였습니다.
    • MGLDAModel 모델의 문헌의 get_topic_dist()가 지역 토픽에 대한 분포도 함께 반환하도록 수정하였습니다..
    • tw=ONE일때의 학습 속도가 개선되었습니다.

  • 0.3.0 (2019-10-06)

    • LLDAModel 토픽 모델이 새로 추가되었습니다.
    • HDPModel을 학습할 때 프로그램이 종료되는 문제를 해결했습니다.
    • HDPModel의 하이퍼파라미터 추정 기능이 추가되었습니다. 이 때문에 새 버전의 HDPModel 결과는 이전 버전과 다를 수 있습니다. 이전 버전처럼 하이퍼파라미터 추정을 끄려면, optim_interval을 0으로 설정하십시오.

  • 0.2.0 (2019-08-18)

    • CTModel와 SLDAModel 토픽 모델이 새로 추가되었습니다.
    • rm_top 파라미터 옵션이 모든 토픽 모델에 추가되었습니다.
    • PAModel과 HPAModel 모델에서 save와 load가 제대로 작동하지 않는 문제를 해결하였습니다.
    • HDPModel 인스턴스를 파일로부터 로딩할 때 종종 프로그램이 종료되는 문제를 해결하였습니다.
    • min_cf > 0으로 설정하였을 때 ll_per_word 값이 잘못 계산되는 문제를 해결하였습니다.

  • 0.1.6 (2019-08-09)

    • macOS와 clang에서 제대로 컴파일되지 않는 문제를 해결했습니다.

  • 0.1.4 (2019-08-05)

    • add_doc 메소드가 빈 리스트를 받았을 때 발생하는 문제를 해결하였습니다.
    • PAModel.get_topic_words()가 하위토픽의 단어 분포를 제대로 반환하지 못하는 문제를 해결하였습니다.

  • 0.1.3 (2019-05-19)

    • min_cf 파라미터와 불용어 제거 기능이 모든 토픽 모델에 추가되었습니다.

  • 0.1.0 (2019-05-12)

    • tomotopy의 최초 버전
Expand source code 
"""
Python package `tomotopy` provides types and functions for various Topic Model 
including LDA, DMR, HDP, MG-LDA, PA and HPA. It is written in C++ for speed and provides Python extension.

.. include:: ./documentation.rst
"""
from tomotopy._version import __version__
from enum import IntEnum

class TermWeight(IntEnum):
    """
    This enumeration is for Term Weighting Scheme and it is based on following paper:
    
    > * Wilson, A. T., & Chew, P. A. (2010, June). Term weighting schemes for latent dirichlet allocation. In human language technologies: The 2010 annual conference of the North American Chapter of the Association for Computational Linguistics (pp. 465-473). Association for Computational Linguistics.
    
    There are three options for term weighting and the basic one is ONE. The others also can be applied for all topic models in `tomotopy`. 
    """

    ONE = 0
    """ Consider every term equal (default)"""

    IDF = 1
    """ 
    Use Inverse Document Frequency term weighting.
    
    Thus, a term occurring at almost every document has very low weighting
    and a term occurring at a few document has high weighting. 
    """

    PMI = 2
    """
    Use Pointwise Mutual Information term weighting.
    """

class ParallelScheme(IntEnum):
    """
    This enumeration is for Parallelizing Scheme:
    There are three options for parallelizing and the basic one is DEFAULT. Not all models supports all options. 
    """

    DEFAULT = 0
    """tomotopy chooses the best available parallelism scheme for your model"""

    NONE = 1
    """ 
    Turn off multi-threading for Gibbs sampling at training or inference. Operations other than Gibbs sampling may use multithreading.
    """

    COPY_MERGE = 2
    """
    Use Copy and Merge algorithm from AD-LDA. It consumes RAM in proportion to the number of workers. 
    This has advantages when you have a small number of workers and a small number of topics and vocabulary sizes in the model.
    Prior to version 0.5, all models used this algorithm by default. 
    
    > * Newman, D., Asuncion, A., Smyth, P., & Welling, M. (2009). Distributed algorithms for topic models. Journal of Machine Learning Research, 10(Aug), 1801-1828.
    """

    PARTITION = 3
    """
    Use Partitioning algorithm from PCGS. It consumes only twice as much RAM as a single-threaded algorithm, regardless of the number of workers.
    This has advantages when you have a large number of workers or a large number of topics and vocabulary sizes in the model.
    
    > * Yan, F., Xu, N., & Qi, Y. (2009). Parallel inference for latent dirichlet allocation on graphics processing units. In Advances in neural information processing systems (pp. 2134-2142).
    """

isa = ''
"""
Indicate which SIMD instruction set is used for acceleration.
It can be one of `'avx2'`, `'avx'`, `'sse2'` and `'none'`.
"""

from _tomotopy import *

import tomotopy.utils as utils
import tomotopy.coherence as coherence
import tomotopy.label as label

import os
if os.environ.get('TOMOTOPY_LANG') == 'kr':
    __doc__ = """`tomotopy` 패키지는 Python에서 사용가능한 다양한 토픽 모델링 타입과 함수를 제공합니다.
내부 모듈은 c++로 작성되었기 때문에 빠른 속도를 자랑합니다.

.. include:: ./documentation.kr.rst
"""
    __pdoc__ = {}
    __pdoc__['isa'] = """현재 로드된 모듈이 어떤 SIMD 명령어 세트를 사용하는지 표시합니다. 
이 값은 `'avx2'`, `'avx'`, `'sse2'`, `'none'` 중 하나입니다."""
    __pdoc__['TermWeight'] = """용어 가중치 기법을 선택하는 데에 사용되는 열거형입니다. 여기에 제시된 용어 가중치 기법들은 다음 논문을 바탕으로 하였습니다:
    
> * Wilson, A. T., & Chew, P. A. (2010, June). Term weighting schemes for latent dirichlet allocation. In human language technologies: The 2010 annual conference of the North American Chapter of the Association for Computational Linguistics (pp. 465-473). Association for Computational Linguistics.

총 3가지 가중치 기법을 사용할 수 있으며 기본값은 ONE입니다. 기본값뿐만 아니라 다른 모든 기법들도 `tomotopy`의 모든 토픽 모델에 사용할 수 있습니다. """
    __pdoc__['TermWeight.ONE'] = """모든 용어를 동일하게 간주합니다. (기본값)"""
    __pdoc__['TermWeight.IDF'] = """역문헌빈도(IDF)를 가중치로 사용합니다.

따라서 모든 문헌에 거의 골고루 등장하는 용어의 경우 낮은 가중치를 가지게 되며, 
소수의 특정 문헌에만 집중적으로 등장하는 용어의 경우 높은 가중치를 가지게 됩니다."""
    __pdoc__['TermWeight.PMI'] = """점별 상호정보량(PMI)을 가중치로 사용합니다."""
    __pdoc__['ParallelScheme'] = """병렬화 기법을 선택하는 데에 사용되는 열거형입니다. 총 3가지 기법을 사용할 수 있으나, 모든 모델이 아래의 기법을 전부 지원하지는 않습니다."""
    __pdoc__['ParallelScheme.DEFAULT'] = """tomotopy가 모델에 따라 적합한 병럴화 기법을 선택하도록 합니다. 이 값이 기본값입니다."""
    __pdoc__['ParallelScheme.NONE'] = """깁스 샘플링에 병렬화 기법을 사용하지 않습니다. 깁스 샘플링을 제외한 다른 연산들은 여전히 병렬로 처리될 수 있습니다."""
    __pdoc__['ParallelScheme.COPY_MERGE'] = """
AD-LDA에서 제안된 복사 후 합치기 알고리즘을 사용합니다. 이는 작업자 수에 비례해 메모리를 소모합니다. 
작업자 수가 적거나, 토픽 개수 혹은 어휘 집합의 크기가 작을 때 유리합니다.
0.5버전 이전까지는 모든 모델은 이 알고리즘을 기본으로 사용했습니다.
    
> * Newman, D., Asuncion, A., Smyth, P., & Welling, M. (2009). Distributed algorithms for topic models. Journal of Machine Learning Research, 10(Aug), 1801-1828.
"""
    __pdoc__['ParallelScheme.PARTITION'] =     """
PCGS에서 제안된 분할 샘플링 알고리즘을 사용합니다. 작업자 수에 관계없이 단일 스레드 알고리즘에 비해 2배의 메모리만 소모합니다.
작업자 수가 많거나, 토픽 개수 혹은 어휘 집합의 크기가 클 때 유리합니다.
    
> * Yan, F., Xu, N., & Qi, Y. (2009). Parallel inference for latent dirichlet allocation on graphics processing units. In Advances in neural information processing systems (pp. 2134-2142).
"""
del IntEnum, os

Sub-modules

tomotopy.coherence

추가된 버전: 0.10.0 …

tomotopy.label

tomotopy.label 서브모듈은 자동 토픽 라벨링 기법을 제공합니다. 아래에 나온 코드처럼 간단한 작업을 통해 토픽 모델의 결과에 이름을 붙일 수 있습니다. 그 결과는 코드 하단에 첨부되어 있습니다 …

tomotopy.utils

tomotopy.utils 서브모듈은 토픽 모델링에 유용한 여러 유틸리티를 제공합니다. Corpus 클래스는 대량의 문헌을 관리할 수 있게 돕습니다. Corpus에 입력된 문헌들은 다양한 토픽 모델에 바로 입력될 수 있습니다. …

Global variables

var isa

현재 로드된 모듈이 어떤 SIMD 명령어 세트를 사용하는지 표시합니다. 이 값은 'avx2', 'avx', 'sse2', 'none' 중 하나입니다.

Classes

class CTModel (*args, **kwargs)

추가된 버전: 0.2.0

이 타입은 Correlated Topic Model (CTM)의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Blei, D., & Lafferty, J. (2006). Correlated topic models. Advances in neural information processing systems, 18, 147.
  • Mimno, D., Wallach, H., & McCallum, A. (2008, December). Gibbs sampling for logistic normal topic models with graph-based priors. In NIPS Workshop on Analyzing Graphs (Vol. 61).

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int

추가된 버전: 0.6.0

단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.

rm_top : int
제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.
k : int
토픽의 개수, 1 ~ 32767 사이의 정수
smoothing_alpha : float
토픽 개수가 0이 되는걸 방지하는 평탄화 계수
eta : float
토픽-단어 디리클레 분포의 하이퍼 파라미터
seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus

추가된 버전: 0.6.0

토픽 모델에 추가될 문헌들의 집합을 지정합니다.

transform : Callable[dict, dict]

추가된 버전: 0.6.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

부모 클래스

인스턴스 변수

var alpha

이 프로퍼티는 CTModel에서 사용불가합니다. 대신 CTModel.prior_mean와 CTModel.prior_cov를 사용하십시오.

추가된 버전: 0.9.1

var num_beta_sample

beta 파라미터를 표집하는 횟수, 기본값은 10.

CTModel은 각 문헌마다 총 num_beta_sample 개수의 beta 파라미터를 표집합니다. beta 파라미터를 더 많이 표집할 수록, 전체 분포는 정교해지지만 학습 시간이 더 많이 걸립니다. 만약 모형 내에 문헌의 개수가 적은 경우 이 값을 크게하면 더 정확한 결과를 얻을 수 있습니다.

var num_tmn_sample

절단된 다변수 정규분포에서 표본을 추출하기 위한 반복 횟수, 기본값은 5.

만약 결과에서 토픽 간 상관관계가 편향되게 나올 경우 이 값을 키우면 편향을 해소하는 데에 도움이 될 수 있습니다.

var prior_cov

토픽의 사전 분포인 로지스틱 정규 분포의 공분산 행렬 (읽기전용)

var prior_mean

토픽의 사전 분포인 로지스틱 정규 분포의 평균 벡터 (읽기전용)

메소드

def get_correlations(self, topic_id=None)

토픽 topic_id와 나머지 토픽들 간의 상관관계를 반환합니다. 반환값은 LDAModel.k 길이의 float의 list입니다.

파라미터

topic_id : Union[int, None]

토픽을 지정하는 [0, k), 범위의 정수

생략 시 상관계수 행렬 전체가 반환됩니다.

상속받은 메소드 및 변수

class DMRModel (*args, **kwargs)

이 타입은 Dirichlet Multinomial Regression(DMR) 토픽 모델의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Mimno, D., & McCallum, A. (2012). Topic models conditioned on arbitrary features with dirichlet-multinomial regression. arXiv preprint arXiv:1206.3278.

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int

추가된 버전: 0.6.0

단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.

rm_top : int

추가된 버전: 0.2.0

제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.

k : int
토픽의 개수, 1 ~ 32767 범위의 정수.
alpha : float
lambdas 파라미터의 평균의 exp의 초기값
eta : float
토픽-단어 디리클레 분포의 하이퍼 파라미터
sigma : float
lambdas 파라미터의 표준 편차
alpha_epsilon : float
exp(lambdas)가 0이 되는 것을 방지하는 평탄화 계수
seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus

추가된 버전: 0.6.0

토픽 모델에 추가될 문헌들의 집합을 지정합니다.

transform : Callable[dict, dict]

추가된 버전: 0.6.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

부모 클래스

Subclasses

인스턴스 변수

var alpha

각 메타데이터별 문헌-토픽 분포의 사전 분포, [k, f] 모양. np.exp(DMRModel.lambdas)와 동일 (읽기전용)

추가된 버전: 0.9.0

var alpha_epsilon

평탄화 계수 alpha-epsilon (읽기전용)

var f

메타데이터 자질 종류의 개수 (읽기전용)

var lambdas

현재 모형의 lambda 파라미터을 보여주는 [k, f] 모양의 float array (읽기전용)

var metadata_dict

tomotopy.Dictionary 타입의 메타데이터 사전 (읽기전용)

var sigma

하이퍼 파라미터 sigma (읽기전용)

메소드

def add_doc(self, words, metadata='')

현재 모델에 metadata를 포함하는 새로운 문헌을 추가하고 추가된 문헌의 인덱스 번호를 반환합니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
metadata : str
문헌의 메타데이터 (예로 저자나 제목, 작성연도 등)
def make_doc(self, words, metadata='')

words 단어를 바탕으로 새로운 문헌인 Document 인스턴스를 반환합니다. 이 인스턴스는 LDAModel.infer() 메소드에 사용될 수 있습니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
metadata : str
문헌의 메타데이터 (예를 들어 저자나 제목, 작성연도 등)

상속받은 메소드 및 변수

class DTModel (*args, **kwargs)

이 타입은 Dynamic Topic Model의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Blei, D. M., & Lafferty, J. D. (2006, June). Dynamic topic models. In Proceedings of the 23rd international conference on Machine learning (pp. 113-120).
  • Bhadury, A., Chen, J., Zhu, J., & Liu, S. (2016, April). Scaling up dynamic topic models. In Proceedings of the 25th International Conference on World Wide Web (pp. 381-390). https://github.com/Arnie0426/FastDTM

추가된 버전: 0.7.0

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int
단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
rm_top : int
제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.
k : int
토픽의 개수, 1 ~ 32767 범위의 정수.
t : int
시점의 개수
alpha_var : float
alpha 파라미터(시점별 토픽 분포)의 전이 분산
eta_var : float
eta 파라미터(문헌별 토픽 분포)의 alpha로부터의 분산
phi_var : float
phi 파라미터(토픽별 단어 분포)의 전이 분산
lr_a : float
SGLD의 스텝 크기 e_i = a * (b + i) ^ (-c) 계산하는데 사용되는 0보다 큰 a값
lr_b : float
SGLD의 스텝 크기 e_i = a * (b + i) ^ (-c) 계산하는데 사용되는 0 이상의 b값
lr_c : float
SGLD의 스텝 크기 e_i = a * (b + i) ^ (-c) 계산하는데 사용되는 (0.5, 1] 범위의 c값
seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus
토픽 모델에 추가될 문헌들의 집합을 지정합니다.
transform : Callable[dict, dict]
특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

부모 클래스

인스턴스 변수

var alpha

문헌별 토픽 분포, [num_timepoints, k] 모양 (읽기전용)

추가된 버전: 0.9.0

var eta

이 프로퍼티는 DTModel에서 사용불가합니다. 대신 DTModel.docs[x].eta를 사용하십시오.

추가된 버전: 0.9.0

var lr_a

SGLD의 스텝 크기를 결정하는 0보다 큰 파라미터 a (e_i = a * (b + i) ^ -c)

var lr_b

SGLD의 스텝 크기를 결정하는 0 이상의 파라미터 b (e_i = a * (b + i) ^ -c)

var lr_c

SGLD의 스텝 크기를 결정하는 (0.5, 1] 범위의 파라미터 c (e_i = a * (b + i) ^ -c)

var num_docs_by_timepoint

각 시점별 모델 내 문헌 개수 (읽기전용)

var num_timepoints

모델의 시점 개수 (읽기전용)

메소드

def add_doc(self, words, timepoint=0)

현재 모델에 timepoint 시점의 새로운 문헌을 추가하고 추가된 문헌의 인덱스 번호를 반환합니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
timepoint : int
시점을 나타내는 [0, t) 범위의 정수
def get_alpha(self, timepoint)

timepoint 시점에 대한 alpha 파라미터의 리스트를 반환합니다.

파라미터

timepoint : int
시점을 나타내는 [0, t) 범위의 정수
def get_count_by_topics(self)

각각의 시점과 토픽에 할당된 단어의 개수를 [num_timepoints, k] 모양으로 반환합니다.

추가된 버전: 0.9.0

def get_phi(self, timepoint, topic_id)

timepoint 시점의 topic_id에 대한 phi 파라미터의 리스트를 반환합니다.

파라미터

timepoint : int
시점을 나타내는 [0, t) 범위의 정수
topic_id : int
토픽을 나타내는 [0, k) 범위의 정수
def get_topic_word_dist(self, topic_id, timepoint)

시점 timepoint의 토픽 topic_id의 단어 분포를 반환합니다. 반환하는 값은 현재 토픽 내 각각의 단어들의 발생확률을 나타내는 len(vocabs)개의 소수로 구성된 list입니다.

파라미터

topic_id : int
토픽을 가리키는 [0, k) 범위의 정수
timepoint : int
시점을 가리키는 [0, t) 범위의 정수
def get_topic_words(self, topic_id, timepoint, top_n=10)

시점 timepoint의 토픽 topic_id에 속하는 상위 top_n개의 단어와 각각의 확률을 반환합니다. 반환 타입은 (단어:str, 확률:float) 튜플의 list형입니다.

파라미터

topic_id : int
토픽을 가리키는 [0, k) 범위의 정수
timepoint : int
시점을 가리키는 [0, t) 범위의 정수
def make_doc(self, words, timepoint=0)

words 단어를 바탕으로 새로운 문헌인 Document 인스턴스를 반환합니다. 이 인스턴스는 LDAModel.infer() 메소드에 사용될 수 있습니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
timepoint : int
시점을 나타내는 [0, t) 범위의 정수

상속받은 메소드 및 변수

class Document (*args, **kwargs)

이 타입은 토픽 모델에 사용되는 문헌들에 접근할 수 있는 추상 인터페이스을 제공합니다.

인스턴스 변수

var beta

문헌의 각 토픽별 beta 파라미터를 보여주는 list (CTModel 모형에서만 사용됨, 읽기전용)

추가된 버전: 0.2.0

var eta

문헌의 eta 파라미터(토픽 분포)를 나타내는 list (DTModel 모형에서만 사용됨, 읽기전용)

추가된 버전: 0.7.0

var labels

문헌에 매겨진 (레이블, 레이블에 속하는 각 주제의 확률들)의 list (LLDAModel, PLDAModel 모형에서만 사용됨 , 읽기전용)

추가된 버전: 0.3.0

var metadata

문헌의 메타데이터 (DMRModel과 GDMRModel 모형에서만 사용됨, 읽기전용)

var path

주어진 문헌에 대한 깊이별 토픽 번호의 list (HLDAModel 모형에서만 사용됨, 읽기전용)

추가된 버전: 0.7.1

var raw

문헌의 가공되지 않는 전체 텍스트 (읽기전용)

var span

문헌의 각 단어 토큰의 구간(시작 지점과 끝 지점의 tuple) (읽기전용)

var subtopics

문헌의 단어들이 각각 할당된 하위 토픽을 보여주는 list (PAModel와 HPAModel 모형에서만 사용됨, 읽기전용)

var timepoint

문헌의 시점 (DTModel 모형에서만 사용됨, 읽기전용)

추가된 버전: 0.7.0

var topics

문헌의 단어들이 각각 할당된 토픽을 보여주는 list (읽기 전용)

PAModel와 HPAModel 모형에서는 이 값이 상위토픽의 ID를 가리킵니다.

var uid

문헌의 고유 ID (읽기전용)

var vars

문헌의 응답 변수를 보여주는 list (SLDAModel 모형에서만 사용됨 , 읽기전용)

추가된 버전: 0.2.0

var weight

문헌의 가중치 (읽기전용)

var windows

문헌의 단어들이 할당된 윈도우의 ID를 보여주는 list (MGLDAModel 모형에서만 사용됨, 읽기전용)

var words

문헌 내 단어들의 ID가 담긴 list (읽기전용)

메소드

def get_count_vector(self)

추가된 버전: 0.7.0

현재 문헌의 카운트 벡터를 반환합니다.

def get_ll(self)

추가된 버전: 0.10.0

현재 문헌의 로그가능도 총합을 반환합니다.

def get_sub_topic_dist(self)

추가된 버전: 0.5.0

현재 문헌의 하위 토픽 확률 분포를 list 형태로 반환합니다. (PAModel 전용)

def get_sub_topics(self, top_n=10)

추가된 버전: 0.5.0

현재 문헌의 상위 top_n개의 하위 토픽과 그 확률을 tuple의 list 형태로 반환합니다. (PAModel 전용)

def get_topic_dist(self)

현재 문헌의 토픽 확률 분포를 list 형태로 반환합니다.

def get_topics(self, top_n=10)

현재 문헌의 상위 top_n개의 토픽과 그 확률을 tuple의 list 형태로 반환합니다.

def get_words(self, top_n=10)

추가된 버전: 0.4.2

현재 문헌의 상위 top_n개의 단어와 그 확률을 tuple의 list 형태로 반환합니다.

class GDMRModel (*args, **kwargs)

이 타입은 Generalized DMR(g-DMR) 토픽 모델의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Lee, M., & Song, M. Incorporating citation impact into analysis of research trends. Scientometrics, 1-34.

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int
단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
rm_top : int
제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.
k : int
토픽의 개수, 1 ~ 32767 범위의 정수.
degrees : Iterable[int]

TDF(토픽 분포 함수)로 쓰일 르장드르 다항식의 차수를 나타내는 list. 길이는 메타데이터 변수의 개수와 동일해야 합니다.

기본값은 []으로 이 경우 모델은 어떤 메타데이터 변수도 포함하지 않으므로 LDA 모델과 동일해집니다.

alpha : float
lambdas 파라미터의 평균의 exp의 초기값
eta : float
토픽-단어 디리클레 분포의 하이퍼 파라미터
sigma : float
lambdas 파라미터의 표준 편차
alpha_epsilon : float
exp(lambdas)가 0이 되는 것을 방지하는 평탄화 계수
metadata_range : Iterable[Iterable[float]]

각 메타데이터 변수의 최솟값과 최댓값을 지정하는 list. 길이는 degrees의 길이와 동일해야 합니다.

예를 들어 metadata_range = [(2000, 2017), (0, 1)] 는 첫번째 변수의 범위를 2000에서 2017까지로, 두번째 변수의 범위를 0에서 1까지로 설정하겠다는 뜻입니다. 기본값은 None이며, 이 경우 입력 문헌의 메타데이터로부터 최솟값과 최댓값을 찾습니다.

seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus
토픽 모델에 추가될 문헌들의 집합을 지정합니다.
transform : Callable[dict, dict]
특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

부모 클래스

인스턴스 변수

var degrees

르장드르 다항식의 차수 (읽기전용)

var metadata_range

각 메타데이터 변수의 범위를 나타내는 list (읽기전용)

var sigma0

하이퍼 파라미터 sigma0 (읽기전용)

메소드

def add_doc(self, words, metadata=[])

현재 모델에 metadata를 포함하는 새로운 문헌을 추가하고 추가된 문헌의 인덱스 번호를 반환합니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
metadata : Iterable[float]
문헌의 연속 메타데이터 변수. 길이는 degrees의 길이와 동일해야 합니다.
def make_doc(self, words, metadata=[])

words 단어를 바탕으로 새로운 문헌인 Document 인스턴스를 반환합니다. 이 인스턴스는 LDAModel.infer() 메소드에 사용될 수 있습니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
metadata : Iterable[float]
문헌의 연속 메타데이터 변수. 길이는 degrees의 길이와 동일해야 합니다.
def tdf(self, metadata, normalize=True)

주어진 metadata에 대해 토픽 분포를 계산하여, k 길이의 list로 반환합니다.

파라미터

metadata : Iterable[float]
문헌의 연속 메타데이터 변수. 길이는 degrees의 길이와 동일해야 합니다.
normalize : bool
참인 경우, 각 값이 [0, 1] 범위에 있는 확률 분포를 반환합니다. 거짓인 경우 logit값을 그대로 반환합니다.
def tdf_linspace(self, metadata_start, metadata_stop, num, endpoint=True, normalize=True)

주어진 metadata에 대해 토픽 분포를 계산하여, k 길이의 list로 반환합니다.

파라미터

metadata_start : Iterable[float]
문헌의 연속 메타데이터 변수의 시작값. 길이는 degrees의 길이와 동일해야 합니다.
metadata_stop : Iterable[float]
문헌의 연속 메타데이터 변수의 끝값. 길이는 degrees의 길이와 동일해야 합니다.
num : Iterable[int]
각 메타데이터 변수별로 생성할 샘플의 개수(0보다 큰 정수). 길이는 degrees의 길이와 동일해야 합니다.
endpoint : bool
참인 경우 metadata_stop이 마지막 샘플이 됩니다. 거짓인 경우 끝값이 샘플에 포함되지 않습니다. 기본값은 참입니다.
normalize : bool
참인 경우, 각 값이 [0, 1] 범위에 있는 확률 분포를 반환합니다. 거짓인 경우 logit값을 그대로 반환합니다.

상속받은 메소드 및 변수

class HDPModel (*args, **kwargs)

이 타입은 Hierarchical Dirichlet Process(HDP) 토픽 모델의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Teh, Y. W., Jordan, M. I., Beal, M. J., & Blei, D. M. (2005). Sharing clusters among related groups: Hierarchical Dirichlet processes. In Advances in neural information processing systems (pp. 1385-1392).
  • Newman, D., Asuncion, A., Smyth, P., & Welling, M. (2009). Distributed algorithms for topic models. Journal of Machine Learning Research, 10(Aug), 1801-1828.

0.3.0버전부터 alpha와 gamma에 대한 하이퍼파라미터 추정 기능이 추가되었습니다. optim_interval을 0으로 설정함으로써 이 기능을 끌 수 있습니다.

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int

추가된 버전: 0.6.0

단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.

rm_top : int

추가된 버전: 0.2.0

제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.

initial_k : int
초기 토픽의 개수를 지정하는 2 ~ 32767 범위의 정수.
0.3.0버전부터 기본값이 1에서 2로 변경되었습니다.
alpha : float
document-table에 대한 Dirichlet Process의 집중 계수
eta : float
토픽-단어 디리클레 분포의 하이퍼 파라미터
gamma : float
table-topic에 대한 Dirichlet Process의 집중 계수
seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus

추가된 버전: 0.6.0

토픽 모델에 추가될 문헌들의 집합을 지정합니다.

transform : Callable[dict, dict]

추가된 버전: 0.6.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

부모 클래스

인스턴스 변수

var gamma

하이퍼 파라미터 gamma (읽기전용)

var live_k

현재 모델 내의 유효한 토픽의 개수 (읽기전용)

var num_tables

현재 모델 내의 총 테이블 개수 (읽기전용)

메소드

def convert_to_lda(self, topic_threshold=0.0)

추가된 버전: 0.8.0

현재의 HDP 모델을 동등한 LDA모델로 변환하고, (new_lda_mode, new_topic_id)를 반환합니다. 이 때 topic_threshold보다 작은 비율의 토픽은 new_lda_model에서 제거됩니다.

new_topic_id는 길이 HDPModel.k의 배열이며, new_topic_id[i]는 새 LDA 모델에서 원 HDP 모델의 토픽 i와 동등한 토픽의 id를 가리킵니다. 만약 원 HDP 모델의 토픽 i가 유효하지 않거나, 새 LDA 모델에서 제거된 것이라면, new_topic_id[i]는 -1이 됩니다.

파라미터

topic_threshold : float
이 값보다 작은 비율의 토픽은 새 LDA 모델에서 제거됩니다. 기본값은 0이며, 이 경우 유효하지 않는 토픽을 제외한 모든 토픽이 LDA 모델에 포함됩니다.
def is_live_topic(self, topic_id)

topic_id가 유효한 토픽을 가리키는 경우 True, 아닌 경우 False를 반환합니다.

파라미터

topic_id : int
토픽을 가리키는 [0, k) 범위의 정수

상속받은 메소드 및 변수

class HLDAModel (*args, **kwargs)

이 타입은 Hierarchical LDA 토픽 모델의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Griffiths, T. L., Jordan, M. I., Tenenbaum, J. B., & Blei, D. M. (2004). Hierarchical topic models and the nested Chinese restaurant process. In Advances in neural information processing systems (pp. 17-24).

추가된 버전: 0.4.0

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int

추가된 버전: 0.6.0

단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.

rm_top : int

추가된 버전: 0.2.0

제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.

depth : int
토픽 계층의 깊이를 지정하는 2 ~ 32767 범위의 정수.
alpha : float
문헌-계층 디리클레 분포의 하이퍼 파라미터
eta : float
토픽-단어 디리클레 분포의 하이퍼 파라미터
gamma : float
Dirichlet Process의 집중 계수
seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus

추가된 버전: 0.6.0

토픽 모델에 추가될 문헌들의 집합을 지정합니다.

transform : Callable[dict, dict]

추가된 버전: 0.6.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

부모 클래스

인스턴스 변수

var depth

현재 모델의 총 깊이 (읽기전용)

var gamma

하이퍼 파라미터 gamma (읽기전용)

var live_k

현재 모델 내의 유효한 토픽의 개수 (읽기전용)

메소드

def children_topics(self, topic_id)

topic_id 토픽의 자식 토픽들의 ID를 list로 반환합니다.

파라미터

topic_id : int
토픽을 가리키는 [0, k) 범위의 정수
def is_live_topic(self, topic_id)

topic_id가 유효한 토픽을 가리키는 경우 True, 아닌 경우 False를 반환합니다.

파라미터

topic_id : int
토픽을 가리키는 [0, k) 범위의 정수
def level(self, topic_id)

topic_id 토픽의 레벨을 반환합니다.

파라미터

topic_id : int
토픽을 가리키는 [0, k) 범위의 정수
def num_docs_of_topic(self, topic_id)

topic_id 토픽에 속하는 문헌의 개수를 반환합니다.

파라미터

topic_id : int
토픽을 가리키는 [0, k) 범위의 정수
def parent_topic(self, topic_id)

topic_id 토픽의 부모 토픽의 ID를 반환합니다.

파라미터

topic_id : int
토픽을 가리키는 [0, k) 범위의 정수

상속받은 메소드 및 변수

class HPAModel (*args, **kwargs)

이 타입은 Hierarchical Pachinko Allocation(HPA) 토픽 모델의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Mimno, D., Li, W., & McCallum, A. (2007, June). Mixtures of hierarchical topics with pachinko allocation. In Proceedings of the 24th international conference on Machine learning (pp. 633-640). ACM.

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int

추가된 버전: 0.6.0

단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.

rm_top : int

추가된 버전: 0.2.0

제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.* k1 : 상위 토픽의 개수, 1 ~ 32767 사이의 정수.

k1 : int
상위 토픽의 개수, 1 ~ 32767 사이의 정수
k2 : int
하위 토픽의 개수, 1 ~ 32767 사이의 정수.
alpha : float
문헌-토픽 디리클레 분포의 하이퍼 파라미터
eta : float
토픽-단어 디리클레 분포의 하이퍼 파라미터
seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus

추가된 버전: 0.6.0

토픽 모델에 추가될 문헌들의 집합을 지정합니다.

transform : Callable[dict, dict]

추가된 버전: 0.6.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

부모 클래스

인스턴스 변수

var alpha

문헌의 상위 토픽 분포에 대한 디리클레 분포 파라미터, [k1 + 1] 모양. 0번째 요소는 최상위 토픽을 가리키며, 1 ~ k1번째가 상위 토픽을 가리킨다. (읽기전용)

추가된 버전: 0.9.0

var subalpha

상위 토픽의 하위 토픽 분포에 대한 디리클레 분포 파라미터, [k1, k2 + 1] 모양. [x, 0] 요소는 상위 토픽 x를 가리키며, [x, 1 ~ k2] 요소는 상위 토픽 x 내의 하위 토픽들을 가리킨다. (읽기전용)

추가된 버전: 0.9.0

메소드

def get_topic_word_dist(self, topic_id)

토픽 topic_id의 단어 분포를 반환합니다. 반환하는 값은 현재 하위 토픽 내 각각의 단어들의 발생확률을 나타내는 len(vocabs)개의 소수로 구성된 list입니다.

파라미터

topic_id : int
0일 경우 최상위 토픽을 가리키며, [1, 1 + k1) 범위의 정수는 상위 토픽을, [1 + k1, 1 + k1 + k2) 범위의 정수는 하위 토픽을 가리킵니다.
def get_topic_words(self, topic_id, top_n=10)

토픽 topic_id에 속하는 상위 top_n개의 단어와 각각의 확률을 반환합니다. 반환 타입은 (단어:str, 확률:float) 튜플의 list형입니다.

파라미터

topic_id : int
0일 경우 최상위 토픽을 가리키며, [1, 1 + k1) 범위의 정수는 상위 토픽을, [1 + k1, 1 + k1 + k2) 범위의 정수는 하위 토픽을 가리킵니다.
def infer(self, doc, iter=100, tolerance=-1, workers=0, parallel=0, together=False, transform=None)

새로운 문헌인 doc에 대해 각각의 주제 분포를 추론하여 반환합니다. 반환 타입은 (doc의 주제 분포, 로그가능도) 또는 (doc의 주제 분포로 구성된 list, 로그가능도)입니다.

파라미터

doc : Union[Document, Iterable[Document], Corpus]
추론에 사용할 Document의 인스턴스이거나 이 인스턴스들의 list. 이 인스턴스들은 LDAModel.make_doc() 메소드를 통해 얻을 수 있습니다.
iter : int
doc의 주제 분포를 추론하기 위해 학습을 반복할 횟수입니다. 이 값이 클 수록 더 정확한 결과를 낼 수 있습니다.
tolerance : float
현재는 사용되지 않음
workers : int
깁스 샘플링을 수행하는 데에 사용할 스레드의 개수입니다. 만약 이 값을 0으로 설정할 경우 시스템 내의 가용한 모든 코어가 사용됩니다.
parallel : Union[int, ParallelScheme]

추가된 버전: 0.5.0

추론에 사용할 병렬화 방법. 기본값은 ParallelScheme.DEFAULT로 이는 모델에 따라 최적의 방법을 tomotopy가 알아서 선택하도록 합니다.

together : bool
이 값이 True인 경우 입력한 doc 문헌들을 한 번에 모델에 넣고 추론을 진행합니다. False인 경우 각각의 문헌들을 별도로 모델에 넣어 추론합니다. 기본값은 False입니다.
transform : Callable[dict, dict]

추가된 버전: 0.10.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체. doc이 Corpus의 인스턴스로 주어진 경우에만 사용 가능합니다.

Returns

result : Union[List[float], List[List[float]], Corpus]

doc이 Document로 주어진 경우, result는 문헌의 토픽 분포를 나타내는 List[float]입니다.

doc이 Document의 list로 주어진 경우, result는 문헌의 토픽 분포를 나타내는 List[float]의 list입니다.

doc이 Corpus의 인스턴스로 주어진 경우, result는 추론된 결과 문서들을 담고 있는, Corpus의 새로운 인스턴스입니다. 각 문헌별 토픽 분포를 얻기 위해서는 Document.get_topic_dist()를 사용하면 됩니다.

log_ll : float
각 문헌별 로그 가능도의 리스트

상속받은 메소드 및 변수

class LDAModel (*args, **kwargs)

이 타입은 Latent Dirichlet Allocation(LDA) 토픽 모델의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Blei, D.M., Ng, A.Y., &Jordan, M.I. (2003).Latent dirichlet allocation.Journal of machine Learning research, 3(Jan), 993 - 1022.
  • Newman, D., Asuncion, A., Smyth, P., &Welling, M. (2009).Distributed algorithms for topic models.Journal of Machine Learning Research, 10(Aug), 1801 - 1828.

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int

추가된 버전: 0.6.0

단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.

rm_top : int

추가된 버전: 0.2.0

제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.

k : int
토픽의 개수, 1 ~ 32767 범위의 정수.
alpha : float
문헌-토픽 디리클레 분포의 하이퍼 파라미터
eta : float
토픽-단어 디리클레 분포의 하이퍼 파라미터
seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus

추가된 버전: 0.6.0

토픽 모델에 추가될 문헌들의 집합을 지정합니다.

transform : Callable[dict, dict]

추가된 버전: 0.6.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

Subclasses

Static methods

def load(filename)

filename 경로의 파일로부터 모델 인스턴스를 읽어들여 반환합니다.

인스턴스 변수

var alpha

문헌의 토픽 분포에 대한 디리클레 분포 파라미터 (읽기전용)

var burn_in

파라미터 학습 초기의 Burn-in 단계의 반복 횟수를 얻거나 설정합니다.

기본값은 0입니다.

var docs

현재 모델에 포함된 Document에 접근할 수 있는 list형 인터페이스 (읽기전용)

var eta

하이퍼 파라미터 eta (읽기전용)

var global_step

현재까지 수행된 학습의 총 반복 횟수 (읽기전용)

추가된 버전: 0.9.0

var k

토픽의 개수 (읽기전용)

var ll_per_word

현재 모델의 단어당 로그 가능도 (읽기전용)

var num_vocabs

작은 빈도의 단어들을 제거한 뒤 남은 어휘의 개수 (읽기전용)

train이 호출되기 전에는 이 값은 0입니다.

Deprecated since version: 0.8.0

이 프로퍼티의 이름은 혼동을 일으킬 여지가 있어 제거될 예정입니다. 대신 len(used_vocabs)을 사용하십시오.

var num_words

현재 모델에 포함된 문헌들 전체의 단어 개수 (읽기전용)

train이 호출되기 전에는 이 값은 0입니다.

var optim_interval

파라미터 최적화의 주기를 얻거나 설정합니다.

기본값은 10이며, 0으로 설정할 경우 학습 과정에서 파라미터 최적화를 수행하지 않습니다.

var perplexity

현재 모델의 Perplexity (읽기전용)

var removed_top_words

모델 생성시 rm_top 파라미터를 1 이상으로 설정한 경우, 빈도수가 높아서 모델에서 제외된 단어의 목록을 보여줍니다. (읽기전용)

var tw

현재 모델의 용어 가중치 계획 (읽기전용)

var used_vocab_df

모델에 실제로 사용된 어휘들의 문헌빈도를 보여주는 list (읽기전용)

추가된 버전: 0.8.0

var used_vocab_freq

모델에 실제로 사용된 어휘들의 빈도를 보여주는 list (읽기전용)

var used_vocabs

모델에 실제로 사용된 어휘만을 포함하는 tomotopy.Dictionary 타입의 어휘 사전 (읽기전용)

추가된 버전: 0.8.0

var vocab_df

빈도수로 필터링된 어휘와 현재 모델에 포함된 어휘 전체의 문헌빈도를 보여주는 list (읽기전용)

추가된 버전: 0.8.0

var vocab_freq

빈도수로 필터링된 어휘와 현재 모델에 포함된 어휘 전체의 빈도를 보여주는 list (읽기전용)

var vocabs

빈도수로 필터링된 어휘와 모델에 포함된 어휘 전체를 포함하는 tomotopy.Dictionary 타입의 어휘 사전 (읽기전용)

메소드

def add_corpus(self, corpus, transform=None)

추가된 버전: 0.10.0

코퍼스를 이용해 현재 모델에 새로운 문헌들을 추가하고 추가된 문헌로 구성된 새 코퍼스를 반환합니다. 이 메소드는 LDAModel.train()를 호출하기 전에만 사용될 수 있습니다. Parameters

corpus : Corpus
토픽 모델에 추가될 문헌들로 구성된 코퍼스
transform : Callable[dict, dict]
특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체
def add_doc(self, words)

현재 모델에 새로운 문헌을 추가하고 추가된 문헌의 인덱스 번호를 반환합니다. 이 메소드는 LDAModel.train()를 호출하기 전에만 사용될 수 있습니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
def get_count_by_topics(self)

각각의 토픽에 할당된 단어의 개수를 list형태로 반환합니다.

def get_topic_word_dist(self, topic_id)

토픽 topic_id의 단어 분포를 반환합니다. 반환하는 값은 현재 토픽 내 각각의 단어들의 발생확률을 나타내는 len(vocabs)개의 소수로 구성된 list입니다.

파라미터

topic_id : int
토픽을 가리키는 [0, k) 범위의 정수
def get_topic_words(self, topic_id, top_n=10)

토픽 topic_id에 속하는 상위 top_n개의 단어와 각각의 확률을 반환합니다. 반환 타입은 (단어:str, 확률:float) 튜플의 list형입니다.

파라미터

topic_id : int
토픽을 가리키는 [0, k) 범위의 정수
def get_word_prior(self, word)

추가된 버전: 0.6.0

word에 대한 사전 주제 분포를 반환합니다. 별도로 설정된 값이 없을 경우 빈 리스트가 반환됩니다.

파라미터

word : str
어휘
def infer(self, doc, iter=100, tolerance=-1, workers=0, parallel=0, together=False, transform=None)

새로운 문헌인 doc에 대해 각각의 주제 분포를 추론하여 반환합니다. 반환 타입은 (doc의 주제 분포, 로그가능도) 또는 (doc의 주제 분포로 구성된 list, 로그가능도)입니다.

파라미터

doc : Union[Document, Iterable[Document], Corpus]
추론에 사용할 Document의 인스턴스이거나 이 인스턴스들의 list. 이 인스턴스들은 LDAModel.make_doc() 메소드를 통해 얻을 수 있습니다.
iter : int
doc의 주제 분포를 추론하기 위해 학습을 반복할 횟수입니다. 이 값이 클 수록 더 정확한 결과를 낼 수 있습니다.
tolerance : float
현재는 사용되지 않음
workers : int
깁스 샘플링을 수행하는 데에 사용할 스레드의 개수입니다. 만약 이 값을 0으로 설정할 경우 시스템 내의 가용한 모든 코어가 사용됩니다.
parallel : Union[int, ParallelScheme]

추가된 버전: 0.5.0

추론에 사용할 병렬화 방법. 기본값은 ParallelScheme.DEFAULT로 이는 모델에 따라 최적의 방법을 tomotopy가 알아서 선택하도록 합니다.

together : bool
이 값이 True인 경우 입력한 doc 문헌들을 한 번에 모델에 넣고 추론을 진행합니다. False인 경우 각각의 문헌들을 별도로 모델에 넣어 추론합니다. 기본값은 False입니다.
transform : Callable[dict, dict]

추가된 버전: 0.10.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체. doc이 Corpus의 인스턴스로 주어진 경우에만 사용 가능합니다.

Returns

result : Union[List[float], List[List[float]], Corpus]

doc이 Document로 주어진 경우, result는 문헌의 토픽 분포를 나타내는 List[float]입니다.

doc이 Document의 list로 주어진 경우, result는 문헌의 토픽 분포를 나타내는 List[float]의 list입니다.

doc이 Corpus의 인스턴스로 주어진 경우, result는 추론된 결과 문서들을 담고 있는, Corpus의 새로운 인스턴스입니다. 각 문헌별 토픽 분포를 얻기 위해서는 Document.get_topic_dist()를 사용하면 됩니다.

log_ll : float
각 문헌별 로그 가능도의 리스트
def make_doc(self, words)

words 단어를 바탕으로 새로운 문헌인 Document 인스턴스를 반환합니다. 이 인스턴스는 LDAModel.infer() 메소드에 사용될 수 있습니다..

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
def save(self, filename, full=True)

현재 모델을 filename 경로의 파일에 저장합니다. None을 반환합니다.

full이 True일 경우, 모델의 전체 상태가 파일에 모두 저장됩니다. 저장된 모델을 다시 읽어들여 학습(train)을 더 진행하고자 한다면 full = True로 하여 저장하십시오. 반면 False일 경우, 토픽 추론에 관련된 파라미터만 파일에 저장됩니다. 이 경우 파일의 용량은 작아지지만, 추가 학습은 불가하고 새로운 문헌에 대해 추론(infer)하는 것만 가능합니다.

추가된 버전: 0.6.0

0.6.0 버전부터 모델 파일 포맷이 변경되었습니다. 따라서 0.6.0 이후 버전에서 저장된 모델 파일 포맷은 0.5.2 버전 이전과는 호환되지 않습니다.

def set_word_prior(self, word, prior)

추가된 버전: 0.6.0

어휘-주제 사전 분포를 설정합니다. 이 메소드는 LDAModel.train()를 호출하기 전에만 사용될 수 있습니다.

파라미터

word : str
설정할 어휘
prior : Iterable[float]
어휘 word의 주제 분포. prior의 길이는 LDAModel.k와 동일해야 합니다.
def summary(self, initial_hp=True, params=True, topic_word_top_n=5, file=None, flush=False)

추가된 버전: 0.9.0

현재 모델의 요약 정보를 읽기 편한 형태로 출력합니다.

파라미터

initial_hp : bool
모델 생성 시 초기 파라미터의 표시 여부
params : bool
현재 모델 파라미터의 표시 여부
topic_word_top_n : int
토픽별 출력할 단어의 개수
file
요약 정보를 출력할 대상, 기본값은 sys.stdout
flush : bool
출력 스트림의 강제 flush 여부
def train(self, iter=10, workers=0, parallel=0)

깁스 샘플링을 iter 회 반복하여 현재 모델을 학습시킵니다. 반환값은 None입니다. 이 메소드가 호출된 이후에는 더 이상 LDAModel.add_doc()로 현재 모델에 새로운 학습 문헌을 추가시킬 수 없습니다.

파라미터

iter : int
깁스 샘플링의 반복 횟수
workers : int
깁스 샘플링을 수행하는 데에 사용할 스레드의 개수입니다. 만약 이 값을 0으로 설정할 경우 시스템 내의 가용한 모든 코어가 사용됩니다.
parallel : Union[int, ParallelScheme]

추가된 버전: 0.5.0

학습에 사용할 병렬화 방법. 기본값은 ParallelScheme.DEFAULT로 이는 모델에 따라 최적의 방법을 tomotopy가 알아서 선택하도록 합니다.

class LLDAModel (*args, **kwargs)

이 타입은 Labeled LDA(L-LDA) 토픽 모델의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Ramage, D., Hall, D., Nallapati, R., & Manning, C. D. (2009, August). Labeled LDA: A supervised topic model for credit attribution in multi-labeled corpora. In Proceedings of the 2009 Conference on Empirical Methods in Natural Language Processing: Volume 1-Volume 1 (pp. 248-256). Association for Computational Linguistics.

추가된 버전: 0.3.0

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int

추가된 버전: 0.6.0

단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.

rm_top : int
제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.
k : int
토픽의 개수, 1 ~ 32767 범위의 정수.
alpha : float
문헌-토픽 디리클레 분포의 하이퍼 파라미터
eta : float
토픽-단어 디리클레 분포의 하이퍼 파라미터
seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus

추가된 버전: 0.6.0

토픽 모델에 추가될 문헌들의 집합을 지정합니다.

transform : Callable[dict, dict]

추가된 버전: 0.6.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

부모 클래스

인스턴스 변수

var topic_label_dict

tomotopy.Dictionary 타입의 토픽 레이블 사전 (읽기전용)

메소드

def add_doc(self, words, labels=[])

현재 모델에 labels를 포함하는 새로운 문헌을 추가하고 추가된 문헌의 인덱스 번호를 반환합니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
labels : Iterable[str]
문헌의 레이블 리스트
def get_topic_words(self, topic_id, top_n=10)

토픽 topic_id에 속하는 상위 top_n개의 단어와 각각의 확률을 반환합니다. 반환 타입은 (단어:str, 확률:float) 튜플의 list형입니다.

파라미터

topic_id : int
전체 레이블의 개수를 l이라고 할 때, [0, l) 범위의 정수는 각각의 레이블에 해당하는 토픽을 가리킵니다. 해당 토픽의 레이블 이름은 LLDAModel.topic_label_dict을 열람하여 확인할 수 있습니다. [l, k) 범위의 정수는 어느 레이블에도 속하지 않는 잠재 토픽을 가리킵니다.
def make_doc(self, words, labels=[])

words 단어를 바탕으로 새로운 문헌인 Document 인스턴스를 반환합니다. 이 인스턴스는 LDAModel.infer() 메소드에 사용될 수 있습니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
labels : Iterable[str]
문헌의 레이블 리스트

상속받은 메소드 및 변수

class MGLDAModel (*args, **kwargs)

이 타입은 Multi Grain Latent Dirichlet Allocation(MG-LDA) 토픽 모델의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Titov, I., & McDonald, R. (2008, April). Modeling online reviews with multi-grain topic models. In Proceedings of the 17th international conference on World Wide Web (pp. 111-120). ACM.

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int

추가된 버전: 0.6.0

단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.

rm_top : int

추가된 버전: 0.2.0

제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.

k_g : int
전역 토픽의 개수를 지정하는 1 ~ 32767 사이의 정수
k_l : int
지역 토픽의 개수를 지정하는 1 ~ 32767 사이의 정수
t : int
문장 윈도우의 크기
alpha_g : float
문헌-전역 토픽 디리클레 분포의 하이퍼 파라미터
alpha_l : float
문헌-지역 토픽 디리클레 분포의 하이퍼 파라미터
alpha_mg : float
전역/지역 선택 디리클레 분포의 하이퍼 파라미터 (전역 부분 계수)
alpha_ml : float
전역/지역 선택 디리클레 분포의 하이퍼 파라미터 (지역 부분 계수)
eta_g : float
전역 토픽-단어 디리클레 분포의 하이퍼 파라미터
eta_l : float
지역 토픽-단어 디리클레 분포의 하이퍼 파라미터
gamma : float
문장-윈도우 디리클레 분포의 하이퍼 파라미터
seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus

추가된 버전: 0.6.0

토픽 모델에 추가될 문헌들의 집합을 지정합니다.

transform : Callable[dict, dict]

추가된 버전: 0.6.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

부모 클래스

인스턴스 변수

var alpha_g

하이퍼 파라미터 alpha_g (읽기전용)

var alpha_l

하이퍼 파라미터 alpha_l (읽기전용)

var alpha_mg

하이퍼 파라미터 alpha_mg (읽기전용)

var alpha_ml

하이퍼 파라미터 alpha_ml (읽기전용)

var eta_g

하이퍼 파라미터 eta_g (읽기전용)

var eta_l

하이퍼 파라미터 eta_l (읽기전용)

var gamma

하이퍼 파라미터 gamma (읽기전용)

var k_g

하이퍼 파라미터 k_g (읽기전용)

var k_l

하이퍼 파라미터 k_l (읽기전용)

var t

하이퍼 파라미터 t (읽기전용)

메소드

def add_doc(self, words, delimiter='.')

현재 모델에 metadata를 포함하는 새로운 문헌을 추가하고 추가된 문헌의 인덱스 번호를 반환합니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
delimiter : str
문장 구분자, words는 이 값을 기준으로 문장 단위로 반할됩니다.
def get_topic_word_dist(self, topic_id)

토픽 topic_id의 단어 분포를 반환합니다. 반환하는 값은 현재 토픽 내 각각의 단어들의 발생확률을 나타내는 len(vocabs)개의 소수로 구성된 list입니다.

파라미터

topic_id : int
[0, k_g) 범위의 정수는 전역 토픽을, [k_g, k_g + k_l) 범위의 정수는 지역 토픽을 가리킵니다.
def get_topic_words(self, topic_id, top_n=10)

토픽 topic_id에 속하는 상위 top_n개의 단어와 각각의 확률을 반환합니다. 반환 타입은 (단어:str, 확률:float) 튜플의 list형입니다.

파라미터

topic_id : int
[0, k_g) 범위의 정수는 전역 토픽을, [k_g, k_g + k_l) 범위의 정수는 지역 토픽을 가리킵니다.
def make_doc(self, words, delimiter='.')

words 단어를 바탕으로 새로운 문헌인 Document 인스턴스를 반환합니다. 이 인스턴스는 LDAModel.infer() 메소드에 사용될 수 있습니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
delimiter : str
문장 구분자, words는 이 값을 기준으로 문장 단위로 반할됩니다.

상속받은 메소드 및 변수

class PAModel (*args, **kwargs)

이 타입은 Pachinko Allocation(PA) 토픽 모델의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Li, W., & McCallum, A. (2006, June). Pachinko allocation: DAG-structured mixture models of topic correlations. In Proceedings of the 23rd international conference on Machine learning (pp. 577-584). ACM.

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int

추가된 버전: 0.6.0

단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.

rm_top : int

추가된 버전: 0.2.0

제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.* k1 : 상위 토픽의 개수, 1 ~ 32767 사이의 정수.

k1 : int
상위 토픽의 개수, 1 ~ 32767 사이의 정수
k2 : int
하위 토픽의 개수, 1 ~ 32767 사이의 정수.
alpha : float
문헌-상위 토픽 디리클레 분포의 하이퍼 파라미터
eta : float
하위 토픽-단어 디리클레 분포의 하이퍼 파라미터
seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus

추가된 버전: 0.6.0

토픽 모델에 추가될 문헌들의 집합을 지정합니다.

transform : Callable[dict, dict]

추가된 버전: 0.6.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

부모 클래스

Subclasses

인스턴스 변수

var alpha

문헌의 상위 토픽 분포에 대한 디리클레 분포 파라미터, [k1] 모양 (읽기전용)

추가된 버전: 0.9.0

var k1

k1, 상위 토픽의 개수 (읽기전용)

var k2

k2, 하위 토픽의 개수 (읽기전용)

var subalpha

상위 토픽의 하위 토픽 분포에 대한 디리클레 분포 파라미터, [k1, k2] 모양 (읽기전용)

추가된 버전: 0.9.0

메소드

def get_count_by_super_topic(self)

각각의 상위 토픽에 할당된 단어의 개수를 list형태로 반환합니다.

추가된 버전: 0.9.0

def get_sub_topic_dist(self, super_topic_id)

상위 토픽 super_topic_id의 하위 토픽 분포를 반환합니다. 반환하는 값은 현재 상위 토픽 내 각각의 하위 토픽들의 발생확률을 나타내는 k2개의 소수로 구성된 list입니다.

파라미터

super_topic_id : int
상위 토픽을 가리키는 [0, k1) 범위의 정수
def get_sub_topics(self, super_topic_id, top_n=10)

추가된 버전: 0.1.4

상위 토픽 super_topic_id에 속하는 상위 top_n개의 하위 토픽과 각각의 확률을 반환합니다. 반환 타입은 (하위토픽:int, 확률:float) 튜플의 list형입니다.

파라미터

super_topic_id : int
상위 토픽을 가리키는 [0, k1) 범위의 정수
def get_topic_word_dist(self, sub_topic_id)

하위 토픽 sub_topic_id의 단어 분포를 반환합니다. 반환하는 값은 현재 하위 토픽 내 각각의 단어들의 발생확률을 나타내는 len(vocabs)개의 소수로 구성된 list입니다.

파라미터

sub_topic_id : int
하위 토픽을 가리키는 [0, k2) 범위의 정수
def get_topic_words(self, sub_topic_id, top_n=10)

하위 토픽 sub_topic_id에 속하는 상위 top_n개의 단어와 각각의 확률을 반환합니다. 반환 타입은 (단어:str, 확률:float) 튜플의 list형입니다.

파라미터

sub_topic_id : int
하위 토픽을 가리키는 [0, k2) 범위의 정수
def infer(self, doc, iter=100, tolerance=-1, workers=0, parallel=0, together=False)

추가된 버전: 0.5.0

새로운 문헌인 doc에 대해 각각의 주제 분포를 추론하여 반환합니다. 반환 타입은 ((doc의 주제 분포, doc의 하위 주제 분포), 로그가능도) 또는 ((doc의 주제 분포, doc의 하위 주제 분포)로 구성된 list, 로그가능도)입니다.

파라미터

doc : Union[Document, Iterable[Document]]
추론에 사용할 Document의 인스턴스이거나 이 인스턴스들의 list. 이 인스턴스들은 LDAModel.make_doc() 메소드를 통해 얻을 수 있습니다.
iter : int
doc의 주제 분포를 추론하기 위해 학습을 반복할 횟수입니다. 이 값이 클 수록 더 정확한 결과를 낼 수 있습니다.
tolerance : float
현재는 사용되지 않음
workers : int
깁스 샘플링을 수행하는 데에 사용할 스레드의 개수입니다. 만약 이 값을 0으로 설정할 경우 시스템 내의 가용한 모든 코어가 사용됩니다.
parallel : Union[int, ParallelScheme]

추가된 버전: 0.5.0

추론에 사용할 병렬화 방법. 기본값은 ParallelScheme.DEFAULT로 이는 모델에 따라 최적의 방법을 tomotopy가 알아서 선택하도록 합니다.

together : bool
이 값이 True인 경우 입력한 doc 문헌들을 한 번에 모델에 넣고 추론을 진행합니다. False인 경우 각각의 문헌들을 별도로 모델에 넣어 추론합니다. 기본값은 False입니다.
transform : Callable[dict, dict]

추가된 버전: 0.10.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체. doc이 Corpus의 인스턴스로 주어진 경우에만 사용 가능합니다.

Returns

result : Union[Tuple[List[float], List[float]], List[Tuple[List[float], List[float]]], Corpus]

doc이 Document로 주어진 경우, result는 문헌의 토픽 분포를 나타내는 List[float]와 하위 토픽 분포를 나타내는 List[float]의 tuple입니다.

doc이 Document의 list로 주어진 경우, result는 문헌의 토픽 분포를 나타내는 List[float]와 하위 토픽 분포를 나타내는 List[float]의 tuple의 list입니다.

doc이 Corpus의 인스턴스로 주어진 경우, result는 추론된 결과 문서들을 담고 있는, Corpus의 새로운 인스턴스입니다. 각 문헌별 토픽 분포를 얻기 위해서는 Document.get_topic_dist(), 하위 토픽 분포를 얻기 위해서는 Document.get_sub_topic_dist()를 사용하면 됩니다.

log_ll : List[float]
각 문헌별 로그 가능도의 리스트

상속받은 메소드 및 변수

class PLDAModel (*args, **kwargs)

이 타입은 Partially Labeled LDA(PLDA) 토픽 모델의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Ramage, D., Manning, C. D., & Dumais, S. (2011, August). Partially labeled topic models for interpretable text mining. In Proceedings of the 17th ACM SIGKDD international conference on Knowledge discovery and data mining (pp. 457-465). ACM.

추가된 버전: 0.4.0

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int

추가된 버전: 0.6.0

단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.

rm_top : int
제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.
latent_topics : int
모든 문헌에 공유되는 잠재 토픽의 개수, 1 ~ 32767 사이의 정수.
topics_per_label : int
레이블별 토픽의 개수, 1 ~ 32767 사이의 정수.
alpha : float
문헌-토픽 디리클레 분포의 하이퍼 파라미터
eta : float
토픽-단어 디리클레 분포의 하이퍼 파라미터
seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus

추가된 버전: 0.6.0

토픽 모델에 추가될 문헌들의 집합을 지정합니다.

transform : Callable[dict, dict]

추가된 버전: 0.6.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

부모 클래스

인스턴스 변수

var latent_topics

잠재 토픽의 개수 (읽기전용)

var topic_label_dict

tomotopy.Dictionary 타입의 토픽 레이블 사전 (읽기전용)

var topics_per_label

레이블별 토픽의 개수 (읽기전용)

메소드

def add_doc(self, words, labels=[])

현재 모델에 labels를 포함하는 새로운 문헌을 추가하고 추가된 문헌의 인덱스 번호를 반환합니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
labels : Iterable[str]
문헌의 레이블 리스트
def get_topic_words(self, topic_id, top_n=10)

토픽 topic_id에 속하는 상위 top_n개의 단어와 각각의 확률을 반환합니다. 반환 타입은 (단어:str, 확률:float) 튜플의 list형입니다.

파라미터

topic_id : int
전체 레이블의 개수를 l이라고 할 때, [0, l * topics_per_label) 범위의 정수는 각각의 레이블에 해당하는 토픽을 가리킵니다. 해당 토픽의 레이블 이름은 PLDAModel.topic_label_dict을 열람하여 확인할 수 있습니다. [l * topics_per_label, l * topics_per_label + latent_topics) 범위의 정수는 어느 레이블에도 속하지 않는 잠재 토픽을 가리킵니다.
def make_doc(self, words, labels=[])

words 단어를 바탕으로 새로운 문헌인 Document 인스턴스를 반환합니다. 이 인스턴스는 LDAModel.infer() 메소드에 사용될 수 있습니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
labels : Iterable[str]
문헌의 레이블 리스트

상속받은 메소드 및 변수

class ParallelScheme (value, names=None, *, module=None, qualname=None, type=None, start=1)

병렬화 기법을 선택하는 데에 사용되는 열거형입니다. 총 3가지 기법을 사용할 수 있으나, 모든 모델이 아래의 기법을 전부 지원하지는 않습니다.

Expand source code 
class ParallelScheme(IntEnum):
    """
    This enumeration is for Parallelizing Scheme:
    There are three options for parallelizing and the basic one is DEFAULT. Not all models supports all options. 
    """

    DEFAULT = 0
    """tomotopy chooses the best available parallelism scheme for your model"""

    NONE = 1
    """ 
    Turn off multi-threading for Gibbs sampling at training or inference. Operations other than Gibbs sampling may use multithreading.
    """

    COPY_MERGE = 2
    """
    Use Copy and Merge algorithm from AD-LDA. It consumes RAM in proportion to the number of workers. 
    This has advantages when you have a small number of workers and a small number of topics and vocabulary sizes in the model.
    Prior to version 0.5, all models used this algorithm by default. 
    
    > * Newman, D., Asuncion, A., Smyth, P., & Welling, M. (2009). Distributed algorithms for topic models. Journal of Machine Learning Research, 10(Aug), 1801-1828.
    """

    PARTITION = 3
    """
    Use Partitioning algorithm from PCGS. It consumes only twice as much RAM as a single-threaded algorithm, regardless of the number of workers.
    This has advantages when you have a large number of workers or a large number of topics and vocabulary sizes in the model.
    
    > * Yan, F., Xu, N., & Qi, Y. (2009). Parallel inference for latent dirichlet allocation on graphics processing units. In Advances in neural information processing systems (pp. 2134-2142).
    """

부모 클래스

  • enum.IntEnum
  • builtins.int
  • enum.Enum

Class variables

var COPY_MERGE

AD-LDA에서 제안된 복사 후 합치기 알고리즘을 사용합니다. 이는 작업자 수에 비례해 메모리를 소모합니다. 작업자 수가 적거나, 토픽 개수 혹은 어휘 집합의 크기가 작을 때 유리합니다. 0.5버전 이전까지는 모든 모델은 이 알고리즘을 기본으로 사용했습니다.

  • Newman, D., Asuncion, A., Smyth, P., & Welling, M. (2009). Distributed algorithms for topic models. Journal of Machine Learning Research, 10(Aug), 1801-1828.
var DEFAULT

tomotopy가 모델에 따라 적합한 병럴화 기법을 선택하도록 합니다. 이 값이 기본값입니다.

var NONE

깁스 샘플링에 병렬화 기법을 사용하지 않습니다. 깁스 샘플링을 제외한 다른 연산들은 여전히 병렬로 처리될 수 있습니다.

var PARTITION

PCGS에서 제안된 분할 샘플링 알고리즘을 사용합니다. 작업자 수에 관계없이 단일 스레드 알고리즘에 비해 2배의 메모리만 소모합니다. 작업자 수가 많거나, 토픽 개수 혹은 어휘 집합의 크기가 클 때 유리합니다.

  • Yan, F., Xu, N., & Qi, Y. (2009). Parallel inference for latent dirichlet allocation on graphics processing units. In Advances in neural information processing systems (pp. 2134-2142).
class SLDAModel (*args, **kwargs)

이 타입은 supervised Latent Dirichlet Allocation(sLDA) 토픽 모델의 구현체를 제공합니다. 주요 알고리즘은 다음 논문에 기초하고 있습니다:

  • Mcauliffe, J. D., & Blei, D. M. (2008). Supervised topic models. In Advances in neural information processing systems (pp. 121-128).
  • Python version implementation using Gibbs sampling : https://github.com/Savvysherpa/slda

추가된 버전: 0.2.0

파라미터

tw : Union[int, TermWeight]
용어 가중치 기법을 나타내는 TermWeight의 열거값. 기본값은 TermWeight.ONE 입니다.
min_cf : int
단어의 최소 장서 빈도. 전체 문헌 내의 출현 빈도가 min_cf보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.
min_df : int

추가된 버전: 0.6.0

단어의 최소 문헌 빈도. 출현한 문헌 숫자가 min_df보다 작은 단어들은 모델에서 제외시킵니다. 기본값은 0으로, 이 경우 어떤 단어도 제외되지 않습니다.

rm_top : int
제거될 최상위 빈도 단어의 개수. 만약 너무 흔한 단어가 토픽 모델 상위 결과에 등장해 이를 제거하고 싶은 경우, 이 값을 1 이상의 수로 설정하십시오. 기본값은 0으로, 이 경우 최상위 빈도 단어는 전혀 제거되지 않습니다.
k : int
토픽의 개수, 1 ~ 32767 사이의 정수
vars : Iterable[str]

응답변수의 종류를 지정합니다. vars의 길이는 모형이 사용하는 응답 변수의 개수를 결정하며, vars의 요소는 각 응답 변수의 종류를 결정합니다. 사용가능한 종류는 다음과 같습니다:

  • 'l': 선형 변수 (아무 실수 값이나 가능)
  • 'b': 이진 변수 (0 혹은 1만 가능)
alpha : float
문헌-토픽 디리클레 분포의 하이퍼 파라미터
eta : float
토픽-단어 디리클레 분포의 하이퍼 파라미터
mu : Union[float, Iterable[float]]
회귀 계수의 평균값, 기본값은 0
nu_sq : Union[float, Iterable[float]]
회귀 계수의 분산값, 기본값은 1
glm_param : Union[float, Iterable[float]]
일반화 선형 모형에서 사용될 파라미터, 기본값은 1
seed : int
난수의 시드값. 기본값은 C++의 std::random_device{}이 생성하는 임의의 정수입니다. 이 값을 고정하더라도 train시 workers를 2 이상으로 두면, 멀티 스레딩 과정에서 발생하는 우연성 때문에 실행시마다 결과가 달라질 수 있습니다.
corpus : Corpus

추가된 버전: 0.6.0

토픽 모델에 추가될 문헌들의 집합을 지정합니다.

transform : Callable[dict, dict]

추가된 버전: 0.6.0

특정한 토픽 모델에 맞춰 임의 키워드 인자를 조작하기 위한 호출가능한 객체

부모 클래스

인스턴스 변수

var f

응답 변수의 개수 (읽기전용)

메소드

def add_doc(self, words, y=[])

현재 모델에 응답 변수 y를 포함하는 새로운 문헌을 추가하고 추가된 문헌의 인덱스 번호를 반환합니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
y : Iterable[float]

문헌의 응답 변수로 쓰일 float의 list. y의 길이는 모델의 응답 변수의 개수인 SLDAModel.f와 일치해야 합니다.

추가된 버전: 0.5.1

만약 결측값이 있을 경우, 해당 항목을 NaN으로 설정할 수 있습니다. 이 경우 NaN값을 가진 문헌은 토픽을 모델링하는데에는 포함되지만, 응답 변수 회귀에서는 제외됩니다.

def estimate(self, doc)

doc의 추정된 응답 변수를 반환합니다. 만약 doc이 SLDAModel.make_doc()에 의해 생성된 인스턴스라면, 먼저 LDAModel.infer()를 통해 토픽 추론을 실시한 다음 이 메소드를 사용해야 합니다.

파라미터

doc : Document
응답 변수를 추정하려하는 문헌의 인스턴스 혹은 인스턴스들의 list
def get_regression_coef(self, var_id=None)

응답 변수 var_id의 회귀 계수를 반환합니다.

파라미터

var_id : int

응답 변수를 지정하는 [0, f) 범위의 정수

생략시, [f, k] 모양의 전체 회귀 계수가 반환됩니다.

def get_var_type(self, var_id)

응답 변수 var_id의 종류를 반환합니다. 'l'은 선형 변수, 'b'는 이진 변수를 뜻합니다.

def make_doc(self, words, y=[])

words 단어를 바탕으로 새로운 문헌인 Document 인스턴스를 반환합니다. 이 인스턴스는 LDAModel.infer() 메소드에 사용될 수 있습니다.

파라미터

words : Iterable[str]
문헌의 각 단어를 나열하는 str 타입의 iterable
y : Iterable[float]
문헌의 응답 변수로 쓰일 float의 list. y의 길이는 모델의 응답 변수의 개수인 SLDAModel.f와 꼭 일치할 필요는 없습니다. y의 길이가 SLDAModel.f보다 짧을 경우, 모자란 값들은 자동으로 NaN으로 채워집니다.

상속받은 메소드 및 변수

class TermWeight (value, names=None, *, module=None, qualname=None, type=None, start=1)

용어 가중치 기법을 선택하는 데에 사용되는 열거형입니다. 여기에 제시된 용어 가중치 기법들은 다음 논문을 바탕으로 하였습니다:

  • Wilson, A. T., & Chew, P. A. (2010, June). Term weighting schemes for latent dirichlet allocation. In human language technologies: The 2010 annual conference of the North American Chapter of the Association for Computational Linguistics (pp. 465-473). Association for Computational Linguistics.

총 3가지 가중치 기법을 사용할 수 있으며 기본값은 ONE입니다. 기본값뿐만 아니라 다른 모든 기법들도 tomotopy의 모든 토픽 모델에 사용할 수 있습니다.

Expand source code 
class TermWeight(IntEnum):
    """
    This enumeration is for Term Weighting Scheme and it is based on following paper:
    
    > * Wilson, A. T., & Chew, P. A. (2010, June). Term weighting schemes for latent dirichlet allocation. In human language technologies: The 2010 annual conference of the North American Chapter of the Association for Computational Linguistics (pp. 465-473). Association for Computational Linguistics.
    
    There are three options for term weighting and the basic one is ONE. The others also can be applied for all topic models in `tomotopy`. 
    """

    ONE = 0
    """ Consider every term equal (default)"""

    IDF = 1
    """ 
    Use Inverse Document Frequency term weighting.
    
    Thus, a term occurring at almost every document has very low weighting
    and a term occurring at a few document has high weighting. 
    """

    PMI = 2
    """
    Use Pointwise Mutual Information term weighting.
    """

부모 클래스

  • enum.IntEnum
  • builtins.int
  • enum.Enum

Class variables

var IDF

역문헌빈도(IDF)를 가중치로 사용합니다.

따라서 모든 문헌에 거의 골고루 등장하는 용어의 경우 낮은 가중치를 가지게 되며, 소수의 특정 문헌에만 집중적으로 등장하는 용어의 경우 높은 가중치를 가지게 됩니다.

var ONE

모든 용어를 동일하게 간주합니다. (기본값)

var PMI

점별 상호정보량(PMI)을 가중치로 사용합니다.