<commit_before>// Copyright 2015
// Ubiquitous Knowledge Processing (UKP) Lab and FG Language Technology
// Technische Universität Darmstadt
// 
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
// http://www.apache.org/licenses/LICENSE-2.0
// 
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[sect_casdoctor]]
== CAS Doctor

The CAS Doctor is an essential tool while developing WebAnno. When enabled, it checks the CAS for
consistency when loading or saving a CAS. It can also automatically repair inconsistencies when
configured to do so. This section gives an overview of the available checks and repairs.

It is safe to enable any <<sect_checks,checks>>. However, active checks may considerably slow down 
WebAnno, in particular for large documents or for actions that work with many documents, e.g. 
curation or the calculation of agreement. Thus, checks should not be enabled on a production system
unless WebAnno behaves strangely and it is necessary to check the documents for consistency.

Enabling <<sect_repairs,repairs>> should be done with great care as most repairs are performing
destructive actions. Repairs should never be enabled on a production system.

When documents are loaded, CAS Doctor first tries to apply any enabled <<sect_repairs,repairs>>
and afterwards applies enabled <<sect_checks,checks>> to ensure that the potentially repaired
document is consistent.

Additionally, CAS Doctor applies enabled <<sect_checks,checks>> *before* saving a document. This
ensures that a bug in the user interface introduces inconsistencies into the document on disk. I.e.
the consistency of the persisted document is protected! Of course, it requires that relevant checks
have been implemented and are actually enabled.

By default, CAS Doctor generates an exception when a check or repair fails. This ensures that
inconsistencies are contained and do not propagate further. In some cases, e.g. when it is known
that by its nature an inconsistency does not propagate and can be avoided by the user, it may be
convenient to allow the user to continue working with WebAnno while a repair is being developed.
In such a case, CAS Doctor can be configured to be non-fatal. Mind that users can always continue
to work on documents that are consistent. CAS Doctor only prevents loading inconsistent documents
and saving inconsistent documents.

=== Configuration

[cols="4*", options="header"]
|===
| Setting
| Description
| Default
| Example

| debug.casDoctor.fatal
| If the extra checks trigger an exception
| true
| false

| debug.casDoctor.checks
| Extra checks to perform when a CAS is saved (also on load if any repairs are enabled)
| _unset_
| see <<sect_checks>>

| debug.casDoctor.repairs
| Repairs to be performed when a CAS is loaded
| _unset_
| see <<sect_repairs>>
|===

[[sect_checks]]
=== Checks

[[check_AllFeatureStructuresIndexedCheck]]
==== All Feature Structures Indexed

[horizontal]
ID:: `AllFeatureStructuresIndexedCheck`
Related repairs:: <<repair_RemoveDanglingChainLinksRepair>>, <<repair_RemoveDanglingRelationsRepair>>
<commit_msg>#375 - Proper CAS Doctor documentation in developer guide<commit_after>// Copyright 2015
// Ubiquitous Knowledge Processing (UKP) Lab and FG Language Technology
// Technische Universität Darmstadt
// 
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
// http://www.apache.org/licenses/LICENSE-2.0
// 
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[sect_casdoctor]]
== CAS Doctor

The CAS Doctor is an essential tool while developing WebAnno. When enabled, it checks the CAS for
consistency when loading or saving a CAS. It can also automatically repair inconsistencies when
configured to do so. This section gives an overview of the available checks and repairs.

It is safe to enable any <<sect_checks,checks>>. However, active checks may considerably slow down 
WebAnno, in particular for large documents or for actions that work with many documents, e.g. 
curation or the calculation of agreement. Thus, checks should not be enabled on a production system
unless WebAnno behaves strangely and it is necessary to check the documents for consistency.

Enabling <<sect_repairs,repairs>> should be done with great care as most repairs are performing
destructive actions. Repairs should never be enabled on a production system.

When documents are loaded, CAS Doctor first tries to apply any enabled <<sect_repairs,repairs>>
and afterwards applies enabled <<sect_checks,checks>> to ensure that the potentially repaired
document is consistent.

Additionally, CAS Doctor applies enabled <<sect_checks,checks>> *before* saving a document. This
ensures that a bug in the user interface introduces inconsistencies into the document on disk. I.e.
the consistency of the persisted document is protected! Of course, it requires that relevant checks
have been implemented and are actually enabled.

By default, CAS Doctor generates an exception when a check or repair fails. This ensures that
inconsistencies are contained and do not propagate further. In some cases, e.g. when it is known
that by its nature an inconsistency does not propagate and can be avoided by the user, it may be
convenient to allow the user to continue working with WebAnno while a repair is being developed.
In such a case, CAS Doctor can be configured to be non-fatal. Mind that users can always continue
to work on documents that are consistent. CAS Doctor only prevents loading inconsistent documents
and saving inconsistent documents.

=== Configuration

[cols="4*", options="header"]
|===
| Setting
| Description
| Default
| Example

| debug.casDoctor.fatal
| If the extra checks trigger an exception
| true
| false

| debug.casDoctor.checks
| Extra checks to perform when a CAS is saved (also on load if any repairs are enabled)
| _unset_
| comma-separated list of <<sect_checks,checks>>

| debug.casDoctor.repairs
| Repairs to be performed when a CAS is loaded
| _unset_
| comma-separated list of <<sect_repairs,repairs>>
|===

[[sect_checks]]
=== Checks

[[check_AllFeatureStructuresIndexedCheck]]
==== All Feature Structures Indexed

[horizontal]
ID:: `AllFeatureStructuresIndexedCheck`
Related repairs:: <<repair_RemoveDanglingChainLinksRepair>>, <<repair_RemoveDanglingRelationsRepair>>

{'fraction_non_alphanumeric': 0.06217175301632363, 'fraction_numerical': 0.0029808374733853796, 'mean_word_length': 4.803953871499176, 'pattern_counts': {'":': 0, '<': 39, '<?xml version=': 0, '>': 39, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1790421', 'n_tokens_mistral': 1820, 'n_tokens_neox': 1695, 'n_words': 949}