# Transects#

For many use cases, a user may require to extract velocities over a certain transect. The most famous application for
this is measuring river flow. *pyorc* is equipped with very smart approaches to extract a transect, interpolate
missing values that may appear on the transect, and extracting cross-section cubic meter per second river flow estimates
with confidence intervals based on temporal variations in velocities. It is highly recommended to consider applying
masks on your results before extracting velocities and flow over transects.

## Extracting a transect#

The starting point for a transect is always a velocimetry result, containing surface velocities, gridded in space and
time and a set of coordinates of a cross section, measured in the same coordinate reference system as the ground control
points and using also the same vertical datum as the measurement of the control video water level (`z_0`

in the
camera configuration).

Transects can be derived by supplying a `transect`

section in your recipe. Under this section, one or several
transects can be derived, by supplying the path to a shapefile or geojson file, that contains x, y, z Point
coordinates of the measured cross section as well as the coordinate reference system of the coordinates.
Any metadata or properties are not used. These files are typical outputs of GNSS equipment and can one on
one be passed onto *pyorc* unless you wish to remove some wrong points, or points that belong to another survey.

The approach is best explained with an example `transect`

section for one transect, with some comments

```
# we start our transect section
transect:
# extracted transects will be written to disk
write: True
# we have measured one cross section in the Ngwerere river in Lusaka - Zambia
ngwerere_1:
# path to the shapefile or geojson, containing our points
shapefile: ../examples/ngwerere/cross_section1.geojson
# supply some extra arguments to get_transect (if not provided, defaults will be used)
get_transect:
# we do a rolling mean over time to smooth out small fps changes of the camera
rolling: 4
# we sample velocity by averaging in a one-sided window size of 2 (5x5)
wdw: 2
# let's derive depth integrated velocity also
get_q:
# we fill missing with a log interpolation method
fill_method: log_interp
# assume depth averaged velocity is 0.85 * surface velocity
v_corr: 0.85
# integrate to m3/s river flow without additional arguments
get_river_flow:
```

If `get_transect`

is not supplied in the command-line recipe then default parameters will be used. When
`write: True`

is provided, the resulting extracted velocities and flow will be written to a file in the
output folder. This file will have the following naming convention: `transect_<name>.nc`

. From the example
above the file would be called `transect_ngwerere_1.nc`

.

You may load x, y, z points from a shapefile or csv file with `pandas`

or `geopandas`

. Then these can be
supplied with a velocimetry result, using the `get_transect`

method. Below a full working example is given, based
on our Ngwerere example dataset.

```
cross_section = pd.read_csv("ngwerere/ngwerere_cross_section.csv")
# the points are assigned to numpy arrays, coordinates are in crs 32735
x = cross_section["x"]
y = cross_section["y"]
z = cross_section["z"]
# extract points, ensuring pyorc knows their projection is 32735.
ds_points = ds.velocimetry.get_transect(x, y, z, crs=32735, rolling=4)
# add depth averaged velocity, filling missings and assuming a average velocity / surface velocity of 0.85
ds_points_q = ds_points.transect.get_q(fill_method="log_interp", v_corr: 0.85)
# finally, obtain cross sectional river flow (added as variable ["river_flow"])
ds_points_q.transect.get_river_flow()
print(ds_points_q["river_flow"])
```

The `get_transect`

method derives the transect from our gridded velocimetry results. Many options
may be supplied to improve sampling. For instance, if flow has a highly predominant direction, then it makes
sense to increase sampling over a longer longitudinal window, and reduce sampling in perpendicular direction.
This can be controlled by arguments `wdw_x_min`

, `wdw_x_max`

, `wdw_y_min`

and `wdw_y_max`

.
There are also options to refine or coarsen the sampling interval over space (`distance`

) as well as an option to
discard values if not enough valid (i.e. non masked) values in the sampled neighbourhood are found (`tolerance`

).
For a full list of parameters, please investigate the API documentation. `get_q`

and `get_river_flow`

are not
mandatory to use, but recommended if river flow is the required variable of interest. Since river flow requires
estimates of velocities without any gaps, fill methods are available that can be applied before the depth averaged
velocity is derived. The relevant API pages that describe the possible input arguments for both are described
here. Stored results in a NetCDF structure will contain the following variables:

`v_eff_nofill`

: the effective velocities per point in the cross section [m/s]`v_eff`

: if`get_q`

is supplied, this will contain velocities, with gaps filled with a selected filling method within the`get_q`

method.`v_dir`

: the direction of the velocity per point in the cross section determined as the perpendicular direction of the supplied cross section. Note that if the cross section is not entirely straight, this may vary from point to point.`q_nofill`

: depth integrated velocity [m2/s], using a correction factor supplied with`v_corr`

(default: 0.9)`q`

: same as`v_eff`

but then for depth integrated velocity.`river_flow`

: available when both`get_q`

and`get_river_flow`

are applied. This variable contains the river flow in m3/s.

In the processing to transects, the `time`

dimension will be replaced by a `quantile`

dimension. By default 5
quantiles are derived (0.05, 0.25, 0.5, 0.75, and 0.95) for each point in the transect based on the time variability of
the extracted velocities. These quantiles allow you to estimate the variance of the velocities. A very high variance
may indicate more uncertainty. Note that this variance is also integrated into the `river_flow`

variable, assuming the
variability is entirely correlated in space. This is likely not to be true, especially if variances are caused by
remaining variability in the frames-per-second of the camera, hence the confidence intervals of the `river_flow`

variable should be interpreted as highly conservative.