mordecai

Teks lengkap geoparsing sebagai perpustakaan Python. Ekstrak nama tempat dari sepotong teks berbahasa Inggris, selesaikan ke tempat yang benar, dan kembalikan koordinat mereka dan informasi geografis terstruktur.

Mordecai siap untuk ditingkatkan! Harap ambil survei pengguna di sini untuk membantu membentuk seperti apa V3 nantinya.

Contoh penggunaan

 >>> from mordecai import Geoparser
>>> geo = Geoparser()
>>> geo.geoparse("I traveled from Oxford to Ottawa.")

[{'country_conf': 0.96474487,
  'country_predicted': 'GBR',
  'geo': {'admin1': 'England',
   'country_code3': 'GBR',
   'feature_class': 'P',
   'feature_code': 'PPLA2',
   'geonameid': '2640729',
   'lat': '51.75222',
   'lon': '-1.25596',
   'place_name': 'Oxford'},
  'spans': [{'end': 22, 'start': 16}],
  'word': 'Oxford'},
 {'country_conf': 0.83302397,
  'country_predicted': 'CAN',
  'geo': {'admin1': 'Ontario',
   'country_code3': 'CAN',
   'feature_class': 'P',
   'feature_code': 'PPLC',
   'geonameid': '6094817',
   'lat': '45.41117',
   'lon': '-75.69812',
   'place_name': 'Ottawa'},
  'spans': [{'end': 32, 'start': 26}],
  'word': 'Ottawa'}]

Mordecai membutuhkan layanan elasticsearch yang sedang berjalan dengan geonames di dalamnya. Lihat "Instalasi" di bawah ini untuk instruksi.

Instalasi dan Persyaratan

1. Mordecai ada di PYPI dan dapat dipasang untuk Python 3 dengan Pip:

 pip install mordecai

Catatan : Sangat disarankan agar Anda menjalankan Mordecai di lingkungan virtual. Perpustakaan yang bergantung pada Mordecai tidak selalu merupakan versi terbaru dan menggunakan lingkungan virtual mencegah perpustakaan diturunkan atau mengalami masalah lain:

 python -m venv mordecai-env
source mordecai-env/bin/activate
pip install mordecai

2. Anda kemudian harus mengunduh model NLP Spacy yang diperlukan:

 python -m spacy download en_core_web_lg

3. Untuk bekerja, Mordecai membutuhkan akses ke gazetteer geonames yang berjalan di Elasticsearch. Cara termudah untuk mengaturnya adalah dengan menjalankan perintah berikut (Anda harus memasang Docker terlebih dahulu).

 docker pull elasticsearch:5.5.2
wget https://andrewhalterman.com/files/geonames_index.tar.gz --output-file=wget_log.txt
tar -xzf geonames_index.tar.gz
docker run -d -p 127.0.0.1:9200:9200 -v $(pwd)/geonames_index/:/usr/share/elasticsearch/data elasticsearch:5.5.2

Lihat ES-geonames untuk kode yang digunakan untuk menghasilkan indeks ini.

Untuk memperbarui indeks, cukup matikan wadah lama, turunkan kembali indeks dari S3, dan restart wadah dengan indeks baru.

Mengutip

Jika Anda menggunakan perangkat lunak ini dalam pekerjaan akademik, silakan kutip sebagai

 @article{halterman2017mordecai,
  title={Mordecai: Full Text Geoparsing and Event Geocoding},
  author={Halterman, Andrew},
  journal={The Journal of Open Source Software},
  volume={2},
  number={9},
  year={2017},
  doi={10.21105/joss.00091}
}

Bagaimana cara kerjanya?

Mordecai mengambil teks yang tidak terstruktur dan mengembalikan informasi geografis terstruktur yang diekstraksi darinya.

• Ini menggunakan pengenalan entitas Spacy yang disebutkan untuk mengekstrak nama tempat dari teks.

• Ini menggunakan gazetteer geonames dalam indeks Elasticsearch (dengan beberapa logika khusus) untuk menemukan koordinat potensial dari nama tempat yang diekstraksi.

• Ini menggunakan jaringan saraf yang diimplementasikan di KERAS dan dilatih pada data berbahasa Inggris beranotasi baru yang dilabeli dengan ajaib untuk menyimpulkan negara yang benar dan memperbaiki entri gazetteer untuk setiap nama tempat.

Data pelatihan untuk kedua model tersebut termasuk teks yang dilindungi hak cipta sehingga tidak dapat dibagikan secara bebas. Menerapkan Mordecai ke teks bahasa non-Inggris akan membutuhkan data pelabelan dalam bahasa target dan pelatihan ulang.

API dan Konfigurasi

Saat membuat modul Geoparser() , opsi berikut dapat diubah:

• es_hosts : Daftar host tempat Layanan Geonames Elasticsearch sedang berjalan. Default ke ['localhost'] , di situlah berjalan jika Anda menggunakan pengaturan Docker default yang dijelaskan di atas.
• es_port : Port apa yang dijalankan oleh Layanan Geonames Elasticsearch. Default ke 9200 , di situlah pengaturan Docker memilikinya
• es_ssl : Apakah Elasticsearch memerlukan koneksi SSL. Default ke False .
• es_auth : Parameter auth http opsional untuk digunakan dengan ES. Jika disediakan, itu harus menjadi dua-tuple dari (user, password) .
• country_confidence : Tetapkan kepercayaan model negara di bawah ini yang tidak akan dikembalikan geolokasi. Jika sangat rendah, modelnya mungkin salah dan akan mengembalikan hasil yang aneh. Default ke 0.6 .
• verbose : Kembalikan semua fitur yang digunakan dalam model pengambilan negara? Default ke False .
• threads : Apakah akan menggunakan utas untuk membuat kueri paralel ke database Elasticsearch. Default ke True , yang memberikan speedup ~ 6x.

geoparse adalah titik akhir utama dan satu -satunya yang dibutuhkan sebagian besar pengguna. Metode lain, sebagian besar internal, mungkin berguna dalam beberapa kasus:

• lookup_city mengambil nama kota, negara, dan (secara opsional) ADM1/negara bagian/gubernur dan melakukan pencarian berbasis aturan untuk kota.
• infer_country mengambil dokumen dan upaya untuk menyimpulkan negara yang paling mungkin untuk masing -masing.
• query_geonames dan query_geonames_country dapat digunakan untuk melakukan pencarian geonames di elasticsearch
• Metode dengan awalan _feature adalah metode internal untuk menghitung fitur pengambilan negara dari teks.

batch_geoparse mengambil daftar dokumen dan menggunakan metode spacy nlp.pipe untuk memprosesnya lebih efisien dalam langkah NLP.

Pengguna lanjutan pada mesin besar dapat meningkatkan parameter lru_cache dari 250 menjadi 1000. Ini akan menggunakan lebih banyak memori tetapi akan meningkatkan kecepatan parsing.

Tes

Mordecai termasuk tes unit. Untuk menjalankan tes, cd ke direktori mordecai dan menjalankan:

 pytest

Tes memerlukan akses ke layanan elastis/geonames yang berjalan untuk menyelesaikannya. Tes saat ini gagal di Travisci dengan Segfault yang tidak dapat dijelaskan tetapi berjalan dengan baik secara lokal. Mordecai hanya diuji dengan Python 3.

Ucapan Terima Kasih

Verion sebelumnya dari perangkat lunak ini disumbangkan ke Open Event Data Alliance oleh Caerus Associates. Lihat Rilis atau Cabang Legacy-Docker untuk 2015-2016 dan versi produksi Mordecai 2016-2017.

Pekerjaan ini sebagian didanai oleh program XDATA DARPA, Laboratorium Penelitian Angkatan Darat AS dan Kantor Penelitian Angkatan Darat AS melalui Inisiatif Minerva di bawah nomor hibah W911NF-13-0332, dan National Science Foundation di bawah nomor penghargaan SBE-SMA-1539302. Setiap pendapat, temuan, dan kesimpulan atau rekomendasi yang diungkapkan dalam materi ini adalah pendapat penulis dan tidak mencerminkan pandangan DARPA, ARO, Minerva, NSF, atau pemerintah AS.

Berkontribusi

Kontribusi melalui permintaan pull dipersilakan. Pastikan perubahan lulus tes unit. Bug dan masalah apa pun dapat dilaporkan di halaman masalah repo.