Reporting a problem without sharing your data#

A public post, such as an issue or a forum question, cannot be fully taken back. Ingence’s output is made from your folders, so a report can easily contain your lab’s names. This page shows how to report a bug or a misread file without them.

If a problem cannot be shown without your data, email it privately to hello@ingence.org instead of posting it.

What Ingence’s output contains#

  • The Dashboard shows file and folder names, paths, people’s names found in folders, dates, and short extracts read from inside files. A screenshot of it shows all of these.

  • Messages in the terminal can contain a path. ingence fix -p PROJECT prints the project’s path and run identifiers as they are, followed by counts. It prints a root’s path only when a root cannot be reached. Under “left out, on purpose” it lists what the census skipped, and that can name folders.

  • ingence export themes writes folder and person names in plain text.

  • The project folder holds the Index, which lists every path and name Ingence read, and the Record, which holds your answers and your name. Do not post it or a zipped copy.

  • Counts show how large a lab or a folder is.

ingence teach shapes is the exception. It prints the shapes of your names and not the names.

Replace names with their shape#

The shape of a name is what is left when you replace each part that is yours by what kind of part it is. Words that every lab uses, such as HeLa, DAPI and DMSO, can stay. Replace people’s names, project codes and anything that identifies unpublished work.

Real name

Shape

Okafor_Atlas_HeLa_03.tif

<person>_<project>_HeLa_<number>.tif

2023-03-14_Atlas_DAPI

<date>_<project>_DAPI

Priya/

<person>/

Use the same stand-in for the same part every time, so a reader can see which names match.

ingence teach shapes does this for every name in a project. Index the folder first, then ask for the shapes:

ingence index -p PROJECT
ingence teach shapes -p PROJECT

For the practice folder below, it prints this table, where entries is how many names have the shape and slots is how many parts the shape has:

entries  slots  skeleton
      6      4  {WORD}_{WORD}_{NUMBER}.{format}
      3      1  {stage}
      2      1  {WORD}
      1      3  {DATE}_{WORD}_{WORD}
      1      4  {DATE}_{WORD}_{WORD}_{version}
      1      3  {WORD}_{stage}.{format}

A word that Ingence knows appears as its kind, such as {stage} for raw or analysis. A word it does not know appears as {WORD}, and numbers and dates as {NUMBER} and {DATE}. No name is printed. The line under the table counts the parts of names Ingence read. --out FILE writes every shape as a CSV file. Read the output before you post it. If the size of your lab matters, change the counts to “a few” or “many”.

Share the output of ingence fix#

To report what ingence fix found, run it with --shareable and paste its output:

ingence fix -p PROJECT --shareable

It prints the same report, with the project written <project>, each root <root 1>, <root 2>, each exclusion pattern you wrote <pattern 1> and each run <run 1>. A value you typed into an older project’s rules file is also written <pattern 1>. It holds no file or folder name from your data. Counts, versions and the time of the last run stay. With --verify, the sample rows are left out and the number of differing rows stays. Read it once before you post it.

What to include#

  1. The version. Run ingence --version and paste the first line it prints.

  2. Your system. The operating system and its version, whether the processor is Intel or Apple silicon, the Python version, and how you installed Ingence.

  3. The command you ran, with every path replaced: ingence index -p PROJECT, not the path you typed.

  4. What you expected and what happened instead.

  5. The message, if there was one, with every path, folder name and person’s name in it replaced by a stand-in such as <root>, <project> or <file>.

  6. The shape of your names, from ingence teach shapes, and the shape of your folders in words (below).

  7. For a conclusion you think is wrong, the rule’s name and version. Open the file in the Dashboard: each conclusion about it shows the rule that made it. Also say what is true and how you know. The signs a person would use (a word in a name, a place in a folder, a date) help most.

Describe the folders in words, with stand-ins:

<root>/
  <person>/                        one folder per person
    2023-03-14_<project>_HeLa/     an experiment: a date, a project code and a cell line
      raw/                         three images, <project>_HeLa_01.tif to <project>_HeLa_03.tif
      analysis/                    a summary table and a script
    2023-03-14_<project>_HeLa_old/ the raw folder copied by hand into a folder with _old added

Make a small folder that shows it#

The best report comes with a made-up folder that shows the same problem. Make one from empty files with invented names:

mkdir -p practice/Priya/2023-03-14_Atlas_HeLa/raw practice/Priya/2023-03-14_Atlas_HeLa/analysis
touch practice/Priya/2023-03-14_Atlas_HeLa/raw/Atlas_HeLa_0{1,2,3}.tif
touch practice/Priya/2023-03-14_Atlas_HeLa/analysis/Atlas_summary.csv
mkdir practice/Priya/2023-03-14_Atlas_HeLa_old
cp -R practice/Priya/2023-03-14_Atlas_HeLa/raw practice/Priya/2023-03-14_Atlas_HeLa_old/

On Windows, make the same folders and empty files in File Explorer, or with New-Item in PowerShell. Then read it with a project of its own, apart from your real ones:

ingence init report-project --root practice
ingence index -p report-project
ingence infer -p report-project

If the problem appears on the made-up folder, paste the commands you ran and the list of its files and folders. Anyone can then run exactly what you ran.

An empty file is enough for anything that depends on names, folders and dates. A problem about sizes or copies needs files that hold a few different characters each. A problem that depends on what is inside a file needs a made-up file with the same structure and invented values.

What not to post#

  • Paths, folder names, people’s names and names of unpublished work, in any form: text, a screenshot, a log or a file name.

  • A screenshot of the Dashboard or the terminal, unless you have covered every name in it.

  • The project folder, or a zipped copy of it (Privacy and your data).

  • The output of ingence fix -p PROJECT as it stands. Replace the project path, the run identifiers, any root path and every folder named under “left out, on purpose”, and describe the counts.

  • The files ingence export themes writes. They hold folder and person names in plain text.

Where to report it#

Write to hello@ingence.org and say which kind of problem it is (Community).

  • Bug: something is broken, crashes or does something that looks wrong.

  • A rule misread my files: a conclusion is wrong, or one that should have been reached was not.

  • A word Ingence does not know: a general word in names that Ingence does not read. A word only your lab uses belongs in your own project, or in a pack of your own.

  • Pack submission: you want to offer a pack of words.

  • Documentation: a page is wrong, unclear or missing.

Questions such as “how do I…?” go to the same address. A security problem is reported privately: write to it and say that it is one. Private reports may contain lab data.

If you pasted something by mistake#

Edit the post to take it out. Then add a short comment, without repeating the text, asking a maintainer to delete the post’s edit history, which keeps the earlier version. Do the same for an issue or a pull request.