Metadata-Version: 2.4
Name: bib2coa
Version: 1.2
Summary: A command-line tool that converts a BibTeX file to a TSV of author-paper pairs for NSF COA forms
Author-email: "Alex S. Holehouse" <alex.holehouse@wustl.edu>
License: MIT
Project-URL: Source, https://github.com/holehouse-lab/bib2coa
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bibtexparser
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Dynamic: license-file

# bib2coa

A command-line tool and Python library that converts a BibTeX file (`.bib`) into a tab-separated file (TSV) of unique author–paper pairs — designed to jumpstart the creation of NSF-compliant Collaborators & Other Affiliations (COA) documents.

## What does this do?

- Parses a `.bib` file and extracts every author and their associated paper title + year.
- Merges duplicate entries (same year + title) so each author appears only once.
- Writes a clean two-column TSV: `author<TAB>year - paper title`.
- Optionally prints summary statistics (number of entries, unique papers, unique authors).

## What does this NOT do?

It does **not** automatically look up author affiliations, institutions, or any other metadata beyond what is in the BibTeX file. You will still need to fill those in manually — but this tool saves you from copying and pasting author names out of PDFs.

## Installation

### From PyPI (stable release)

```bash
pip install bib2coa
```

### From source

```bash
git clone https://github.com/holehouse-lab/bib2coa.git
cd bib2coa
pip install .
```

> **Requires Python 3.6+** and the [`bibtexparser`](https://pypi.org/project/bibtexparser/) package (installed automatically).

## Command-line usage

### Basic usage

```bash
bib2coa my_references.bib
```

This reads `my_references.bib` and writes `coa_initial.tsv` in the current directory.

### Custom output filename

```bash
bib2coa my_references.bib --output my_coa.tsv
```

### Show summary statistics

```bash
bib2coa my_references.bib --stats
```

Example output:

```
+----------------------+
| Summary statistics   |
+----------------------+
Number of bibtex entries     : 42
Number of unique paper names : 38
Number of unique authors     : 107
Wrote 107 author-paper pairs to coa_initial.tsv
```

### Show version

```bash
bib2coa --version
```

### All options

| Flag | Description |
|---|---|
| `file` (positional) | Path to the BibTeX `.bib` file |
| `--output FILENAME` | Output TSV filename (default: `coa_initial.tsv`) |
| `--stats` | Print summary statistics after processing |
| `--version` | Show version and exit |

## Python API

You can also use `bib2coa` as a library in your own scripts:

```python
from bib2coa import parse_bibtex, write_tsv

# Parse a BibTeX file
unique_pairs, stats = parse_bibtex("my_references.bib")

# unique_pairs is a list of (author, paper_label) tuples
for author, paper in unique_pairs:
    print(f"{author}  ->  {paper}")

# stats is a dict with keys:
#   'num_entries', 'num_unique_papers', 'num_unique_authors'
print(f"Found {stats['num_unique_authors']} unique authors")

# Write to a TSV file
write_tsv(unique_pairs, "coa_initial.tsv")
```

### `parse_bibtex(filepath)`

Parse a BibTeX file and return unique author–paper pairs.

**Parameters:**
- `filepath` (str) — Path to a `.bib` file.

**Returns:**
- `unique_pairs` (list of tuple) — Each tuple is `(author_name, paper_label)` where `paper_label` is formatted as `"YEAR - Title"`.
- `stats` (dict) — Keys: `num_entries`, `num_unique_papers`, `num_unique_authors`.

**Raises:**
- `Bib2COAException` — If the file does not exist or cannot be parsed.

### `write_tsv(unique_pairs, output_path)`

Write author–paper pairs to a tab-separated file.

**Parameters:**
- `unique_pairs` (list of tuple) — Output from `parse_bibtex()`.
- `output_path` (str) — Path for the output TSV file.

### `Bib2COAException`

Custom exception raised when a file is missing or a BibTeX file cannot be parsed.

## Output format

The output TSV has two columns separated by a tab character:

```
Smith, John     2020 - A study of protein folding
Doe, Jane       2020 - A study of protein folding
Garcia, Maria   2021 - Phase separation in the cell
Kumar, Raj      2019 - Intrinsically disordered regions
```

- **Column 1:** Author name (as it appears in the BibTeX file).
- **Column 2:** Year and cleaned title (LaTeX braces `{}` are stripped).

Each author appears exactly once, associated with the first paper where they were encountered.

## Recommended workflow

Below is the workflow we recommend for making an [NSF-compliant COA file](https://www.nsf.gov/bfa/dias/policy/coa.jsp).

### 1. Build your references

Use your reference manager (we recommend [PaperPile](https://paperpile.com/)) to select all the references you want to process and export them as a single BibTeX file.

For PaperPile, select all the papers you want to include, copy the citations as BibTeX keys to your clipboard, and save them as a `.bib` file (e.g. `nsf.bib`).

![paperpile_screenshot](docs/images/img1-01.png)

### 2. Run bib2coa

```bash
bib2coa --stats nsf.bib
```

This generates `coa_initial.tsv`.

### 3. Edit in a spreadsheet

Open `coa_initial.tsv` in Excel, Google Sheets, or Numbers using a tab delimiter. From there, reorganize and add affiliations to match the appropriate table in the [NSF COA template](https://www.nsf.gov/bfa/dias/policy/coa.jsp).

## License

MIT
