Repository navigation
Description
The gap
Citation styles (Vancouver/PubMed, and Russian and Eastern European bibliographies) write a byline as the surname, then the initials, with no comma. nameparser reads by position, so the surname becomes the given name and the initials become the family. Measured on master 13e7314:
Armitage JO → given 'Armitage', family 'JO'
Armitage J.O. → given 'Armitage', family 'J.O.' (suffix-or-name reported)
Armitage J. O. → given 'Armitage', middle 'J.', family 'O.'
Gomes A.R.S. → given 'Gomes', family 'A.R.S.' (suffix-or-name reported)
SAFIN R.R. → given 'SAFIN', family 'R.R.'
McWilliams John P. → given 'McWilliams', middle 'John', family 'P.'
Armitage, J.O. → family 'Armitage', given 'J.O.' (right: the comma settles it)
This is the Latin-script twin of #995 (Иванов И.И. under locales.RU). #995 is scoped to the RU pack and leaves the default alone. This issue asks about the default parse, where the shape turns up regardless of language.
Measured: it goes both ways
ORCID credit names (orcid-researchers, 356,956 entries) of the form one word + initials, checked against the holder's own given and family boxes. "Surname first" means the word is in the family box and the first initial matches the given box:
| surname first | given name first | unclear | |
|---|---|---|---|
undotted (Islam MS, Kavitha S) |
138 | 61 | 36 |
dotted (Delgado G., Daniela S.) |
76 | 47 | 55 |
The "unclear" rows are mostly surname first when read by eye (Wagner F, BISWAS P. K., Ben-Salem S.), but the boxes don't confirm it. Most of the given-name-first rows are South Indian or Bangladeshi names, where an initial stands for the father's name or the family name (Gomathi KG, Kavitha S, FATIMA M.J.). That is the same convention #864 kept for Nepali paired initials (Ram Bahadur B.K. → family 'B.K.'). So surname first is the majority, roughly 2:1, but the minority is real and concentrated in particular regions.
The OpenAlex sample in ourresearch/human-name-parser-gold-standard has 37 rows where its labels read this shape surname first.
It collides with #659
#659 asks whether an all-caps word in a mixed-case name marks the family (DUPONT Jean). Here the all-caps word is initials, not a surname, and the two have the same shape:
Zhi LI → family 'LI' (right: LI is the surname, as #659 would have it)
Hongwei LIU → family 'LIU' (right)
Islam MS → suffix 'MS' (wrong: MS are the initials, read as the credential)
Armitage JO → family 'JO' (wrong)
Two or three capital letters can't be told apart by shape: LI and MS are written the same way. A #659 rule would reinforce the current misreading of Armitage JO, and a rule for this issue would reverse Zhi LI. The two need to be decided together, or each needs to exclude the other's case explicitly. The dotted form (Armitage J.O.) has no #659 collision, but it does collide with #864.
Options
- Leave the default alone and document the shape. Callers with citation-style input either insert the comma or declare
name_order=FAMILY_FIRST, which already readsArmitage JOas familyArmitage. Report the fork so a caller can see it. Dotted initials already reportsuffix-or-name, butJOreports nothing. - Read dotted initials after a single word as given initials by default (
Gomes A.R.S.,Armitage J. O.), but leave undotted capitals alone. The dotted ones can't be a Should an ALL-CAPS word in a mixed-case name mark the family name?DUPONT Jeangives givenDUPONT#659 surname, so the remaining cost is ShouldRam Bahadur B.K.keepB.K.as its family name? #864's shape and the South Indian minority above. That needs a measured decision. - An opt-in
Policyswitch for citation input, besidelone_name_word(Should a lone name word read as the given name under a family-first pack, soparser_for(locales.VI).parse("Anh")gives givenAnh? #1111). The tie to ShouldИванов И.И.read family 'Иванов' under locales.RU, where it now reads family 'И.И.'? #995 would then be a pack setting it.
Open
- Should a reading taken by position here report its alternative (
PARTICLE_OR_GIVEN's analogue, or a new kind)? A reader would hesitate overArmitage JO, which meets the bar for adding a kind. - How should a single initial be read (
Delgado G.,Armitage J)? ShouldИванов И.И.read family 'Иванов' under locales.RU, where it now reads family 'И.И.'? #995 leaves it open for Cyrillic for the same reason:Ivan P.also has this shape.
Found by scoring master against ourresearch/human-name-parser-gold-standard, an LLM-labelled sample of OpenAlex bylines.
🤖 Generated with Claude Code
Activity
belentani7 commentedon Nov 7, 2026
I measured option 1 on master (
3.0.0dev, viaParser(policy=Policy(name_order=nameparser.FAMILY_FIRST))) against the cases in your table, and I think it is worth separating what it fixes from what it changes.FAMILY_FIRSTdoes not resolve the shape ambiguity — it installs the opposite prior. Everysingle-word + initialsname gets inverted unconditionally, so the rows it fixes and the rows it breaks are the same rows. On a 17-name sample taken from your table:FAMILY_FIRSTFixes (9):
Armitage JO,Armitage J.O.,Armitage J. O.,Gomes A.R.S.,SAFIN R.R.,McWilliams John P.,Delgado G.,Ivan P.,Wagner F.Breaks (6):
Zhi LI→LI | Zhi,Hongwei LIU→LIU | Hongwei,DUPONT Jean→Jean | DUPONT,Kavitha S→S | Kavitha,Ram Bahadur B.K.→Bahadur | Ram,FATIMA M.J.→M.J. | FATIMA.Two details from that run that bear on the decision:
FAMILY_FIRSTdoes not fixIslam MSeither — family comes back empty in both modes — so the ShouldRam Bahadur B.K.keepB.K.as its family name? #864 shape is not helped by the switch.Armitage J. O.readsgiven 'J.',family 'Armitage'underFAMILY_FIRST, which is the reading you want; worth a fixture, since the default drops theO.intomiddleand a future rule could regress it.My read: the pairing that stands up is option 1's first half plus option 2's reporting half — keep the default, report the fork so a caller can see it, and let the corpus owner pick
name_order.FAMILY_FIRSTis the right answer for a bibliography and the wrong one for a mixed aggregator, and only the caller knows which it has. Option 2 as a default change (dotted initials read as given by default) is the riskier one, because for the dotted form ORCID is 76 surname-first against 47 given-first: that is a 62% majority, not the 69% the undotted row shows, so a shape rule would be wrong on nearly four rows for every six it fixes unless it also reports the fork.Caveat on the numbers: 17 hand-labelled names are a sanity check on the shape, not a substitute for the OpenAlex/ORCID scoring you already have. I did not touch the corpora.