studio2ped 0.1.0__tar.gz → 0.2.0__tar.gz

studio2ped-0.2.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+## 0.2.0
+
+- People are now identified by their pedigree numbers (I-1, II-3 and so on),
+  worked out exactly as Pedigree Studio shows them and as studio2ga4gh 0.4
+  writes them, so the same person has the same identifier in the PED file and
+  in the GA4GH files. Version 0.1.0 took identifiers from the text under each
+  symbol, which usually holds a name and an age (`Alice_50`), sometimes a
+  condition (`Bowel_cancer`), and is not always unique: in the Lynch example
+  two cousins labelled 26 got the same identifier, which `mpedtools validate`
+  rejects.
+- `--ids` chooses the identifiers: `numbers` (the default), `drawing` (the
+  labels the drawing shows under its numbering setting: numbers, letters or
+  labels typed in), `studio` (Pedigree Studio's own ids) or `text` (0.1.0's
+  identifiers). Whatever the choice, an identifier that would be shared by two
+  people, be empty or be `0` (which PED reads as "no parent") is replaced by
+  the person's pedigree number, and the command says so.
+- The "no children" and "infertility" symbols are no longer written as
+  people. Pedigree Studio stores them as children of the couple, so 0.1.0 put
+  them in the file as individuals of unknown sex (29 individuals for the 27
+  people in the features example). They are left out now, with a note naming
+  the couple.
+- Adoptive parents and surrogates are no longer written as parents. A child
+  joined to a couple by a dashed line (an adoption) and a parent marked S (a
+  gestational carrier) are not genetic relations, and a linkage program reads
+  the father and mother columns as genetic parents, so 0.1.0's files gave
+  wrong ones. Those parents are now 0, with a note, which is also what
+  studio2ga4gh's PED-style pedigree gives: a solid line from birth parents
+  still counts, and so does a donor (D).
+- A symbol standing for several people (a number such as 3 in the symbol) is
+  still written as one person, but the command now says so.
+- An ontology id written after a condition's name in the colour key, as
+  studio2ga4gh reads it (`Condition X [MONDO:0009061]`), is left out of the
+  MPED column name, which is now `Condition_X` instead of
+  `Condition_X_MONDO0009061`. Only the ids of ontologies count (the HPO,
+  Mondo, OMIM, Orphanet, SNOMED CT and the others studio2ga4gh can declare):
+  anything else in brackets, such as `Hypertension (BP:160/95)`, stays part of
+  the name. Two conditions that would give the same column name are told apart
+  with `_2`, `_3`.
+- Without `-o`, the output is named after the input without `.studio.json`:
+  `okafor.studio.json` gives `okafor.mped`, where 0.1.0 wrote
+  `okafor.studio.mped`.
+- Within each generation, people are listed in the order of the drawing,
+  from left to right, rather than in the order of Pedigree Studio's internal
+  ids.
+- Session files are read as UTF-8 (with or without a byte-order mark) and the
+  PED files written as UTF-8, whatever the computer's own setting, so names
+  with accents no longer fail on Windows.
+- `-d` makes the output folder if it does not exist. In 0.1.0 the README's own
+  example (`-d ./output/`) failed unless the folder was already there, and
+  the error said that the input file could not be found.
+- `studio2ped_standalone.py` is made from the package by
+  `tools/make_standalone.py`, and a test checks that it is up to date and
+  writes exactly what the package writes.
+- New in the Python interface: `convert(..., ids=...)`,
+  `convert_file(..., ids=...)`, `individual_ids`, `pedigree_numbers` and
+  `ID_CHOICES`; `ConversionResult` has `notes` and `ids`.
+- `--version`, tests run on Python 3.9 to 3.14, and releases are published to
+  PyPI from GitHub.
+
+Commands written for 0.1.0 still run unchanged. To get 0.1.0's identifiers,
+add `--ids text`.
+
+## 0.1.0
+
+Released on PyPI on 20 May 2026.

studio2ped-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include CHANGELOG.md
+include studio2ped_standalone.py
+include tools/make_standalone.py
+recursive-include tests *.py *.json *.mped *.ped

studio2ped-0.2.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: studio2ped
+Version: 0.2.0
+Summary: Convert Pedigree Studio session JSON to PED/MPED pedigree files
+Author-email: Tim Hearn <tjh70@cam.ac.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/comparativechrono/studio2ped
+Project-URL: Issues, https://github.com/comparativechrono/studio2ped/issues
+Project-URL: Changelog, https://github.com/comparativechrono/studio2ped/blob/main/CHANGELOG.md
+Keywords: pedigree,genetics,ped,family-tree,clinical-genetics,pedigree-studio
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# studio2ped
+
+Convert families drawn in [Pedigree Studio](https://github.com/comparativechrono/PedigreeStudio)
+into standard PED pedigree files, or into extended MPED (multi-phenotype PED)
+files when more than one condition is recorded.
+
+## Installation
+
+```bash
+pip install studio2ped
+```
+
+It needs Python 3.9 or later and nothing else. You can also use the
+standalone script, `studio2ped_standalone.py`, without installing anything.
+
+## Usage
+
+### Command line
+
+```bash
+# Basic conversion: writes okafor.ped, or okafor.mped if the family needs MPED
+studio2ped okafor.studio.json
+
+# Specify output name and directory
+studio2ped okafor.studio.json -o my_pedigree -d ./output/
+
+# Identify people by the labels the drawing shows, instead of pedigree numbers
+studio2ped okafor.studio.json --ids drawing
+
+# Using the standalone script
+python studio2ped_standalone.py okafor.studio.json
+```
+
+The command prints a short summary, the files it wrote and notes on anything
+you should know: symbols that are not people and were left out, identifiers
+that had to be changed, and so on.
+
+Commands written for version 0.1.0 still work. The difference you will notice
+is that people are now identified by their pedigree numbers; add `--ids text`
+to get the identifiers 0.1.0 used (see [Identifying people](#identifying-people)).
+
+### Python API
+
+```python
+import json
+import studio2ped
+
+with open("okafor.studio.json", encoding="utf-8") as f:
+    session = json.load(f)
+
+result = studio2ped.convert(session, "okafor")     # ids="drawing", "studio" or "text" to choose identifiers
+print(result.summary)
+for note in result.notes:
+    print("Note:", note)
+for filename, content in result.files:
+    print(f"--- {filename} ---")
+    print(content)
+
+# From file to file
+result = studio2ped.convert_file("okafor.studio.json")
+for filepath, _ in result.files:
+    print(f"Written: {filepath}")
+```
+
+## What it does
+
+The converter reads a Pedigree Studio session file and:
+
+1. **Detects separate pedigrees**: if the canvas holds several unconnected
+   families, each is written to a file of its own.
+2. **Works out the family structure** from the partnership and child lines,
+   not from where the symbols are, so a rearranged pedigree converts correctly.
+3. **Leaves out symbols that are not people.** Pedigree Studio stores the "no
+   children" bar and the "infertility" double bar as children of the couple;
+   they are not written as individuals, and a note names the couple.
+4. **Gives genetic parents only.** The father and mother columns of a PED
+   file are genetic parents. A child joined to a couple by a dashed line (an
+   adoption) gets 0 for that couple, and so does the place of a parent marked
+   S (a gestational carrier), with a note in each case; a parent marked D (a
+   donor) is a genetic parent. studio2ga4gh's PED-style pedigree gives the
+   same.
+5. **Extracts phenotypes** from the colour key: solid fills, half fills,
+   quartered fills and shading patterns are all recognised.
+6. **Detects carrier notation**: centre dots (●) and half-filled symbols mark
+   carriers.
+7. **Chooses the format**:
+   - **one phenotype** → a standard `.ped` file (6 columns);
+   - **several phenotypes**, or **carrier notation alongside a phenotype** → an
+     extended `.mped` file.
+
+## Identifying people
+
+| `--ids` | Each person is identified by |
+|---|---|
+| `numbers` (the default) | their pedigree number as Pedigree Studio shows it: the generation in Roman numerals and the position from the left, such as `II-3` |
+| `drawing` | the label the drawing shows under its numbering setting: pedigree numbers, letters (`II-C`, or `A`, `B`, `C` …) or labels typed in |
+| `studio` | Pedigree Studio's own id, such as `p-3` |
+| `text` | what version 0.1.0 used: the label typed in if there is one, otherwise the first line of the text under the symbol, otherwise Pedigree Studio's id |
+
+Pedigree numbers are the ones studio2ga4gh writes into the GA4GH files, so a
+person can be followed from one file to the other. The text under a symbol
+usually holds a name and an age ("Alice, 50"), so `text`, and `drawing` when
+the drawing has labels typed in, can put names into the file: use them only
+when that is acceptable for wherever the file is going.
+
+Identifiers can't contain spaces, so spaces become underscores and other
+punctuation is dropped: "J. Mensah" becomes `J_Mensah`. studio2ga4gh makes its
+ids from labels the same way, so with the same choice a person has the same
+identifier in the PED file and in the GA4GH files. No two people may share an
+identifier, and `0` means "no parent" in a PED file, so if a label would be
+shared by two people (two cousins both labelled "26", say), would be empty or
+would be `0`, the person is given their pedigree number instead, and a note
+says so.
+
+Pedigree numbers follow the drawing, as in Pedigree Studio: a new generation
+starts 80 pixels or more below the first symbol of the generation above, and
+the "no children" and "infertility" symbols are counted in their row, even
+though they are not written to the file.
+
+## Output formats
+
+### Standard PED (`.ped`)
+
+The standard 6-column format used by PLINK, GATK and most genetics tools:
+
+```
+# Family: FAM1
+# FamID  IndID  FatherID  MotherID  Sex  Phenotype
+FAM1     I-1    0         0         1    1
+FAM1     I-2    0         0         2    1
+FAM1     II-1   I-1       I-2       2    2
+```
+
+Phenotype codes: `0` = unknown, `1` = unaffected, `2` = affected. The columns
+are separated by tabs.
+
+### Extended MPED (`.mped`)
+
+A multi-phenotype extension for pedigrees in which more than one condition is
+tracked. It adds a header line naming the phenotype columns, and a carrier
+status:
+
+```
+# MPED v1	Breast_cancer	Carrier
+# FamID	IndID	FatherID	MotherID	Sex	Breast_cancer	Carrier
+FAM1	I-1	0	0	1	1	1
+FAM1	I-2	0	0	2	3	3
+FAM1	II-1	I-1	I-2	2	2	1
+```
+
+Phenotype codes: `0` = unknown, `1` = unaffected, `2` = affected, `3` = carrier.
+
+The format is easy to read by program: the first line declares the format and
+names the phenotype columns, the second is a header for people to read, and
+the data lines have the same tab-separated columns as standard PED, with one
+more column for each phenotype.
+
+Column names are the condition names from the colour key, with spaces turned
+into underscores. An ontology id written in brackets after a name, as
+studio2ga4gh reads it ("Breast cancer [MONDO:0007254]"), is left out of the
+column name, which is then `Breast_cancer`, and a note says which id it had.
+Only the ids of ontologies studio2ga4gh can declare count (the HPO, Mondo,
+OMIM, Orphanet, SNOMED CT and so on): anything else in brackets, such as
+"Hypertension (BP:160/95)", stays part of the name.
+If two conditions would give the same column name, the second becomes
+`Breast_cancer_2`.
+
+## Phenotype detection
+
+The converter maps Pedigree Studio's markings to phenotype status using the
+colour key:
+
+| Marking | Colour key entry | Status |
+|---------------|-------------------|--------|
+| Solid colour fill | `#rrggbb` | Affected (2) |
+| Full shading (stripes/dots) | `shading:pattern:full` | Affected (2) |
+| Half colour fill (one side only) | `#rrggbb` | Carrier (3) |
+| Half shading | `shading:pattern:half-left` | Carrier (3) |
+| Quartered fill (any quarter) | `#rrggbb` | Affected (2) |
+| Centre dot (●) | — | Carrier (3) |
+| No fill | — | Unaffected (1) |
+
+Phenotype names are the text typed into the colour key (for example "Breast
+cancer"). A colour with no text in the key is ignored.
+
+A centre dot gives 3 in the Carrier column, and in the column of the condition
+the person is drawn with; on a symbol with no fill it is the first condition
+in the key.
+
+## Multiple pedigrees
+
+If a drawing holds several unconnected families (common when several are
+drawn on the same canvas), each is written to a file of its own:
+
+```
+okafor_1.mped    # the first family
+okafor_2.mped    # the second family
+```
+
+The colour key belongs to the whole drawing, so every family is written in the
+same format: all `.ped` or all `.mped`.
+
+## The standalone script
+
+`studio2ped_standalone.py` is the whole package in one file, for computers
+where installing a package is awkward; it takes the same options as the
+`studio2ped` command. It is made from the package by
+`python tools/make_standalone.py`, and a test checks that the two agree.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## Licence
+
+MIT

studio2ped-0.2.0/README.md

@@ -0,0 +1,219 @@
+# studio2ped
+
+Convert families drawn in [Pedigree Studio](https://github.com/comparativechrono/PedigreeStudio)
+into standard PED pedigree files, or into extended MPED (multi-phenotype PED)
+files when more than one condition is recorded.
+
+## Installation
+
+```bash
+pip install studio2ped
+```
+
+It needs Python 3.9 or later and nothing else. You can also use the
+standalone script, `studio2ped_standalone.py`, without installing anything.
+
+## Usage
+
+### Command line
+
+```bash
+# Basic conversion: writes okafor.ped, or okafor.mped if the family needs MPED
+studio2ped okafor.studio.json
+
+# Specify output name and directory
+studio2ped okafor.studio.json -o my_pedigree -d ./output/
+
+# Identify people by the labels the drawing shows, instead of pedigree numbers
+studio2ped okafor.studio.json --ids drawing
+
+# Using the standalone script
+python studio2ped_standalone.py okafor.studio.json
+```
+
+The command prints a short summary, the files it wrote and notes on anything
+you should know: symbols that are not people and were left out, identifiers
+that had to be changed, and so on.
+
+Commands written for version 0.1.0 still work. The difference you will notice
+is that people are now identified by their pedigree numbers; add `--ids text`
+to get the identifiers 0.1.0 used (see [Identifying people](#identifying-people)).
+
+### Python API
+
+```python
+import json
+import studio2ped
+
+with open("okafor.studio.json", encoding="utf-8") as f:
+    session = json.load(f)
+
+result = studio2ped.convert(session, "okafor")     # ids="drawing", "studio" or "text" to choose identifiers
+print(result.summary)
+for note in result.notes:
+    print("Note:", note)
+for filename, content in result.files:
+    print(f"--- {filename} ---")
+    print(content)
+
+# From file to file
+result = studio2ped.convert_file("okafor.studio.json")
+for filepath, _ in result.files:
+    print(f"Written: {filepath}")
+```
+
+## What it does
+
+The converter reads a Pedigree Studio session file and:
+
+1. **Detects separate pedigrees**: if the canvas holds several unconnected
+   families, each is written to a file of its own.
+2. **Works out the family structure** from the partnership and child lines,
+   not from where the symbols are, so a rearranged pedigree converts correctly.
+3. **Leaves out symbols that are not people.** Pedigree Studio stores the "no
+   children" bar and the "infertility" double bar as children of the couple;
+   they are not written as individuals, and a note names the couple.
+4. **Gives genetic parents only.** The father and mother columns of a PED
+   file are genetic parents. A child joined to a couple by a dashed line (an
+   adoption) gets 0 for that couple, and so does the place of a parent marked
+   S (a gestational carrier), with a note in each case; a parent marked D (a
+   donor) is a genetic parent. studio2ga4gh's PED-style pedigree gives the
+   same.
+5. **Extracts phenotypes** from the colour key: solid fills, half fills,
+   quartered fills and shading patterns are all recognised.
+6. **Detects carrier notation**: centre dots (●) and half-filled symbols mark
+   carriers.
+7. **Chooses the format**:
+   - **one phenotype** → a standard `.ped` file (6 columns);
+   - **several phenotypes**, or **carrier notation alongside a phenotype** → an
+     extended `.mped` file.
+
+## Identifying people
+
+| `--ids` | Each person is identified by |
+|---|---|
+| `numbers` (the default) | their pedigree number as Pedigree Studio shows it: the generation in Roman numerals and the position from the left, such as `II-3` |
+| `drawing` | the label the drawing shows under its numbering setting: pedigree numbers, letters (`II-C`, or `A`, `B`, `C` …) or labels typed in |
+| `studio` | Pedigree Studio's own id, such as `p-3` |
+| `text` | what version 0.1.0 used: the label typed in if there is one, otherwise the first line of the text under the symbol, otherwise Pedigree Studio's id |
+
+Pedigree numbers are the ones studio2ga4gh writes into the GA4GH files, so a
+person can be followed from one file to the other. The text under a symbol
+usually holds a name and an age ("Alice, 50"), so `text`, and `drawing` when
+the drawing has labels typed in, can put names into the file: use them only
+when that is acceptable for wherever the file is going.
+
+Identifiers can't contain spaces, so spaces become underscores and other
+punctuation is dropped: "J. Mensah" becomes `J_Mensah`. studio2ga4gh makes its
+ids from labels the same way, so with the same choice a person has the same
+identifier in the PED file and in the GA4GH files. No two people may share an
+identifier, and `0` means "no parent" in a PED file, so if a label would be
+shared by two people (two cousins both labelled "26", say), would be empty or
+would be `0`, the person is given their pedigree number instead, and a note
+says so.
+
+Pedigree numbers follow the drawing, as in Pedigree Studio: a new generation
+starts 80 pixels or more below the first symbol of the generation above, and
+the "no children" and "infertility" symbols are counted in their row, even
+though they are not written to the file.
+
+## Output formats
+
+### Standard PED (`.ped`)
+
+The standard 6-column format used by PLINK, GATK and most genetics tools:
+
+```
+# Family: FAM1
+# FamID  IndID  FatherID  MotherID  Sex  Phenotype
+FAM1     I-1    0         0         1    1
+FAM1     I-2    0         0         2    1
+FAM1     II-1   I-1       I-2       2    2
+```
+
+Phenotype codes: `0` = unknown, `1` = unaffected, `2` = affected. The columns
+are separated by tabs.
+
+### Extended MPED (`.mped`)
+
+A multi-phenotype extension for pedigrees in which more than one condition is
+tracked. It adds a header line naming the phenotype columns, and a carrier
+status:
+
+```
+# MPED v1	Breast_cancer	Carrier
+# FamID	IndID	FatherID	MotherID	Sex	Breast_cancer	Carrier
+FAM1	I-1	0	0	1	1	1
+FAM1	I-2	0	0	2	3	3
+FAM1	II-1	I-1	I-2	2	2	1
+```
+
+Phenotype codes: `0` = unknown, `1` = unaffected, `2` = affected, `3` = carrier.
+
+The format is easy to read by program: the first line declares the format and
+names the phenotype columns, the second is a header for people to read, and
+the data lines have the same tab-separated columns as standard PED, with one
+more column for each phenotype.
+
+Column names are the condition names from the colour key, with spaces turned
+into underscores. An ontology id written in brackets after a name, as
+studio2ga4gh reads it ("Breast cancer [MONDO:0007254]"), is left out of the
+column name, which is then `Breast_cancer`, and a note says which id it had.
+Only the ids of ontologies studio2ga4gh can declare count (the HPO, Mondo,
+OMIM, Orphanet, SNOMED CT and so on): anything else in brackets, such as
+"Hypertension (BP:160/95)", stays part of the name.
+If two conditions would give the same column name, the second becomes
+`Breast_cancer_2`.
+
+## Phenotype detection
+
+The converter maps Pedigree Studio's markings to phenotype status using the
+colour key:
+
+| Marking | Colour key entry | Status |
+|---------------|-------------------|--------|
+| Solid colour fill | `#rrggbb` | Affected (2) |
+| Full shading (stripes/dots) | `shading:pattern:full` | Affected (2) |
+| Half colour fill (one side only) | `#rrggbb` | Carrier (3) |
+| Half shading | `shading:pattern:half-left` | Carrier (3) |
+| Quartered fill (any quarter) | `#rrggbb` | Affected (2) |
+| Centre dot (●) | — | Carrier (3) |
+| No fill | — | Unaffected (1) |
+
+Phenotype names are the text typed into the colour key (for example "Breast
+cancer"). A colour with no text in the key is ignored.
+
+A centre dot gives 3 in the Carrier column, and in the column of the condition
+the person is drawn with; on a symbol with no fill it is the first condition
+in the key.
+
+## Multiple pedigrees
+
+If a drawing holds several unconnected families (common when several are
+drawn on the same canvas), each is written to a file of its own:
+
+```
+okafor_1.mped    # the first family
+okafor_2.mped    # the second family
+```
+
+The colour key belongs to the whole drawing, so every family is written in the
+same format: all `.ped` or all `.mped`.
+
+## The standalone script
+
+`studio2ped_standalone.py` is the whole package in one file, for computers
+where installing a package is awkward; it takes the same options as the
+`studio2ped` command. It is made from the package by
+`python tools/make_standalone.py`, and a test checks that the two agree.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## Licence
+
+MIT

{studio2ped-0.1.0 → studio2ped-0.2.0}/pyproject.toml

@@ -1,13 +1,14 @@
 [build-system]
-requires = ["setuptools>=61.0"]
+requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "studio2ped"
-version = "0.1.0"
+version = "0.2.0"
 description = "Convert Pedigree Studio session JSON to PED/MPED pedigree files"
 readme = "README.md"
-license = {text = "MIT"}
+license = "MIT"
+license-files = ["LICENSE"]
 requires-python = ">=3.9"
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -15,25 +16,26 @@ classifiers = [
     "Intended Audience :: Healthcare Industry",
     "Topic :: Scientific/Engineering :: Bio-Informatics",
     "Topic :: Scientific/Engineering :: Medical Science Apps.",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
 ]
 keywords = ["pedigree", "genetics", "ped", "family-tree", "clinical-genetics", "pedigree-studio"]
 authors = [
     {name = "Tim Hearn", email = "tjh70@cam.ac.uk"},
 ]
 
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
 [project.scripts]
 studio2ped = "studio2ped.cli:main"
 
 [project.urls]
 Homepage = "https://github.com/comparativechrono/studio2ped"
 Issues = "https://github.com/comparativechrono/studio2ped/issues"
+Changelog = "https://github.com/comparativechrono/studio2ped/blob/main/CHANGELOG.md"
 
 [tool.setuptools.packages.find]
 include = ["studio2ped*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

studio2ped-0.2.0/studio2ped/__init__.py

@@ -0,0 +1,10 @@
+"""studio2ped — Convert Pedigree Studio session JSON to PED/MPED pedigree files."""
+
+__version__ = "0.2.0"
+
+from .converter import (  # noqa: E402
+    ID_CHOICES, ConversionResult, convert, convert_file, individual_ids, parse_session, pedigree_numbers,
+)
+
+__all__ = ["convert", "convert_file", "parse_session", "individual_ids", "pedigree_numbers", "ID_CHOICES",
+           "ConversionResult", "__version__"]

{studio2ped-0.1.0 → studio2ped-0.2.0}/studio2ped/cli.py

@@ -5,7 +5,8 @@ from __future__ import annotations
 import argparse
 import sys
 
-from .converter import convert_file
+from . import __version__
+from .converter import ID_CHOICES, convert_file
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -21,7 +22,7 @@ def main(argv: list[str] | None = None) -> int:
         "-o", "--output-prefix",
         default=None,
         dest="output_prefix",
-        help="Base name for output files (default: input filename stem)",
+        help="Base name for output files (default: the input file's name without .studio.json)",
     )
     parser.add_argument(
         "-d", "--output-dir",
@@ -29,6 +30,15 @@ def main(argv: list[str] | None = None) -> int:
         dest="output_dir",
         help="Directory for output files (default: same as input file)",
     )
+    parser.add_argument(
+        "--ids",
+        choices=ID_CHOICES,
+        default="numbers",
+        help="How people are identified: pedigree numbers such as II-3 (numbers, the default), the labels "
+             "the drawing shows (drawing), Pedigree Studio's own ids (studio), or version 0.1.0's "
+             "identifiers taken from the text under each symbol, which are often names (text)",
+    )
+    parser.add_argument("--version", action="version", version=f"studio2ped {__version__}")
 
     args = parser.parse_args(argv)
 
@@ -37,13 +47,16 @@ def main(argv: list[str] | None = None) -> int:
             args.input,
             output_prefix=args.output_prefix,
             output_dir=args.output_dir,
+            ids=args.ids,
         )
         print(result.summary)
         for filepath, _ in result.files:
             print(f"  Written: {filepath}")
+        for note in result.notes:
+            print(f"  Note: {note}")
         return 0
-    except FileNotFoundError:
-        print(f"Error: file not found: {args.input}", file=sys.stderr)
+    except FileNotFoundError as e:
+        print(f"Error: file not found: {e.filename or args.input}", file=sys.stderr)
         return 1
     except Exception as e:
         print(f"Error: {e}", file=sys.stderr)