⚠ ARCHIVED: please use the up-to-date fork at https://github.com/sentspace/sentspace
sentspace
gives users a better understanding of the distribution of linguistic stimuli,
specifically, sentences, in comparison with large corpora. sentspace
achieves
this using a collection of psycholinguistic datasets and linguistic features.
Imagine you have collected a set of sentences for use in a language experiment, or generated
sentences using an artificial neural network language model. How does your set of sentences compare to
naturally occurring sentences? What are the dimensions along which your sentences deviate from
normal?
sentspace
provides you with numerical estimates of these values, as well as
allows you to visualize the high-dimensional space in a web-based application.
Online interface: http://sentspace.github.io/hosted
Screencast video demo: https://youtu.be/a66_nvcCakw
CLI usage demo:
Documentation is generated using pdoc3
and available online (click on the title above).
Example: get lexical and embedding features for stimuli from a csv containing columns for 'sentence' and 'index'.
$ python3 -m sentspace -h
usage:
positional arguments:
input_file path to input file or a single sentence. If supplying a file, it must be .csv .txt or .xlsx, e.g., example/example.csv
optional arguments:
-h, --help show this help message and exit
-sw STOP_WORDS, --stop_words STOP_WORDS
path to delimited file of words to filter out from analysis, e.g., example/stopwords.txt
-b BENCHMARK, --benchmark BENCHMARK
path to csv file of benchmark corpora For example benchmarks/lexical/UD_corpora_lex_features_sents_all.csv
-p PARALLELIZE, --parallelize PARALLELIZE
use multiple threads to compute features? disable using `-p False` in case issues arise.
-o OUTPUT_DIR, --output_dir OUTPUT_DIR
path to output directory where results may be stored
-of {pkl,tsv}, --output_format {pkl,tsv}
-lex LEXICAL, --lexical LEXICAL
compute lexical features? [False]
-syn SYNTAX, --syntax SYNTAX
compute syntactic features? [False]
-emb EMBEDDING, --embedding EMBEDDING
compute high-dimensional sentence representations? [False]
-sem SEMANTIC, --semantic SEMANTIC
compute semantic (multi-word) features? [False]
--emb_data_dir EMB_DATA_DIR
path to output directory where results may be stored
Example: get embedding features in a script
import sentspace
s = sentspace.Sentence('The person purchased two mugs at the price of one.')
emb_features = sentspace.embedding.get_features(s)
Example: parallelize getting features for multiple sentences using multithreading
import sentspace
sentences = [
'Hello, how may I help you today?',
'The person purchased three mugs at the price of five!',
"She's leaving home.",
'This is an example sentence we want features of.'
]
# construct sentspace.Sentence objects from strings
sentences = [*map(sentspace.Sentence, sentences)]
# make use of parallel processing to get lexical features for the sentences
lex_features = sentspace.utils.parallelize(sentspace.lexical.get_features, sentences,
wrap_tqdm=True, desc='Computing lexical features')
1. Install using Conda and Poetry
Prerequisites: conda
- Use your own or create new conda environment:
conda create -n sentspace-env python=3.8
(if using your own, we will assume your environment is calledsentspace-env
)- Activate it:
conda activate sentspace-env
- Activate it:
- Install poetry:
curl -sSL https://github.com/raw/python-poetry/poetry/master/get-poetry.py | python -
- Install
polyglot
dependencies using conda:conda install -c conda-forge pyicu morfessor icu -y
- Install remaining packages using poetry:
poetry install
If after the above steps the installation gives you trouble, you may need to refer to: polyglot
install instructions, which lists how to obtain ICU, a dependency for polyglot.
To use sentspace
after installation, simply make sure to have the conda environment active and all packages up to date using poetry install
Requirements: singularity
or docker
.
Singularity:
singularity shell docker://aloxatel/sentspace:latest
Alternatively, from the root of the repo, bash singularity-shell.sh
). this step can take a while when you run it for the first time as it needs to download the image from docker hub and convert it to singularity image format (.sif
). however, each subsequent run will execute rapidly.
Docker: use corresponding commands for Docker.
now you are inside the container and ready to run sentspace
!
On Debian/Ubuntu-like systems, follow the steps below. On other systems (RHEL, etc.), substitute commands and package names with appropriate alternates.
# optional (but recommended):
# create a virtual environment using your favorite method (venv, conda, ...)
# before any of the following
# install basic packages using apt (you likely already have these)
sudo apt update
sudo apt install python3.8 python3.8-dev python3-pip
sudo apt install python2.7 python2.7-dev
sudo apt install build-essential git
# install ICU
DEBIAN_FRONTEND="noninteractive" TZ="America/New_York" sudo apt install python3-icu
# install ZS package separately (pypi install fails)
python3.8 -m pip install -U pip cython
git clone https://github.com/njsmith/zs
cd zs && git checkout v0.10.0 && pip install .
# install rest of the requirements using pip
cd .. # make sure you're in the sentspace/ directory
pip install -r ./requirements.txt
polyglot download morph2.en
In general, each submodule implements a major class of features. You can run each module on its own by specifying its flag and 0
or 1
with the module call:
python -m sentspace -lex {0,1} -syn {0,1} -emb {0,1} <input_file_path>
Obtain lexical (word-level) features that are not dependendent on the sentence context. These features are returned on a word-by-word level and also averaged at the sentence level to provide each sentence a corresponding value.
- typical age of acquisition
- n-gram surprisal
n={1,2,3,4}
- etc. (comprehensive list will be updated)
Description pending
Obtain high dimensional representations of sentences using word-embedding and contextualized encoder models.
glove
- Huggingface model hub (
gpt2-xl
,bert-base-uncased
)
Multi-word features computed using partial or full sentence context.
- PMI (pointwise mutual information)
- Language model-based perplexity/surprisal Not Implemented yet
Any contributions you make are greatly appreciated, and no contribution is too small to contribute.
- Fork the project on Github (how to fork)
- Create your feature/patch branch (
git checkout -b feature/AmazingFeature
) - Commit your changes (
git commit -m 'Add some AmazingFeature'
) - Push the branch (
git push origin feature/AmazingFeature
) - Open a Pull Request (PR) and we will take a look asap!
gretatu % mit ^ edu
asathe % mit ^ edu
(C) 2020-2022 EvLab, MIT BCS