FHOPS handoff
.. py:module:: nemora.export
Export adapters for external consumers.
The FHOPS adapter writes a standalone individual-tree inventory. It does not import FHOPS or create a FHOPS scenario; FHOPS remains a consumer of the exported contract.
.. py:class:: FhopsTreeExport(inventory_path, metadata_path, inventory_sha256, tree_count, block_id) :module: nemora.export
Bases: :py:class:object
Paths and provenance for one FHOPS tree-inventory export.
.. py:attribute:: FhopsTreeExport.block_id :module: nemora.export :type: str
.. py:attribute:: FhopsTreeExport.inventory_path :module: nemora.export :type: ~pathlib.Path
.. py:attribute:: FhopsTreeExport.inventory_sha256 :module: nemora.export :type: str
.. py:attribute:: FhopsTreeExport.metadata_path :module: nemora.export :type: ~pathlib.Path
.. py:method:: FhopsTreeExport.to_dict() :module: nemora.export
Return a JSON-serializable export summary.
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`
.. py:attribute:: FhopsTreeExport.tree_count :module: nemora.export :type: int
.. py:function:: export_fhops_tree_inventory(trees, output_dir, *, block_id=’GAVIN_EMPIRICAL’, inventory_id=’nemora-phase9-gavin-empirical’, crs=’EPSG:3005’, origin_x=0.0, origin_y=0.0, size_m=100.0, seed=20261030, producer=’Nemora’, method=’Plot-conditioned empirical resampling; synthetic placement.’, source_id=’bc-faib-psp’, caveats=(‘Synthetic plot-conditioned tree inventory; not a surveyed stand or real tree map.’, ‘Coordinates are deterministic synthetic placement inside a one-hectare block context.’)) :module: nemora.export
Write a FHOPS fhops.tree.inventory.v1 CSV and metadata file.
:type trees: :sphinx_autodoc_typehints_type:\:py\:class\:\~pandas.DataFrame` :param trees: Synthetic tree rows with ``tree_id``, ``species_code``, ``dbh_cm``, and ``height_m``. Extra columns are ignored. :type output_dir: :sphinx_autodoc_typehints_type::py:class:`str` | :py:class:`~pathlib.Path` :param output_dir: Directory for ``tree_inventory.csv`` and ``tree_inventory.meta.json``. :type block_id: :sphinx_autodoc_typehints_type::py:class:`str` :param block_id: FHOPS block identifier. :type inventory_id: :sphinx_autodoc_typehints_type::py:class:`str` :param inventory_id: Stable inventory identifier. :type crs: :sphinx_autodoc_typehints_type::py:class:`str` :param crs: CRS label for the synthetic coordinates. :type origin_x: :sphinx_autodoc_typehints_type::py:class:`float` :param origin_x: Synthetic square block context in the export CRS. :type origin_y: :sphinx_autodoc_typehints_type::py:class:`float` :param origin_y: Synthetic square block context in the export CRS. :type size_m: :sphinx_autodoc_typehints_type::py:class:`float` :param size_m: Synthetic square block context in the export CRS. :type seed: :sphinx_autodoc_typehints_type::py:class:`int` :param seed: Deterministic placement seed. :type producer: :sphinx_autodoc_typehints_type::py:class:`str` :param producer: Provenance fields written to the metadata. :type method: :sphinx_autodoc_typehints_type::py:class:`str` :param method: Provenance fields written to the metadata. :type source_id: :sphinx_autodoc_typehints_type::py:class:`str` :param source_id: Provenance fields written to the metadata. :type caveats: :sphinx_autodoc_typehints_type::py:class:`tuple`\ \[:py:class:`str`, :py:data:`…<Ellipsis>`]`
:param caveats: Provenance fields written to the metadata.
:raises KeyError: If a required tree column is missing.
:raises ValueError: If the input is empty or size_m is not positive.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.export.FhopsTreeExport``
.. py:module:: nemora.fhops_handoff
Register a FHOPS scenario against an exported tree inventory.
This is an external handoff adapter. It writes FHOPS scenario metadata and checksums without importing FHOPS or changing its core.
.. py:class:: FhopsScenarioRegistration(scenario_path, inventory_path, metadata_path, inventory_sha256, metadata_sha256, block_id, work_required_m3) :module: nemora.fhops_handoff
Bases: :py:class:object
Paths and checksums for a registered FHOPS scenario.
.. py:attribute:: FhopsScenarioRegistration.block_id :module: nemora.fhops_handoff :type: str
.. py:attribute:: FhopsScenarioRegistration.inventory_path :module: nemora.fhops_handoff :type: ~pathlib.Path
.. py:attribute:: FhopsScenarioRegistration.inventory_sha256 :module: nemora.fhops_handoff :type: str
.. py:attribute:: FhopsScenarioRegistration.metadata_path :module: nemora.fhops_handoff :type: ~pathlib.Path
.. py:attribute:: FhopsScenarioRegistration.metadata_sha256 :module: nemora.fhops_handoff :type: str
.. py:attribute:: FhopsScenarioRegistration.scenario_path :module: nemora.fhops_handoff :type: ~pathlib.Path
.. py:method:: FhopsScenarioRegistration.to_dict() :module: nemora.fhops_handoff
Return a JSON-serializable summary.
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`
.. py:attribute:: FhopsScenarioRegistration.work_required_m3 :module: nemora.fhops_handoff :type: float | None
.. py:function:: register_fhops_scenario(scenario_template, output_dir, inventory_dir, *, block_id=’B01’, work_required_m3=None) :module: nemora.fhops_handoff
Copy a scenario template and pin an exported tree inventory.
:type scenario_template: :sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:class:`~pathlib.Path` :param scenario_template: Directory containing ``scenario.yaml`` and its ``data/`` files. :type output_dir: :sphinx_autodoc_typehints_type::py:class:`str` | :py:class:`~pathlib.Path` :param output_dir: Destination scenario directory. It is replaced if it exists. :type inventory_dir: :sphinx_autodoc_typehints_type::py:class:`str` | :py:class:`~pathlib.Path` :param inventory_dir: Directory containing ``tree_inventory.csv`` and ``tree_inventory.meta.json``. :type block_id: :sphinx_autodoc_typehints_type::py:class:`str` :param block_id: FHOPS block to reconcile in ``data/blocks.csv``. :type work_required_m3: :sphinx_autodoc_typehints_type::py:class:`float` | :py:obj:`None``
:param work_required_m3: Optional replacement for the block’s work_required value.
:returns: Registered paths and checksums. :rtype: FhopsScenarioRegistration
:raises FileNotFoundError: If an expected input file is missing. :raises ValueError: If the inventory metadata is inconsistent or the block is absent.
.. py:function:: validate_fhops_scenario_pin(scenario_path) :module: nemora.fhops_handoff
Return whether a scenario’s tree inventory pin matches its files.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\bool``
.. py:module:: nemora.yield_check
Independent inventory-volume checks for FHOPS handoff scenarios.
The estimator is deliberately simple and transparent. It is not a taper model and must not be treated as an operational yield estimate.
.. py:class:: InventoryVolumeEstimate(tree_count, total_volume_m3, mean_volume_m3, merchantable_height_ratio, form_factor, formula) :module: nemora.yield_check
Bases: :py:class:object
Independent volume estimate for a tree inventory.
.. py:attribute:: InventoryVolumeEstimate.form_factor :module: nemora.yield_check :type: float
.. py:attribute:: InventoryVolumeEstimate.formula :module: nemora.yield_check :type: str
.. py:attribute:: InventoryVolumeEstimate.mean_volume_m3 :module: nemora.yield_check :type: float
.. py:attribute:: InventoryVolumeEstimate.merchantable_height_ratio :module: nemora.yield_check :type: float
.. py:method:: InventoryVolumeEstimate.to_dict() :module: nemora.yield_check
Return a JSON-serializable summary.
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`object\`\]`
.. py:attribute:: InventoryVolumeEstimate.total_volume_m3 :module: nemora.yield_check :type: float
.. py:attribute:: InventoryVolumeEstimate.tree_count :module: nemora.yield_check :type: int
.. py:function:: compare_volume_estimates(estimate_m3, *, registered_work_required_m3=None, fhops_processed_m3=None) :module: nemora.yield_check
Compare independent, registered, and FHOPS-processed volumes.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\dict`\ \[:py:class:`str`, :py:data:`~typing.Any`]`
.. py:function:: estimate_inventory_volume(trees, *, merchantable_height_ratio=0.7, form_factor=0.5) :module: nemora.yield_check
Estimate total volume for a tree table with dbh_cm and height_m.
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\~nemora.yield_check.InventoryVolumeEstimate``
.. py:function:: estimate_tree_volume_m3(dbh_cm, height_m, *, merchantable_height_m=None, merchantable_height_ratio=0.7, form_factor=0.5) :module: nemora.yield_check
Estimate one tree’s volume with a paraboloid-style formula.
V = pi/4 * D^2 * H_m * form_factor with D in metres. The default
merchantable height is 70% of total height and the default form factor is
0.5. This is an independent check, not a taper model.
:raises ValueError: If inputs are non-finite, non-positive, or outside (0, 1].
:rtype: :sphinx_autodoc_typehints_type:\:py\:class\:\float``
See also
docs/howto/fhops_handoff.mdfor the export, registration, and run workflow.