0
# Entity Recognition
1

2
Automatic detection, extraction, and analysis of named entities including people, places, dates, values, and organizations. The entity classes extend the Noun class with specialized parsing and analysis methods.
3

4
## Capabilities
5

6
### Person Class
7

8
Person entity with name parsing and demographic analysis.
9

10
```javascript { .api }
11
/**
12
 * Person class extending Noun for person name analysis
13
 */
14
class Person extends Noun {
15
  /** Person's title/honorific (Dr., Mr., Ms., etc.) */
16
  honourific: string;
17
  /** First name component */
18
  firstName: string;
19
  /** Middle name component */
20
  middleName: string;
21
  /** Last name component */
22
  lastName: string;
23
  
24
  /**
25
   * Parse name components from person text
26
   */
27
  parse(): void;
28
  
29
  /**
30
   * Detect person's gender from name
31
   * @returns {string} Gender: 'Male', 'Female', or undefined
32
   */
33
  gender(): string;
34
  
35
  /**
36
   * Get appropriate pronoun for person
37
   * @returns {string} Pronoun: 'he', 'she', or 'they'
38
   */
39
  pronoun(): string;
40
  
41
  /**
42
   * Check if term is a pronoun
43
   * @returns {boolean} True if pronoun
44
   */
45
  isPronoun(): boolean;
46
}
47
```
48

49
**Usage Examples:**
50

51
```javascript
52
const nlp = require('nlp_compromise');
53

54
// Basic person parsing
55
const person = nlp.person('Dr. Jane Smith');
56
console.log(person.honourific);  // 'Dr.'
57
console.log(person.firstName);   // 'Jane'
58
console.log(person.lastName);    // 'Smith'
59
console.log(person.gender());    // 'Female'
60
console.log(person.pronoun());   // 'she'
61

62
// Full name parsing
63
const fullName = nlp.person('John Michael Johnson Jr.');
64
console.log(fullName.firstName);   // 'John'
65
console.log(fullName.middleName);  // 'Michael'
66
console.log(fullName.lastName);    // 'Johnson Jr.'
67

68
// Pronoun detection
69
const pronoun = nlp.person('he');
70
console.log(pronoun.isPronoun());  // true
71
console.log(pronoun.gender());     // 'Male'
72
```
73

74
### Value Class
75

76
Numeric values and measurements with unit parsing and conversion awareness.
77

78
```javascript { .api }
79
/**
80
 * Value class extending Noun for numeric value analysis
81
 */
82
class Value extends Noun {
83
  /** Numeric value extracted from text */
84
  number: number;
85
  /** Unit abbreviation (kg, ft, $, etc.) */
86
  unit: string;
87
  /** Full unit name (kilogram, foot, dollar, etc.) */
88
  unit_name: string;
89
  /** Type of measurement */
90
  measurement: string;
91
  /** What is being measured (optional context) */
92
  of_what: string;
93
  
94
  /**
95
   * Parse numeric value and unit information
96
   */
97
  parse(): void;
98
  
99
  /**
100
   * Check if string contains a number
101
   * @param {string} str - String to check
102
   * @returns {boolean} True if contains number
103
   */
104
  is_number(str): boolean;
105
  
106
  /**
107
   * Check if number is ordinal (1st, 2nd, 3rd, etc.)
108
   * @returns {boolean} True if ordinal number
109
   */
110
  is_ordinal(): boolean;
111
  
112
  /**
113
   * Convert number to ordinal form
114
   * @returns {string} Ordinal form (1st, 2nd, 3rd, etc.)
115
   */
116
  to_ordinal(): string;
117
  
118
  /**
119
   * Check if string is a unit
120
   * @returns {boolean} True if recognized unit
121
   */
122
  is_unit(): boolean;
123
  
124
  /**
125
   * Get textual representation of the value
126
   * @returns {string} Text form of the number
127
   */
128
  textual(): string;
129
}
130
```
131

132
**Usage Examples:**
133

134
```javascript
135
// Currency values
136
const money = nlp.value('$500');
137
console.log(money.number);       // 500
138
console.log(money.unit);         // 'dollar'
139
console.log(money.measurement);  // 'Money'
140

141
// Written numbers
142
const written = nlp.value('five hundred dollars');
143
console.log(written.number);     // 500
144
console.log(written.unit_name);  // 'dollar'
145
console.log(written.textual());  // 'five hundred'
146

147
// Measurements
148
const distance = nlp.value('25 kilometers');
149
console.log(distance.number);       // 25
150
console.log(distance.unit);         // 'km'
151
console.log(distance.unit_name);    // 'kilometer'
152
console.log(distance.measurement);  // 'Distance'
153

154
// Ordinal numbers
155
const ordinal = nlp.value('3rd');
156
console.log(ordinal.is_ordinal());  // true
157
console.log(ordinal.number);        // 3
158

159
// Temperature
160
const temp = nlp.value('98.6 degrees fahrenheit');
161
console.log(temp.number);        // 98.6
162
console.log(temp.measurement);   // 'Temperature'
163

164
// Utility methods
165
const ordinal = nlp.value('5');
166
console.log(ordinal.to_ordinal());  // '5th'
167
console.log(ordinal.is_number('42')); // true (utility method with parameter)
168
const unit = nlp.value('5 kg');
169
console.log(unit.is_unit());   // true
170
```
171

172
### Date Class
173

174
Date entity with temporal parsing and date object conversion.
175

176
```javascript { .api }
177
/**
178
 * Date class extending Noun for date analysis
179
 */
180
class Date extends Noun {
181
  /** Parsed date components */
182
  data: {
183
    day: number | null;
184
    month: number | null;
185
    year: number | null;
186
  };
187
  
188
  /**
189
   * Convert to JavaScript Date object
190
   * @returns {Date} JavaScript Date object
191
   */
192
  date(): Date;
193
  
194
  /**
195
   * Validate if parsed as valid date
196
   * @returns {boolean} True if valid date
197
   */
198
  is_date(): boolean;
199
}
200
```
201

202
**Usage Examples:**
203

204
```javascript
205
// Date parsing
206
const dateEntity = nlp.date('March 15, 2024');
207
console.log(dateEntity.data.day);    // 15
208
console.log(dateEntity.data.month);  // 3
209
console.log(dateEntity.data.year);   // 2024
210
console.log(dateEntity.is_date());   // true
211

212
// Convert to JavaScript Date
213
const jsDate = dateEntity.date();
214
console.log(jsDate instanceof Date); // true
215

216
// Various date formats
217
const shortDate = nlp.date('3/15/24');
218
console.log(shortDate.data.month);   // 3
219

220
const relative = nlp.date('yesterday');
221
console.log(relative.is_date());     // true
222
```
223

224
### Place Class
225

226
Place entity with location component parsing.
227

228
```javascript { .api }
229
/**
230
 * Place class extending Noun for location analysis
231
 */
232
class Place extends Noun {
233
  /** City name component */
234
  city: string;
235
  /** State/region component */
236
  region: string;
237
  /** Country component */
238
  country: string;
239
  /** Full place title */
240
  title: string;
241
}
242
```
243

244
**Usage Examples:**
245

246
```javascript
247
// City parsing
248
const city = nlp.place('New York City');
249
console.log(city.city);    // 'New York City'
250
console.log(city.title);   // 'New York City'
251

252
// Full location
253
const location = nlp.place('San Francisco, California');
254
console.log(location.city);    // 'San Francisco'
255
console.log(location.region);  // 'California'
256

257
// International location
258
const intl = nlp.place('London, England');
259
console.log(intl.city);     // 'London'
260
console.log(intl.country);  // 'England'
261
```
262

263
### Organization Class
264

265
Organization entity for company and institution names.
266

267
```javascript { .api }
268
/**
269
 * Organization class extending Noun for organization analysis
270
 */
271
class Organization extends Noun {
272
  // Inherits all Noun properties and methods
273
  // Specialized for organization name recognition
274
}
275
```
276

277
**Usage Examples:**
278

279
```javascript
280
// Company names
281
const company = nlp.organization('Apple Inc.');
282
console.log(company.text);         // 'Apple Inc.'
283
console.log(company.is_organization()); // true
284

285
// Institutions
286
const university = nlp.organization('Harvard University');
287
console.log(university.text);      // 'Harvard University'
288

289
// Government organizations
290
const agency = nlp.organization('FBI');
291
console.log(agency.text);          // 'FBI'
292
console.log(agency.is_acronym());  // true
293
```
294

295
### Entity Detection from Text
296

297
All entity types can be automatically detected and extracted from text:
298

299
**Usage Examples:**
300

301
```javascript
302
const text = nlp.text(`
303
  Dr. Jane Smith from Harvard University visited Apple Inc. 
304
  in Cupertino on March 15th, 2024. The meeting cost $1,500 
305
  and lasted 2.5 hours.
306
`);
307

308
// Extract all entities
309
const people = text.people();
310
console.log(people[0].firstName);     // 'Jane'
311
console.log(people[0].honourific);    // 'Dr.'
312

313
const organizations = text.organizations();
314
console.log(organizations[0].text);   // 'Harvard University'
315
console.log(organizations[1].text);   // 'Apple Inc.'
316

317
const places = text.places();
318
console.log(places[0].text);          // 'Cupertino'
319

320
const dates = text.dates();
321
console.log(dates[0].data.month);     // 3
322
console.log(dates[0].data.day);       // 15
323

324
const values = text.values();
325
console.log(values[0].number);        // 1500
326
console.log(values[0].unit);          // 'dollar'
327
console.log(values[1].number);        // 2.5
328
console.log(values[1].unit);          // 'hour'
329
```
330

331
### Measurement Types
332

333
Value entities recognize various measurement categories:
334

335
```javascript { .api }
336
// Available measurement types
337
const measurementTypes = [
338
  'Temperature',  // degrees, celsius, fahrenheit
339
  'Volume',       // liters, gallons, cups
340
  'Distance',     // meters, feet, miles, kilometers
341
  'Weight',       // grams, pounds, kilograms
342
  'Area',         // square feet, acres, hectares
343
  'Frequency',    // hertz, rpm, bpm
344
  'Speed',        // mph, kph, knots
345
  'Data',         // bytes, MB, GB, TB
346
  'Energy',       // watts, calories, joules
347
  'Time',         // seconds, minutes, hours, days
348
  'Money'         // dollars, euros, yen, pounds
349
];
350
```
351

352
**Usage Examples:**
353

354
```javascript
355
// Different measurement types
356
console.log(nlp.value('100 mph').measurement);        // 'Speed'
357
console.log(nlp.value('500 GB').measurement);         // 'Data'
358
console.log(nlp.value('98.6°F').measurement);         // 'Temperature'
359
console.log(nlp.value('2.5 acres').measurement);      // 'Area'
360
console.log(nlp.value('150 calories').measurement);   // 'Energy'
361
console.log(nlp.value('60 bpm').measurement);         // 'Frequency'
362
```