fieldwork 0.1.0__tar.gz

fieldwork-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beatrice Brown-Mulry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fieldwork-0.1.0/NOTICE

@@ -0,0 +1,6 @@
+Fieldwork exploration foundation, tests and benchmark extracted from bea-tools
+by Beatrice Brown-Mulry, declared MIT in its pyproject.toml.
+Source: https://github.com/beatrice-b-m/bea-tools
+Commit: 4e4f1704cbca91a314652b0c99f86d8f4a2c4f90
+The source repository contained no standalone license text at extraction.
+No DICOM, sampling code, or compatibility accessors were migrated.

fieldwork-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+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.

fieldwork-0.1.0/README.pypi.md

@@ -0,0 +1,62 @@
+# 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.

fieldwork-0.1.0/benchmarks/discovery.py

@@ -0,0 +1,32 @@
+"""Measure end-to-end discovery and strict JSON result size on seeded wide data."""
+import argparse
+import json
+from pathlib import Path
+import time
+
+import numpy as np
+import pandas as pd
+import fieldwork as fw
+
+parser = argparse.ArgumentParser()
+parser.add_argument('--rows', type=int, default=2000)
+parser.add_argument('--columns', type=int, default=24)
+parser.add_argument('--output', type=Path, required=True)
+args = parser.parse_args()
+rng = np.random.default_rng(721)
+frame = pd.DataFrame({f'field_{i}': np.where(rng.random(args.rows) < .7, np.nan,
+                      rng.integers(0, 8, args.rows)) for i in range(args.columns)})
+frame['entity'] = np.arange(args.rows)//4
+records = []
+for name, run in [('missingness', lambda: fw.missingness(frame, entity='entity')),
+                  ('dependencies', lambda: fw.discover_dependencies(frame, max_candidates=12)),
+                  ('paths', lambda: fw.suggest_paths(frame, max_candidates=60))]:
+    start = time.perf_counter()
+    result = run()
+    elapsed = time.perf_counter()-start
+    encoded = json.dumps(result.to_dict(), allow_nan=False).encode()
+    records.append({'operation': name, 'seconds': elapsed, 'result_bytes': len(encoded),
+                    'coverage': result['coverage']})
+args.output.write_text(json.dumps({'rows': args.rows, 'columns': len(frame.columns),
+                                  'results': records}, indent=2)+'\n')
+print(args.output.read_text())

fieldwork-0.1.0/benchmarks/foundation.py

@@ -0,0 +1,125 @@
+"""Reproducible synthetic end-to-end benchmark for the hierarchy explorer."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import platform
+import resource
+import statistics
+import time
+import tracemalloc
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from fieldwork import explore, grain, levels, render_plaintext
+
+
+def fixture(name: str, rows: int, seed: int) -> pd.DataFrame:
+    rng = np.random.default_rng(seed)
+    cardinalities = {
+        "low3": (2, 4, 8),
+        "low6": (4, 4, 4, 4, 4, 4),
+        "high6": (100, 100, 100, 100, 100, 100),
+        "mixed6": (17_000, 50_000, 2, 4, 8, 10_000),
+    }[name]
+    return pd.DataFrame(
+        {
+            f"c{index}": np.char.add("v", rng.integers(0, cardinality, rows).astype(str))
+            for index, cardinality in enumerate(cardinalities)
+        }
+    )
+
+
+def workload(frame: pd.DataFrame, name: str):
+    columns = frame.columns.tolist()
+    if name == "s1":
+        return levels(frame, columns, top_n=5)
+    if name == "s3":
+        return grain(frame, columns[:2])
+    result = explore(
+        frame,
+        columns[:6],
+        candidate_keys=columns[:2],
+        top_n=5,
+        max_nodes=10_000,
+        include_pairs=True,
+    )
+    if name == "render":
+        return render_plaintext(result, max_lines=200)
+    return json.dumps(result.to_dict(), allow_nan=False, separators=(",", ":"))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--suite", default="acceptance", choices=["smoke", "acceptance"])
+    parser.add_argument("--fixture", default="low6", choices=["low3", "low6", "high6", "mixed6"])
+    parser.add_argument("--workload", default="explore", choices=["s1", "s3", "explore", "render"])
+    parser.add_argument("--rows", type=int)
+    parser.add_argument("--seed", type=int, default=721)
+    parser.add_argument("--repeats", type=int, default=7)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    rows = args.rows or (10_000 if args.suite == "smoke" else 150_000)
+    frame = fixture(args.fixture, rows, args.seed)
+    workload(frame, args.workload)  # warmup
+    times = []
+    baseline_rss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    for _ in range(args.repeats):
+        start = time.perf_counter()
+        workload(frame, args.workload)
+        times.append(time.perf_counter() - start)
+    # Allocation tracing is a separate run because it changes timings.
+    tracemalloc.start()
+    traced_output = workload(frame, args.workload)
+    _, traced_peak = tracemalloc.get_traced_memory()
+    peak_rss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    tracemalloc.stop()
+    canonical = (
+        traced_output
+        if isinstance(traced_output, str)
+        else json.dumps(traced_output.to_dict(), allow_nan=False)
+    )
+    record = {
+        "fixture": args.fixture,
+        "workload": args.workload,
+        "rows": rows,
+        "columns": len(frame.columns),
+        "observed_cardinalities": {
+            column: int(frame[column].nunique(dropna=False)) for column in frame.columns
+        },
+        "seed": args.seed,
+        "repeats": args.repeats,
+        "seconds": {
+            "median": statistics.median(times),
+            "minimum": min(times),
+            "maximum": max(times),
+            "spread": max(times) - min(times),
+            "raw": times,
+        },
+        "memory": {
+            "baseline_peak_rss_platform_units": baseline_rss,
+            "absolute_peak_rss_platform_units": peak_rss,
+            "incremental_peak_rss_platform_units": max(0, peak_rss - baseline_rss),
+            "tracemalloc_peak_bytes": traced_peak,
+        },
+        "output_bytes": len(canonical.encode()),
+        "output_sha256": hashlib.sha256(canonical.encode()).hexdigest(),
+        "environment": {
+            "python": platform.python_version(),
+            "platform": platform.platform(),
+            "pandas": pd.__version__,
+            "numpy": np.__version__,
+        },
+    }
+    args.output.mkdir(parents=True, exist_ok=True)
+    destination = args.output / f"{args.fixture}-{args.workload}-{args.seed}.json"
+    destination.write_text(json.dumps(record, indent=2, allow_nan=False) + "\n")
+    print(destination)
+
+
+if __name__ == "__main__":
+    main()

fieldwork-0.1.0/docs/algorithms.md

@@ -0,0 +1,145 @@
+# Discovery algorithms and budgets
+
+## Availability
+
+Features are encoded once per operation. Row presence or explicit any/all entity
+aggregation provides the analysis masks. Repeated boolean availability signatures
+are ranked by descending analysis-unit count with lexical signature ties. `max_signatures=50`
+limits stored signatures, with omitted row mass reported. Identical masks form
+families even for always-missing or always-present columns.
+
+Pairs are enumerated in input-column combination order, bounded by `max_pairs=200`.
+For A and B, presence Jaccard is both-present / either-present. If neither is ever
+present, it is undefined, never perfect similarity. Agreement additionally includes
+co-absence and is reported separately. A implies B has conditional presence
+both-present / A-present, an exception rate, and B's baseline presence. No antecedent
+support means no implication finding. Similarity and implication thresholds default
+to 0.8 and 0.9. Mutually exclusive pairs require each field to have observed support
+and no co-presence; exact families let users interpret exclusive field groups.
+
+Context groups are joint combinations in first-observed order, bounded by
+`max_contexts=32`. Per-feature entity counts operate over all eligible distinct
+keys, without a display truncation affecting their denominator.
+
+## Dependencies and candidate grain
+
+Enumerate determinants by size then input-column order, up to `max_key_size=2` and
+`max_candidates=100`. Report the combinatorial candidate space and tested count.
+Every selected non-key feature is a target; all rows are evaluated. User-specified
+contexts add up to `max_contexts=32` conditional populations plus the global population.
+
+Modal accuracy = 1 − minimum rows needing target-value repair / evaluated rows.
+Within each determinant group, choose its most frequent target; canonical code order
+breaks ties. Nonmodal rows are representative exceptions. Also retain all violating
+groups, affected rows, group violation rate, and repeated-group support. This
+separates approximate mapping quality from coverage and singleton effects.
+`min_accuracy=0.95` controls finding emission, not which tests are computed.
+
+Candidates report groups, uniqueness, repeated groups/rows, complete-case exclusions,
+and exactly determined targets. A unique row ID therefore remains distinguishable
+from a useful repeated entity grouping. Conditional dependencies use their own
+populations. The embedded foundation grain graph admits exact dependencies only,
+collapses equivalent candidates, retains cross-cutting structure, and checks
+population compatibility. Graph work is additionally bounded by the same candidate
+set; pairwise candidate comparisons may dominate runtime.
+
+## Census paths
+
+`max_features=20` bounds the eligible input features (steering columns survive the
+budget), and `max_pairs=200` bounds pair nesting inference. Constants are omitted
+unless required. Equivalent pairs are retained as aliases. If fine determines coarse
+but coarse does not determine fine, the soft nesting edge is coarse → fine.
+
+A deterministic beam search extends ordered prefixes; it defaults to four dimensions,
+beam width 12, 200 evaluated extensions, three returned paths, and display budget 40.
+Input order defines feature coverage; lexical path order breaks score ties. If the
+search budget ends, shorter valid paths may be returned. Coverage records returned
+and requested depth; unsatisfied required columns can yield no recommendation.
+
+For each path, count observed distinct prefixes at every depth. Base score is:
+
+```text
+sum(prefix_counts) / display_budget
++ sum(max(0, prefix_count - display_budget)) / display_budget
++ 2 * redundant_steps
++ 3 * equivalent_pair_steps
+```
+
+A redundant step leaves the prefix count unchanged. Lower scores rank first.
+Structure and context objectives add eight per reversed supported nesting edge.
+Compact uses the base score. Target adds twelve times summed within-prefix modal
+impurity of the target values. Availability adds twelve times the same impurity for
+full boolean signatures. Impurity is rows outside each group's mode / input rows.
+The target itself is excluded from browsing candidates unless explicitly required.
+
+`start_with` fixes the leading dimensions. `before` enforces acyclic precedence and
+includes its referenced features; `exclude` removes candidates. Conflicting or
+unfittable steering raises `ValueError`. Context requires `start_with`; target
+requires `target`. These are observed-prefix heuristics, not an exhaustive optimizer
+or an order-invariant joint-information score.
+
+## Value patterns
+
+String formats replace digit runs with `9` and ASCII letter runs with `A`; report
+three-character prefixes and lengths. `max_patterns=10` bounds displayed counts.
+Indexed-name families are explicitly name evidence, augmented by identical presence
+when observed. Numeric summaries use finite values, observed minimum spacing, and
+an allclose grid check. Offset and ratio checks require at least two finite paired
+rows; ratios exclude zero denominators. Tolerances are rtol 1e-5 and atol 1e-8.
+They are simple measured relationships, not fitted latent models. Context constancy
+reports how many populated context groups have a single populated target value.
+
+### Population-compatible grain views
+
+Discovery builds one view per distinct, nonempty candidate complete-case mask.
+Each view includes candidates whose supported rows contain that mask. The anchor
+candidate guarantees their common complete-case population is exactly that mask;
+the foundation still recomputes and checks every combined relationship on it.
+Views are ordered by descending population, then candidate enumeration order.
+`exact_grain` is the first view; `grain_views` retains every view, candidate IDs,
+source positions and population accounting. No relation is composed across views.
+All candidates remain in `candidates`, with view membership; unsupported candidates
+also appear in `graph_selection.excluded` with `no_evaluated_support`. With
+`dropna=False`, all candidates share the scoped population.
+
+Presentation ranks supported repeated groupings before unique identifiers,
+constants, and candidates without evaluated support. Within each class, more exact
+determined targets and repeated rows rank first, with shorter keys and lexical
+order breaking ties. A one-group candidate is a constant, including a singleton
+population. Ranking changes presentation only; the complete evaluated set remains
+available in enumeration order. Conditional findings carry typed context predicates
+in `structure.context`; readable statements name the feature, value and scalar type.
+Topology retains these predicates while suppressing measurements and selectors.
+
+### Recommendation reasons and diversity
+
+Every path stores `reasons` for observed prefix branching/overflow, supported
+nesting, redundant dimensions and equivalent partitions, and availability
+separation. Target searches also report target separation. Separation is the
+within-prefix nonmodal row fraction at each depth; explanations quote these
+measured values and the actual feature names. Numerical reasons stay in full
+presentations; topology retains only structural path and alias findings.
+
+At each search depth the beam keeps the best order per selected feature set,
+reserving slots for different browsing choices. Future extensions depend on that
+set, while accumulated prefix costs retain the ordering evidence. Returned paths
+also collapse alias substitutions. Fewer than `n_paths` are returned when no
+meaningfully different evaluated feature sets exist; reverse permutations are not
+advertised as alternatives. Explicit start order and precedence remain binding.
+
+### Connected feature evidence
+
+The overview includes value-pattern discovery and a `feature_network` with
+feature nodes, typed relationships, and connected components. Availability
+identity/similarity/implication/exclusion, indexed names, equivalent value
+partitions and exact/approximate dependencies remain separate relationship types.
+A connected component means reachability through this evidence, not equivalence
+or a composed functional dependency. Composite determinants and typed context
+predicates remain explicit. Each relationship links to its section finding,
+overview finding, counting unit and population reference. Pair-specific FD
+populations stay in the referenced finding; the network does not replace the
+compatible exact grain views. `overview.relationships(feature, kinds=[...])`
+returns a dataframe for filtering and following evidence to `inspect`/`select`.
+Saved HTML provides feature disclosures and links to the supporting findings.
+Topology removes evidence pointers and populations while retaining relation types,
+direction and context. Its relationship order is canonical.

fieldwork-0.1.0/docs/architecture.md

@@ -0,0 +1,67 @@
+# Architecture
+
+Fieldwork is a dataframe-in/result-out library. Runtime dependencies are pandas
+and NumPy. Optional rendering tools used by release builds are development
+requirements only. Python 3.11–3.14 are supported, with a committed universal uv lock.
+
+## Follow one investigation
+
+`explore(df)` calls path search, availability analysis, and a bounded single-key
+dependency search, plus bounded value-pattern analysis. It returns an overview containing individual saved results and
+a census preview. Its compact text view presents families, signatures, candidate
+grains and recommended paths together. `explore(df, dimensions)` delegates to the original composition
+API; explicit dimension order remains authoritative. Common context settings are
+applied to a private normalized frame and source accounting is retained in all
+derived scopes; incompatible search options are rejected. `discovery={...}` steers the
+implicit path search; common `features`, `scope`, `missing`, and `table_id` parameters
+also flow into overview evidence.
+
+Discovery modules call `evidence.prepare` to identify the ordered dataset, apply a
+scope, encode values, and compute native/sentinel availability without modifying
+source values. Findings carry table-qualified feature references and bounded source
+positions. Presentation consumes saved evidence, never the original dataframe.
+
+## Module map
+
+| Module | Responsibility |
+| --- | --- |
+| `_explore/encoding.py`, `_kernels.py` | Canonical scalar identity and counting |
+| `_explore/census.py` | Independent levels, bounded ordered observed prefixes |
+| `_explore/grain.py`, `grain_graph.py` | Exact FDs, scope compatibility, equivalence, DAG |
+| `_explore/relations.py`, `roles.py` | Pair contexts/absence, joint counts, schema suggestions |
+| `_explore/result.py`, `resolved.py` | Foundation result model and readable references |
+| `_explore/visual_data.py`, `render.py`, `graphics.py` | Foundation projections and renderers |
+| `evidence.py` | Discovery results, scopes, fingerprints, source inspection |
+| `availability.py` | Presence signatures, families, implications, entity summaries |
+| `discovery.py` | Supplied search bounds, exact/approximate/conditional FDs |
+| `navigation.py` | Deterministic beam search and objective-specific prefix costs |
+| `families.py` | Typed feature relationships linked to section findings |
+| `patterns.py` | Populated strings/numbers, indexed families, context constancy |
+| `workflow.py` | Composition, recipes, delivery comparisons |
+| `presentation.py` | Discovery projections and dispatch to foundation renderers |
+
+## Extension boundaries
+
+New patterns should add named measurements, population accounting, an example
+selection limit, and a presentation test for full and topology exports. Add an
+operation to the explicit Recipe allowlist only when its arguments serialize to
+JSON and can be safely reapplied to a new frame. No arbitrary Python evaluation is
+used for recipes.
+
+Related-table automatic discovery, adaptive branch-specific census orders, cached
+sessions, and external discovery engines remain future extensions. Table identity
+is present in new feature references; foundation references are local to the
+source's `table_id`. The current public APIs analyze one dataframe at a time.
+
+## Extraction
+
+The foundation, regression tests, benchmark and grain example came from bea-tools
+commit `4e4f1704cbca91a314652b0c99f86d8f4a2c4f90`; see `NOTICE`. Imports were
+rewritten, accessors omitted, branding updated, and repeated interpretive disclaimers
+removed. Quantitative evidence, populations, and topology disclosure behavior remain.
+No DICOM, sampling dependencies, or compatibility shims were migrated.
+
+Overview discovery also accepts `by`, `entity`, `unit`, and `entity_presence`.
+Context columns flow to availability, dependency and value-pattern sections.
+Entity settings apply to availability; census path scores and exact/approximate
+value dependencies continue to count rows. Each linked finding identifies its unit.

fieldwork-0.1.0/docs/assets/README.pypi.md

@@ -0,0 +1,62 @@
+# 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.