Metadata-Version: 2.4
Name: fieldwork
Version: 0.1.0
Summary: Explore unfamiliar data through patterns, evidence, and reproducible investigations
Author: Beatrice Brown-Mulry
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2.3
Requires-Dist: wcwidth>=0.2 ; extra == 'unicode'
Requires-Python: >=3.11, <3.15
Project-URL: Source, https://github.com/beatrice-b-m/fieldwork
Project-URL: Documentation, https://fieldwork.beabm.dev
Project-URL: Issues, https://github.com/beatrice-b-m/fieldwork/issues
Provides-Extra: unicode
Description-Content-Type: text/markdown

# Fieldwork

Explore unfamiliar data through patterns, source-row evidence, and reproducible
investigations. Fieldwork is a Python toolkit for researchers working with pandas
dataframes: find availability families, examine dependencies and candidate grains,
then choose a useful census path through the data.

**Alpha release.** Python 3.11–3.14; pandas and NumPy are the only required runtime
dependencies.

![Availability in the worked example](https://raw.githubusercontent.com/beatrice-b-m/fieldwork/v0.1.0/docs/assets/availability.png)

```bash
pip install fieldwork
```

```python
import pandas as pd
import fieldwork as fw

df = pd.DataFrame({
    "site": ["North", "North", "South", "South"],
    "exam": [1, 1, 2, 2],
    "image": [10, 11, 20, 21],
    "report": ["ok", "ok", "ok", None],
})
overview = fw.explore(df)
availability = fw.missingness(df, entity="exam", min_implication=0.75)
paths = fw.suggest_paths(df, features=["site", "exam"])
tree = paths.best.census(df)
print(tree)
```

Use `result.to_frame()` for discovery tables and `result.inspect(df, finding_id,
exceptions=True)` for the saved example rows. Duplicate indexes are supported;
inspection checks the ordered source dataset. Use `result.select(df, finding_id)`
to recover the complete matching population as a `Scope`, then pass that scope to
`missingness` or `suggest_paths`. `paths.best.census(df)` preserves the selected
population and sentinel conventions. Choose `unit="entities"` with `entity=` for
equal entity weights, or keep the default `unit="rows"`. Browse connected feature
evidence with `overview.relationships("image")`. Save results with `to_dict()`, export
with `render_svg()` or `render_html()`, and reapply a `Recipe` to later deliveries.

![Observed census from the worked example](https://raw.githubusercontent.com/beatrice-b-m/fieldwork/v0.1.0/docs/assets/census.png)

The single-table workflow includes independent levels, contextual pair summaries,
joint counts and absence, exact grain graphs, bounded approximate dependency
discovery, five census-path objectives, availability signatures and entity summaries,
string and numeric patterns, scoped investigations, and delivery comparisons.
Topology-only exports retain structure while suppressing quantitative evidence.
Automatic related-table discovery is a later extension.

- [User documentation source](https://github.com/beatrice-b-m/fieldwork-docs)
- [Developer documentation](https://github.com/beatrice-b-m/fieldwork/blob/v0.1.0/docs/index.md): architecture, contracts, algorithms, releases
- [Investigation journey and units](https://github.com/beatrice-b-m/fieldwork/blob/v0.1.0/docs/investigation.md)
- [Executable investigation](https://github.com/beatrice-b-m/fieldwork/blob/v0.1.0/examples/investigation.py) and [notebook](https://github.com/beatrice-b-m/fieldwork/blob/v0.1.0/examples/investigation.ipynb)
- [MIT license](https://github.com/beatrice-b-m/fieldwork/blob/v0.1.0/LICENSE) and [extraction provenance](https://github.com/beatrice-b-m/fieldwork/blob/v0.1.0/NOTICE)

For development: `uv sync --locked`, `uv run pytest`, and `uv build`. Documentation
images are generated from executable examples using the public renderers. Run
`uv run python scripts/generate_assets.py` after behavior or styling changes;
CI checks concurrence and release builds regenerate the assets.
