SynSemClass (formerly CzEngClass)
Overview
The SynSemClass Search Tool is a web-based interface designed for querying the SynSemClass ontology, an event-type ontology available in multiple languages. It includes several search options and criteria for building complex queries. The search results are presented in a clear and user-friendly interactive format. Additionally, the tool offers an API, allowing users to retrieve either the search results identical to the UI, or the raw server response for further processing.
How To Use
-
Search Criteria:
- Lemma: Enter a class member lemma, e.g., "bring".
- Sense ID: Enter the sense ID (idref), e.g., “EngVallex-ID-ev-w122f2”.
- Class ID: Inputting a Class ID will display all associated class members.
Regular expressions can be used in any input fields (lemma, sense ID, class ID) to match strings or phrasal verbs. For example, “put.*” will show class members starting with “put”.
- Filters: Select languages: English, Czech, or German. Multiple languages can be selected. If none are selected, all three are searched.
-
Roles: Define the search by class member roles. Choose a role from a dropdown list of possible options (type the first letters for quick search). More advanced search of several role combinations is performed using Conjunctive Normal Form (CNF). The user can interact with the brackets (CNF clauses) and place the roles between them, as well as adding more clauses. The final roles query is displayed on the bottom. It is always in the form of CNF, for example, (Role1 OR Role2) AND (Role3).
- Optionally, the user can use a checkmark "Restrict search only to these roles", if they want to find only results containing those roles and no others.
- Cmnote: search the class members with additional notes, e.g., "idiom.*".
- Restrict: search the class member with additional "restrict" field notes, e.g., "to come across as".
- Diacritics-Sensitive Search for lemma: check to enable diacritics-sensitive search for lemma field, otherwise, search diacritics-insensitive by default.
-
Understanding the Results:
- The result shows the number of class members and the number of unique classes. Then, also the number of class members and unique classes per specific language is displayed.
-
The data representation is class-centric. Class members matching the criteria are grouped into their common classes with essential information condensed on top-level representation
- the class ID is displayed on top. Upon mouse hover, the entry is clickable, with the link pointing to the class entry in SynSemClass5.0 web. Upon hovering on class ID, the copy icon pops up on the right for a quick copy tool of the ID.
- roles are highlighted in green
- If the result contains class members from different languages, each language class name is displayed on top and the respective class members are grouped within.
- The initial results are collapsed and condensed for more efficient representation, only top 2 class members with their respective sense IDs (hover for a quick copy as well) are displayed within a given class. Clicking on “Show more” button expands the full list of class members with their sense ID (hover for a quick copy available), their class member ID (hover for a quick copy available) and the mapping. Finally, expanding each individual class member with the right arrow shows the full JSON content of the given class member. Class member ID, sense ID (idref) and lemma are clickable links leading to the class member’s entry in the SynSemClass5.0 web or the valency lexicons (PDT-Vallex, EngVallex, …).
- "Show all class members in the given class" button allows to quickly show current class with class members from all languages; same functionality as copying the class ID and searching all languages with the given class ID.
- Clicking on roles' list can copy the given roles' combination into the query without the need to manually construct it.
- "Download JSON" button on the top right corner of the results allows downloading the complete search results in a file in .json format.
- Large results are paginated. Use page controls on top and bottom to navigate between pages.
API Guide
Endpoint: /api/search
-
Method: GET
-
Parameters:
- lemma: string (e.g., “/api/search?lemma=bring”)
- idref: string (e.g., “/api/search?idref=EngVallex.*”)
- classID: string (e.g., “/api/search?classID=vec.*17”)
- cmnote: string (e.g., "/api/search?cmnote=idiom.*")
- restrict: string (e.g., "api/search?restrict=to come across as")
- filters: language codes, eng, ces, or deu (e.g., “/api/search?filters=ces,deu”).
-
roles_cnf: a JSON string representing a non-empty array of arrays, where the outer brackets represent the whole roles query and inner arrays represent clauses, for instance, “api/search?roles_cnf=[["Agent"], ["Recipient"]]”, represents ((Agent) AND (Recipient)). Another example: “api/search?roles_cnf=[["Agent", "Abuser"]]”, which stands for ((Agent OR Abuser)). Be careful about the roles’ names, they have to be the same as the options in the dropdown-list in the UI. Additionally, you can retrieve a full list of these labels by accessing API endpoint
/api/shortlabels. -
version: string containing the version of the data; by default, the latest version is used ("synsemclass5.0"); if you need to search within the older 4.0 version, include "version=synsemclass4.0" in the query.
-
restrictRolesSearch: string equal to "true" (e.g., "/api/search/?roles_cnf=[["Agent"]]&restrictRolesSearch=true)
-
diacriticsSensitive: string equal to "true" (e.g., "/api/search/?roles_cnf=[["Agent"]]&diacriticsSensitive=true)
Example: "/api/search?lemma=put.*&filters=eng&roles_cnf=[["Agent"]]"
-
Response: Returns a JSON object:
- pages: Array of search results.
- uniqueCommonClassCount: Count of unique classes.
- uniqueCommonIdCount: Count of unique IDs.
- langCounts: Breakdown by language.
- totalClassMembers: Count of class members.
Browser Rendered Results
This uses the same parameters as the API endpoint, but displays a visual result page, identical to using the UI.
Example: "/?lemma=put.*&filters=eng&roles_cnf=[["Agent"]]"